Configure and share your Microsoft Foundry agent

Learn how to configure your agent’s stable endpoint, select the active version, and share your agent with consumers in Microsoft Foundry.

Every agent in Microsoft Foundry has a stable endpoint from the moment it’s created. Behind each endpoint, a Foundry model processes user input according to the agent’s instructions and tools. When end users interact with your agent through Microsoft 365 Copilot, Teams, your existing application, or other surfaces, they interact with the agent’s stable endpoint. Before you share your agent, verify these settings:

• Active agent version — Confirm the version that receives traffic is the one you want end users to interact with. By default, the agent automatically updates to the latest version, which means a newly created version is immediately served. If that isn’t what you want, pin traffic to a specific version.
• Protocols and authorization schemes — Make sure they match where and how your users interact with the agent. For example, an agent published to Microsoft 365 or Teams must have the Activity protocol enabled and use a BotServiceRbac or BotServiceTenant authorization scheme.

This article shows you how to select the active version, enable protocols, set authorization schemes, and add an agent card. After you configure the endpoint, you can:

• Publish agents to Microsoft 365 Copilot and Microsoft Teams
• Publish an agent as an autopilot in Agent 365

If you’re migrating from the previous publishing model, see Migrate from Agent Applications to the new agent model.

Prerequisites

• A Foundry project with at least one agent version created
• Foundry User role on the Foundry project scope to create, manage, and invoke agents. Principals that only interact with agents (without creating or editing them) should use the Foundry Agent Consumer role instead.
• Foundry User role on the Foundry project scope to create, manage, and invoke agents. Principals that only interact with agents (without creating or editing them) should use the Foundry Agent Consumer role instead.

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

• Familiarity with Azure role-based access control (RBAC) for permission configuration
• Familiarity with Agent identity concepts in Foundry
• Install the required language runtimes, global tools, and Visual Studio Code extensions as described in Prepare your development environment

Code in this article uses packages that are currently in preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

Understand the agent object model

Before you configure the endpoint, understand how projects, agents, agent versions, and the stable endpoint relate to each other.

Foundry project: A folder that groups related resources such as agents, files, and tools.

Agent version: An immutable snapshot of the agent’s configuration. Any change, even a single prompt edit, produces a new version.

Agent: The stable, consumer-facing representation of an agent. The agent’s identity, endpoint, and authorization surface stay consistent as its underlying versions evolve, so consumers always interact with the same entity.

Agent endpoint: 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.

For the full list of agent object properties, see the reference section at the end of this article.

Traffic routing

The agent’s version_selector determines how traffic routes to agent versions. Two routing policies are available:

• Always use latest (default): 100% of traffic routes to the most recently created agent version. When the agent is published to Teams or Microsoft 365, creating a new version automatically updates what’s served in those channels.
• Pinned to a specific version: 100% of traffic routes to the agent version you select, called the active agent version. 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.

Protocols

An agent can expose multiple protocols simultaneously:

Protocol	Endpoint pattern
Responses	https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/openai/responses
Activity Protocol	https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/activityprotocol
Invocations	https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/invocations
A2A (preview)	https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/a2a
MCP (preview)	https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/mcp

To enable the A2A protocol on your agent, see Enable incoming A2A on a Foundry agent.

Authorization schemes

You can configure inbound authentication on the agent endpoint:

Scheme type	Description	Isolation key source
Entra	Microsoft Entra ID authorization. The caller must have the Foundry Agent Consumer role (or higher, such as Foundry User) on the Foundry project or agent scope.	Entra — derives user identity from the Microsoft Entra token. Header — reads isolation keys from custom headers (user_isolation_key, chat_isolation_key).
BotServiceRbac	Azure Bot Service channel authorization combined with Azure RBAC. Only identities that have the Azure permissions required to call the agent in Foundry can invoke it. Used when publishing to Microsoft 365 or Teams; configured automatically during the publish flow.	N/A
BotServiceTenant	Azure Bot Service channel authorization scoped to your tenant. Anyone in your tenant can invoke the agent. Used when publishing to Microsoft 365 or Teams; configured automatically during the publish flow.	N/A

API key authentication isn’t supported. Use Microsoft Entra ID (Azure RBAC) to authorize callers.

Configure the agent properties

By default, the version selector routes 100% of traffic to the latest agent version, the Responses protocol is enabled, and authorization is set to Entra. You can change the version routing, enable more protocols, set authorization schemes, and add an agent card.

Select the active agent version

By default, the routing policy is Always use latest. To pin traffic to a specific version, update the version_selector.

Foundry portal

1. In the Foundry portal, create an agent or open an existing agent.

2. Expand the Publish dropdown to see endpoint configuration options.

   Expected result: You see the available endpoints for your agent and the current version routing configuration. The endpoints are live from agent creation; no publish step is required to activate them.

3. Select the version selector arrow and choose a specific version.

   Expected result: The stable endpoint routes 100% of traffic to the selected version. When pinned, creating new versions doesn’t change what’s served.

REST API

PATCH {{endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: Bearer {{token}}
Content-Type: application/merge-patch+json

{
  "agent_endpoint": {
    "version_selector": {
      "version_selection_rules": [
        {
          "type": "FixedRatio",
          "agent_version": "2",
          "traffic_percentage": 100
        }
      ]
    }
  }
}

Python SDK

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpointConfig,
    FixedRatioVersionSelectionRule,
    VersionSelector,
)
from azure.identity import DefaultAzureCredential

PROJECT_ENDPOINT = "https://{account}.services.ai.azure.com/api/projects/{project}"

agent_name = "name-of-your-existing-agent"

project_client = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

with project_client:
    endpoint_config = AgentEndpointConfig(
        version_selector=VersionSelector(
            version_selection_rules=[
                FixedRatioVersionSelectionRule(agent_version="2", traffic_percentage=100),
            ]
        ),
    )

    patched_agent = project_client.agents.update_details(
        agent_name=agent_name,
        agent_endpoint=endpoint_config,
    )
    print(f"Agent endpoint configured for agent: {patched_agent.name}")

Enable protocols and authorization schemes

An agent can expose multiple protocols simultaneously. Configure protocols and inbound authorization on the agent endpoint.

Foundry portal

Updating protocols and authorization schemes isn’t yet configurable in the Foundry portal. Use the REST API or Python SDK.

REST API

PATCH {{endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: Bearer {{token}}
Content-Type: application/merge-patch+json

{
  "agent_endpoint": {
    "protocol_configuration": {
      "activity": {},
      "responses": {},
      "invocations": {},
      "a2a": {}
    },
    "authorization_schemes": [
      {
        "type": "Entra"
      },
      {
        "type": "BotServiceRbac"
      }
    ]
  }
}

Python SDK

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    A2AProtocolConfiguration,
    ActivityProtocolConfiguration,
    AgentEndpointConfig,
    BotServiceRbacAuthorizationScheme,
    EntraAuthorizationScheme,
    InvocationsProtocolConfiguration,
    ProtocolConfiguration,
    ResponsesProtocolConfiguration,
)
from azure.identity import DefaultAzureCredential

PROJECT_ENDPOINT = "https://{account}.services.ai.azure.com/api/projects/{project}"

agent_name = "name-of-your-existing-agent"

project_client = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

with project_client:
    endpoint_config = AgentEndpointConfig(
        protocol_configuration=ProtocolConfiguration(
            responses=ResponsesProtocolConfiguration(),
            activity=ActivityProtocolConfiguration(),
            invocations=InvocationsProtocolConfiguration(),
            a2a=A2AProtocolConfiguration(),
        ),
        authorization_schemes=[
            EntraAuthorizationScheme(),
            BotServiceRbacAuthorizationScheme(),
        ],
    )

    patched_agent = project_client.agents.update_details(
        agent_name=agent_name,
        agent_endpoint=endpoint_config,
    )
    print(f"Protocols and authorization updated for agent: {patched_agent.name}")

Add an agent card

An agent card surfaces details and capabilities to consumers, including for agent-to-agent (A2A) discovery.

Foundry portal

Adding an agent card isn’t yet configurable in the Foundry portal. Use the REST API or SDK.

REST API

PATCH {{endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: Bearer {{token}}
Content-Type: application/merge-patch+json

{
  "agent_card": {
    "version": "1.0.0",
    "description": "A competitive intelligence analyst that monitors market trends and competitor activity.",
    "skills": [
      {
        "id": "competitor-analysis",
        "name": "Competitor Analysis",
        "description": "Analyzes competitor products, pricing strategies, and market positioning across specified industry verticals.",
        "tags": ["research", "analysis", "market-intel"],
        "examples": [
          "Compare our Q3 pricing against Contoso's latest catalog",
          "Summarize recent product launches from our top 5 competitors",
          "Identify gaps in competitor coverage for the EMEA region"
        ]
      },
      {
        "id": "trend-monitoring",
        "name": "Trend Monitoring",
        "description": "Tracks emerging market trends and surfaces early signals from earnings calls, filings, and news.",
        "tags": ["trends", "monitoring"],
        "examples": [
          "What themes are emerging from this quarter's earnings calls?",
          "Flag any regulatory changes affecting our sector in the last 30 days"
        ]
      }
    ]
  }
}

Python SDK

# Agent card update via SDK is not yet supported. Use the REST API.

Get your agent properties

To view your agent’s current properties—identity, protocols, authorization, and endpoint configuration—run:

GET {endpoint}/agents/{agent_name}?api-version=v1
Authorization: Bearer {{token}}
Content-Type: application/json

Security and privacy considerations

• Use least privilege. Grant users the minimum role they need. For example, create custom roles that separate agent creation permissions from agent invocation permissions.
• Don’t embed access tokens in source code, scripts, or client applications. Use the Microsoft Entra authentication flow appropriate for your app.

Limitations

Limitation	Description
No traffic splitting	Only one agent version can be active and receive traffic at a time.

Troubleshooting

Issue	Likely cause	Resolution
403 Forbidden when invoking the endpoint	Caller lacks the required role on the agent	Assign the Foundry User role on the Foundry project resource.
401 Unauthorized when invoking the endpoint	The access token is missing, expired, or for the wrong resource	Reauthenticate and request a token for https://ai.azure.com.
Tool calls fail	The agent identity doesn’t have access to downstream resources	Assign the required RBAC roles to the agent’s identity for any Azure resources it accesses.
Publishing to M365/Teams fails	The agent doesn’t have a unique identity (agent.identity is null)	See the migration guide for steps to resolve this.

Reference: Agent object properties

Related content

• Learn about Agent identity concepts in Foundry
• Learn about Hosted agents
• Publish agents to Microsoft 365 Copilot and Microsoft Teams
• Migrate from Agent Applications to the new agent model