Configuring Agent Deployments

Agents, versions, and the stable endpoint

A model deployment answers prompts. An agent deployment has to answer a harder question: when you change the agent, what do your users get, and when?

A Foundry project is a folder that groups related resources such as agents, files, and tools. An agent version is an immutable record of the agent's configuration, and any change, even a single prompt edit, creates a new version. The agent is the stable, consumer-facing representation: its identity, endpoint, and authorization surface stay consistent as its underlying versions evolve.

The agent endpoint is the URL consumers call to invoke the agent. It's live the moment you create the agent, with no separate publish step, and the URL doesn't change as you roll out new versions. You configure which version it serves, which protocols it speaks, and how callers authenticate.

Keep the four objects apart:

So an edit never rewrites what is already running. It adds a version, and a separate setting decides whether that version gets traffic.

Choosing which version receives traffic

The agent's version_selector determines how traffic routes to agent versions. With Always use latest, the default, 100% of traffic routes to the most recently created agent version, so a newly created version is immediately served. When pinned to a specific version, 100% of traffic routes to the version you select, called the active agent version, and new versions don't change what's served until you update the selector.

Pin to a specific version when you need stability across new versions, such as when an agent is in production or published to end users in Teams or Microsoft 365. There's no traffic splitting: only one agent version can be active and receive traffic at a time.

In the portal, you pin a version from the Publish dropdown. In code, you send PATCH /agents/{agent_name} with a FixedRatio rule at 100 percent, or, in Python, call project_client.agents.update_details on an AIProjectClient from the azure.ai.projects package, passing an AgentEndpointConfig whose VersionSelector holds a FixedRatioVersionSelectionRule.

In plain words, the Python call says: for this agent, route one hundred percent of traffic to version two.

Protocols and authorization schemes

The endpoint can speak several languages at once, and each audience needs the right one. An agent can expose multiple protocols simultaneously: Responses, Activity Protocol, Invocations, A2A, and MCP (preview). The Activity Protocol is the one used by Azure Bot Service. A2A supports agent-to-agent delegation, and an agent card surfaces the agent's details and capabilities to consumers, including for A2A discovery.

By default, the Responses protocol is enabled and authorization is set to Entra. Protocols and authorization schemes aren't yet configurable in the Foundry portal, so you use the REST API or the SDK.

Three authorization schemes decide who may call:

• With the Entra scheme, the caller must have the Foundry Agent Consumer role, or higher, such as Foundry User, on the Foundry project or agent scope. Principals that only interact with agents, without creating or editing them, should use the Foundry Agent Consumer role.
• BotServiceRbac combines Azure Bot Service channel authorization with Azure RBAC, while BotServiceTenant lets anyone in your tenant invoke the agent.

An agent published to Microsoft 365 or Teams must have the Activity protocol enabled and use a BotServiceRbac or BotServiceTenant authorization scheme. API key authentication isn't supported: use Microsoft Entra ID (Azure RBAC) to authorize callers.

Publishing to Teams from a private network

A common enterprise case: the Foundry account has public network access turned off, yet the agent must appear in Teams.

If your project disables public network access, set enable_m365_public_endpoint to true inside the activity protocol configuration before you publish the agent to Microsoft Copilot or Teams. Foundry applies this network exception only to the Activity Protocol route, so other agent protocols and project APIs remain private. Microsoft 365 doesn't support private network connectivity for agents and requires the endpoints it invokes to be routable over the public internet.

Service-managed source IP filtering allows requests delivered through Azure Bot Service or Microsoft 365 infrastructure, and you don't need to change the account's network settings or configure public ingress in your virtual network. Network restrictions don't replace authorization, so keep BotServiceRbac or BotServiceTenant configured.

One more trap: because that PATCH replaces protocol_configuration and authorization_schemes, include every protocol and authorization scheme that the endpoint must retain. Sending only the activity block would silently drop Responses and Entra.

The legacy Agent Application model

You will still meet the older way to share an agent. Publishing an agent as an Agent Application is the legacy publishing experience. Publishing creates an Agent Application resource with its own invocation URL, authentication policy, unique Entra agent identity, and unique Entra agent blueprint, plus a deployment child resource that references the agent version and supports start and stop. Publishing requires the Foundry Project Manager role on the Foundry resource scope.

In the legacy model, the deployment type is Managed for prompt agents and Hosted for hosted agents, and only hosted deployments take minReplicas and maxReplicas.

The identity change is what breaks things after publishing. Because the identity changes, permissions don't transfer automatically: you must reassign RBAC permissions to the new agent identity, or tool calls that worked during development fail with authorization errors.

Callers need the Foundry User role on the Agent Application resource, because the Foundry Agent Consumer role doesn't grant access to invoke Agent Applications. An Agent Application can use either Responses or Activity Protocol, one at a time. With Responses, it supports only the stateless POST /responses call, so the client must store conversation history for multi-turn conversations.

Hosted agents: when and how

Prompt agents cover most needs. Hosted agents exist for the cases where you need your own code.

Hosted agents are your own code packaged as a container image, unlike prompt-based agents, which are defined entirely through prompts and tool configuration. Choose them when you need to bring your own code or framework, accept webhooks or non-OpenAI payloads through the Invocations protocol, control CPU and memory, run stateful workloads, or run long-lived work resiliently. You push the image to Azure Container Registry, and at deployment Agent Service pulls it, assigns a dedicated Microsoft Entra agent identity, and exposes a dedicated endpoint.

The Responses protocol lets the platform manage conversation history, while Invocations accepts arbitrary JSON and leaves session management to your code. If you aren't sure, start with Responses, because a hosted agent can support both protocols simultaneously.

Hosted agent versions, sessions, and sizing

Each version is an immutable record of the container image, resource allocation, environment variables, and protocol configuration, so to update your agent you create and deploy a new version. Hosted agents run in per-session, VM-isolated sandboxes, and the idle timeout can be 2 through 60 minutes, with a 15-minute default.

Sandbox sizes are 0.5 vCPU with 1 GiB, 1 vCPU with 2 GiB, or 2 vCPU with 4 GiB.

The cost model surprises people. The CPU and memory you set describe a single session, and billing is based on CPU and memory consumed across all active sessions, so oversizing multiplies cost by your concurrency. Hosted agents scale per session, not per replica, so there's no replica count to configure. Don't put secrets in container images or environment variables.

A worked example: a version sized at 2 vCPU that never uses more than a fraction of it, running two hundred concurrent sessions, pays for that unused headroom two hundred times. The fix is a new version at a smaller size, retested under the same load.