Publish and share agents in Microsoft Foundry

Publishing promotes an agent from a development asset inside your Foundry project into a managed Azure resource that external consumers can call through a stable endpoint. Think of it as the step that moves your agent from "works in my project" to "ready for others to use."

This article shows you how to publish an agent, configure its authentication and permissions, and update your Agent Application as you roll out new agent versions. After publishing, see the following articles to use your Agent Application:

• Invoke your Agent Application using the Responses API protocol
• Publish agents to Microsoft 365 Copilot and Microsoft Teams

If you specifically want to build and publish an agent as a digital worker in Agent 365, see Publish an agent as a digital worker in Agent 365.

What is publishing?

During development, you build and test your agent inside a Foundry project. The project gives you and your teammates a shared workspace, but it isn't designed for broad distribution because everyone with project access can interact with all agents and shares the same conversation context and permissions. Publishing is the step that moves an agent out of that shared development space and into a production-ready Azure resource.

When you publish an agent version, Foundry creates an Agent Application resource that wraps your agent version with its own invocation URL, authentication policy, unique Entra agent identity, and unique Entra agent blueprint. A Deployment is also created as a child resource of the application, referencing the specific agent version being published and supporting start/stop lifecycle management.

Why publish?

Publishing gives you capabilities that project-level development doesn't provide:

• External sharing — Grant access to teammates or customers without giving them access to your Foundry project.
• Stable endpoint — The application URL stays the same even as you roll out new agent versions.
• Distinct agent identity — The published agent gets its own Entra agent identity and Entra agent blueprint, separate from the project's shared identity and blueprint.
• Independent RBAC and authorization — The Agent Application is a separate Azure resource with its own RBAC scope. You can assign roles like Azure AI User directly on the Agent Application resource to control who can invoke it.
• Azure Policy integration — As an Azure Resource Manager (ARM) resource, the application can be governed by Azure Policy.
• Integration with Microsoft 365 Copilot and Teams — Distribute your Agent Application to channels like Microsoft 365 Copilot and Teams.

What changes when you publish?

The most important change is identity. An unpublished agent uses the project's shared agent identity. Once published, the agent receives its own dedicated agent identity. Any tools that use agent identity authentication will switch from the project's shared identity to the agent application's unique agent identity.

What to watch for

Because the identity changes, permissions don't transfer automatically. When you publish an agent, you must reassign RBAC permissions to the new agent identity for any resources that the agent needs to access. If you skip this step, tool calls that work during development fail with authorization errors once the agent is published.

Prerequisites

• A Foundry project with at least one agent version created
• Azure AI Project Manager role on the Foundry resource scope to publish agents
• Azure AI User role on the Agent Application scope to chat with a published agent using the Responses API protocol
• 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

Understand Agent Applications and deployments

Before publishing, it's important to understand the relationship between projects, agent versions, applications, and deployments.

A Foundry project is a work organization concept that groups related resources such as agents, files, and indexes. An agent represents a composable unit — defined by its instructions, model, and tools. An agent version captures a specific immutable snapshot of an agent. Every time you make changes to your agent, such as updating the prompt or adding tools, a new agent version is created. Each agent version is exposed under the Foundry project, where developers with project access can create, run, and test it.

An Agent Application projects one or more agents as a service — independently addressable, governable, and equipped with lifecycle and content management capabilities. It provides a durable interface that establishes authentication, identity, and a stable entry point for consumers. A deployment is a running instance of an agent version inside an application that can be started, stopped, and updated to reference new agent versions.

Routing and version management

Each Agent Application acts as a routing table to specific agent deployments. Currently, an Agent Application supports one active deployment, directing 100% of the traffic received by the application’s endpoint to that deployment. When you publish a new agent version to an existing application, 100% of the traffic received by the application’s endpoint is directed to the deployment referencing the new agent version.

Invoke Agent Applications

An Agent Application resource exposes a stable endpoint with multiple protocol and authentication options.

Protocols

Responses protocol

Foundry agents by default expose an OpenAI-compatible protocol based around Responses for interacting with agents.

For applications, this endpoint is exposed at:

https://{accountName}.services.ai.azure.com/api/projects/{projectName}/applications/{applicationName}/protocols/openai

The OpenAI-compatible API exposed through applications has been modified to ensure users' conversations remain private. This restriction is temporary and will be removed once we support end-user isolation. As a result, the API is more limited than the OpenAI API served by the project endpoint. Specifically:

• Only the stateless Responses API (POST /responses) is supported.
• Other APIs including /conversations, /files, /vector_stores, and /containers are inaccessible.

This limitation means the client must store conversation history for multi-turn conversations.

Activity Protocol

Foundry agents can also expose the Activity Protocol used by Azure Bot Service.

For applications this endpoint is exposed at:

https://{accountName}.services.ai.azure.com/api/projects/{projectName}/applications/{applicationName}/protocols/activityprotocol

Authentication

You can configure inbound end-user authentication on the application. The following options are available:

• Default (RBAC): The caller must have the Azure AI User role (or a custom role with the /applications/invoke/action permission) on the Agent Application resource. Choose this option if you want to invoke your agent application using the Responses API protocol. For more information about Foundry RBAC roles, see Role-based access control for Microsoft Foundry.
• Channels (Azure Bot Service): When you publish to M365/Teams or to A365 as a digital worker, channels is the authentication that is used. This is selected automatically in the UI through the M365/Teams publish flow.

API key authentication isn't supported for invoking Agent Applications. Use Microsoft Entra ID (Azure RBAC) to authorize callers.

Publish an agent

Foundry portal

This section shows you how to publish an agent using the Foundry portal interface.

1. In the Agent Builder, create or select an agent version you want to publish.

2. Select Publish Agent to create an Agent Application and deployment.

Expected result: Publishing completes and the agent version shows a published status.

3. Configure authentication for your Agent Application:

   • By default, the authentication type is set to RBAC (Role-Based Access Control).
   • Users calling the agent application using Responses protocol must be granted the Azure AI User built-in Azure RBAC role (or an equivalent custom role) on the Agent Application resource.

4. Assign permissions for tool authentication:

   • If your agent includes tools that use agent identity for authentication, the newly created agent identity must have appropriate permissions
   • Navigate to each Azure resource your agent accesses and assign the required RBAC role to the new agent identity

5. After publishing, you can:

   • Share the published endpoint with external consumers or integrate it into your existing application.
   • Share and chat with your application in channels like Teams/M365 Copilot.

REST API

To publish an agent version, you must create an application and deployment that reference your agent version.

Before you begin

1. Sign in and acquire an Azure Resource Manager access token:

az login
az account get-access-token --resource https://management.azure.com

Use the accessToken value as the Authorization: Bearer <token> header in the following requests.

If you want to capture only the token value (for example, for use in a script), use:

az account get-access-token --resource https://management.azure.com --query accessToken -o tsv

2. Collect the values you need for the request URL.

   • subscription_id: Use the subscription that contains your Foundry resource. You can find it in the Azure portal (Subscriptions) or by running az account show --query id -o tsv.
   • resource_group: The resource group that contains your Foundry resource. You can find it on the Foundry resource Overview page in the Azure portal.
   • account_name: The name of your Foundry resource (the Azure resource name).
   • project_name: The Foundry project name.
   • application_name and deployment_name: Choose names for the Agent Application and deployment you want to create.

3. Choose an api-version.

1. Create agent application.

For a full property reference and an infrastructure-as-code (Bicep) example for Agent Applications, see the Azure Resource Manager template reference for Microsoft.CognitiveServices/accounts/projects/applications.

Required field: Set the agentName field to the name of the agent you want to publish.

The following example shows only the minimum required fields. By default authorizationPolicy is set to Default (Azure RBAC) and trafficRoutingPolicy routes all traffic to the first deployment.

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "properties":{
    "agents": [{"agentName": "Publishing Agent"}]
  }
}

2. Create an agent deployment.

For a full property reference and an infrastructure-as-code (Bicep) example for Agent deployments, see the Azure Resource Manager template reference for Microsoft.CognitiveServices/accounts/projects/applications/agentDeployments.

Required fields:

• deploymentType: The deployment mode. Use Managed for prompt and workflow agents. Use Hosted for hosted agents.
• agents: The agent name and version to deploy.
• protocols: The protocol the deployment exposes. For responses, set protocol as Responses and version as 1.0.

More required fields for hosted-only:

• minReplicas: Sets the minimum number of replicas
• maxReplicas: Sets the maximum number of replicas

Prompt and workflow agents

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "properties":{
    "displayName": "Test Managed Deployment",
    "deploymentType": "Managed",
    "protocols": [
        {
          "protocol": "Responses",
          "version": "1.0"
        }
    ],
    "agents": [
        {
            "agentName": "Publishing Agent",
            "agentVersion": "1"
        }
    ]
  }
}    

Hosted agents

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json
{
  "properties": {
    "displayName": "Test Hosted Deployment",
    "deploymentType": "Hosted",
    "minReplicas": 1,
    "maxReplicas": 1,
    "protocols": [
        {
            "protocol": "Responses",
            "version": "1.0"
        }
    ],
    "agents": [
        {
            "agentName": "ContainerAgent",
            "agentVersion": "1"
        }
    ]
  }
}

3. Verify deployment is running

Prompt and workflow agent deployments typically start running automatically. Hosted agent deployments inherit the state of the published agent version — if the version is stopped, the deployment is also stopped.

To check the current state, get the deployment resource and inspect property state:

GET https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}

Use the following call to start a stopped deployment:

POST https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}/start?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

Verify publishing succeeded

Confirm that your agent published successfully before sharing the endpoint with consumers. After you publish, verify that:

• The Agent Application resource exists.
• The deployment is running.
• You can invoke the application endpoint.

Quick verification by calling the endpoint

To run the following commands, you need the Azure CLI.

1. Get an access token for the calling user.

az account get-access-token --resource https://ai.azure.com

2. Call the Agent Application endpoint (Responses protocol).

curl -X POST \
  "https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses?api-version=2025-11-15-preview" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"input":"Say hello"}'

If you receive 403 Forbidden, confirm the caller has the Azure AI User role on the Agent Application resource.

Update a published Agent Application

When you need to roll out a new version of your agent, update the existing application and deployment to reference the new agent version.

Foundry portal

1. In the Agent Builder, navigate to the specific agent version you want to publish.

2. Select Publish Updates.

3. Confirm the update. The Agent Application automatically directs 100% of traffic to the new agent version.

The stable endpoint URL remains unchanged, ensuring downstream consumers aren't disrupted by the update.

REST API

If your agent name remains the same and you only want to roll out a new agent version, update the deployment to reference a new agent version.

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "properties":{
    "description": "This is a managed deployment",
     "displayName": "Test Managed Deployment",
    "deploymentType": "Managed",
    "protocols": [
        {
          "protocol": "Responses",
          "version": "1.0"
        }
    ],
    "agents": [
        {
            "agentName": "Publishing Agent",
            "agentVersion": "<updated-agent-version>"
        }
    ]
  }
}

To roll out an agent with a different name, you must:

1. Update the Agent Application to allow the new agent name.
2. Create or update a deployment to reference the new agent version.
3. If you created a new deployment, update the Agent Application's traffic routing policy so 100% of traffic goes to the new deployment.

Invoke your Agent Application

After publishing, you invoke your agent through its endpoint using either the Responses API protocol or the activity protocol. The activity protocol is used when your agent is published to Microsoft 365 and Teams.

To use your Agent Application with the Responses API protocol, see Invoke your Agent Application using the Responses API protocol

To use your Agent Application in Microsoft 365 Copilot and Teams, see Publish agents to Microsoft 365 Copilot and Microsoft Teams.

To publish your agent as a digital worker, see Publish an agent as a digital worker in Agent 365

Security and privacy considerations

• Use least privilege. Grant users the minimum role they need (for example, separate publish permissions from invoke permissions).
• Avoid sharing project access when you only need to share an agent. Use the Agent Application endpoint and RBAC on the application resource.
• Don’t embed access tokens in source code, scripts, or client applications. Use Microsoft Entra authentication flows appropriate for your app.
• Plan for identity changes when you publish. Tool calls authenticated by agent identity use the application identity after publishing, not the project identity.
• Store conversation history in your client if you need multi-turn experiences. Agent Applications currently restrict APIs and don’t store responses.

Limitations

Agents published as Agent Applications have the following limitations:

Troubleshooting

Clean up resources

If you no longer need a published endpoint, delete the Agent Application Azure resource (and its deployments). Deleting the application doesn’t delete your agent versions in the Foundry project.

Reference: Agent Application and deployment properties

Use the following tables when you construct REST API requests or need to understand the fields returned in responses.

Related content

• Learn about Agent identity concepts in Foundry
• Learn about Hosted agents
• Learn how to publish agents to Microsoft 365 Copilot and Microsoft Teams

Next steps