Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Prompt agents in Microsoft Foundry Agent Service are declaratively defined agents for text interactions. You configure a model, instructions, and tools, and Foundry runs the agent for you. You don't write or operate the orchestration code, package a container, or manage compute.
This article covers text prompt agents. For real-time spoken interactions, see Create a voice-based prompt agent.
When to use prompt agents
Use a prompt agent when you want to:
- Build without deploying application code or infrastructure.
- Define agent behavior through instructions and model selection, then attach supported tools, skills, and toolboxes.
- Create and test the agent in the Foundry portal, or manage its definition through an SDK, the REST API, or the Azure Developer CLI (
azd). - Give applications a stable agent endpoint while Foundry manages agent versions, conversations, identity, tracing, and scaling.
- Optionally use the Microsoft Copilot harness for supported multi-step tool, skill, file, and command workflows without operating harness code.
Use a Hosted agent instead when you need to bring your own framework or orchestration code, add custom middleware or protocols, control runtime dependencies or compute resources, or manage the process model.
If your application already owns the agent definition and doesn't need a saved agent resource, call the Responses API directly. This ephemeral pattern lets the application change the model, instructions, and tools on each request, but it doesn't support features that require a saved prompt agent, such as the Copilot harness or prompt-agent optimization.
How prompt agents work
A saved prompt agent is a versioned resource in a Foundry project. Its definition contains the model, instructions, tools, and other supported settings. Saving a change creates a new version and preserves the definition as part of the agent's version history.
When an application or the playground invokes a prompt agent:
- The client sends input to the prompt agent's Responses endpoint.
- Foundry uses the saved agent definition and routes the request to the selected runtime.
- The runtime coordinates the model and configured tools. It can make multiple model and tool calls to complete the request.
- Foundry returns the completed response, records traces for the request, and appends the response items to the conversation when one is used.
The runtime that coordinates these steps depends on whether you select the optional Copilot harness when you create the agent.
Choose a managed agent runtime
Foundry operates the prompt-agent runtime. When you create the agent, you can keep the default prompt-agent behavior or select the Copilot harness (preview). In either case, the resource remains a prompt agent and applications invoke it through the Responses API.
| Choice | Use it when | Runtime behavior |
|---|---|---|
| Default prompt-agent behavior | You want the simplest runtime configuration for instructions, model calls, and supported Foundry tools. You don't need the harness workspace or its built-in file, shell, web-fetch, and subagent capabilities. | Foundry coordinates the model and tools declared in the prompt-agent definition. |
| Copilot harness (preview) | You need multi-step tool, skill, file, or command workflows and want Foundry to operate the harness and its execution environment. | The harness coordinates the model and supported capabilities. It can provide built-in file-system, shell, web-fetch, and subagent tools in addition to compatible declared tools and skills. |
Foundry operates the Copilot harness and its execution environment.
The harness choice doesn't change the agent type, endpoint, project roles, or supported governance controls. It does affect the runtime capabilities and some request and tool constraints. During the initial public preview:
- Select the harness only when you create the prompt agent. To change the choice, create another agent.
- Use a first-class conversation for every response.
- Confirm that your project region, model, and tools support the harness.
- Review the built-in harness tools before enabling broad capabilities such as shell commands.
For the current setup, tools, file behavior, security guidance, and limitations, see Use the Copilot harness with prompt agents and Quotas, limits, and regional support.
Define a prompt agent
A prompt-agent definition brings together these parts. Tool, skill, and toolbox availability depends on the selected runtime and capability.
| Part | Purpose |
|---|---|
| Model | Provides the agent's reasoning and language capabilities. Model support can vary by region and tool. |
| Instructions | Describe the agent's role, behavior, boundaries, and expected output. |
| Tools | Let the agent retrieve information or take actions. Examples include web search, file search, Code Interpreter, function calling, and Model Context Protocol (MCP) servers. |
| Skills | Package reusable instructions, scripts, and resources that an agent can use for a specialized task. |
| Toolboxes | Group reusable tools behind a managed MCP-compatible endpoint with centralized authentication, governance, and versioning. |
| Harness choice | Keeps the default prompt-agent behavior or selects the Copilot harness when the agent is created. |
Connections and Microsoft Entra roles control access to tools and downstream resources. Use the narrowest permissions that the agent needs. Some operations, such as returning a file generated by the Copilot harness, require a role assignment for the agent identity in addition to the role held by the person creating the agent.
Build and operate a prompt agent
Choose the authoring path that fits how your team works:
- Foundry portal: Create and test an agent interactively, then save a new version when you change its model, instructions, tools, or skills.
- SDK or REST API: Manage the agent definition from application or deployment code.
- Azure Developer CLI: Store the agent definition in
azure.yaml, deploy it withazd, and inspect the persisted definition after deployment.
After you create or update the agent, test a multi-turn conversation, inspect traces for model and tool activity, evaluate representative tasks, and grant the agent identity only the resource permissions that it needs. For the complete lifecycle, see Agent development lifecycle.
Get started
| Goal | Article |
|---|---|
| Create a prompt agent with an SDK or the REST API | Quickstart: Create a prompt agent |
| Create a prompt agent with the Copilot harness | Quickstart: Create a web research agent |
| Configure harness tools, Foundry tools, toolboxes, and skills | Use the Copilot harness with prompt agents |
| Configure a saved agent | Configure an agent |
| Compare prompt, voice, hosted, and ephemeral approaches | Agents in Microsoft Foundry |