> ## Documentation Index
> Fetch the complete documentation index at: https://hobbyist-e43fa225.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Publish agents to Microsoft 365 Copilot and Microsoft Teams
> Publish a Microsoft Foundry agent to Microsoft 365 Copilot and Microsoft Teams from the Foundry portal.
After you build and test an agent, the next step is often sharing it with others in the surfaces where they already work. Publishing a Foundry agent to Microsoft 365 Copilot and Teams lets you and others interact with and discover your agent through the Microsoft 365 Copilot and Teams UI. What gets published is the agent's stable endpoint, so end users always interact with a consistent agent entity while you seamlessly roll out new agent versions that receive traffic through the endpoint.
This article explains how to publish agents from the Foundry portal.
When you publish agents to Microsoft 365 and Teams, certain data associated with publishing and using the agent in Microsoft 365 and Teams is processed and stored by those services and is subject to the terms, compliance commitments, data residency commitments, and data handling practices applicable to Microsoft 365 and Teams.
This data can include data necessary to publish the agent, such as the agent's name, icon, and description, as well as data contained in responses provided by the agent when users in your organization submit queries to the agent from Microsoft 365 and Teams.
Before you publish an agent to Microsoft 365 and Teams, evaluate whether the resulting data flows and processing are consistent with your organization's compliance, data residency, and governance requirements.
Publishing from the Foundry portal isn't available for projects that disable public network access because additional networking configuration is required. To publish these agents, use the REST API. For more information, see [Publish a virtual network agent to Microsoft 365 and Teams](/agents/publish-copilot-virtual-network).
## Prerequisites
* Access to the [Microsoft Foundry portal](https://ai.azure.com/?cid=learnDocs)
* A [Foundry project](../../how-to/create-projects) with an agent version you tested and want to publish
* The following role assignments:
* Permission to create an Azure Bot Service resource (`Microsoft.BotService/botServices/write`) and configure its channels (`Microsoft.BotService/botServices/channels/write`) in the resource group where you publish. The **Azure Bot Service Contributor Role** grants exactly these permissions. The broader **Contributor** or **Owner** roles also work. Foundry roles don't grant these permissions. For details, see [Azure Bot Service setup](/agents/hosted-agent-permissions#azure-bot-service-setup).
* **Foundry User** role on the Foundry project scope to create, manage, and publish agents.
> 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.
* For details, see [Role-based access control in the Foundry portal](../../concepts/rbac-foundry).
* **Test your agent thoroughly** in the Foundry portal before publishing. Confirm it responds correctly and any tools work as expected.
* **Select the active agent version** you want consumers to interact with in Microsoft 365 and Teams.
* Verify that required Azure resource providers are registered in your subscription. The publishing process creates an Azure Bot Service resource, which requires the `Microsoft.BotService` provider.
If you use Azure CLI, you can register the provider with:
```azurecli theme={null}
az provider register --namespace Microsoft.BotService
```
## Select an active agent version
The active version is the version that your agent's stable endpoint serves to consumers, so confirm it before you publish. For more information about agent versions and other settings, see [Configure your agent endpoint and settings](/agents/configure-agent).
Set the active version from either of two entry points.
**From the Details tab**
1. Open your agent and select the **Details** tab.
2. In **Agent configuration**, next to **Active version**, select **Edit**.
3. Select **Always use latest**, or select a specific version.
**From the Publish button**
1. In the Microsoft Foundry portal, select **Publish**.
2. Next to **Active version**, select the arrow.
3. Select **Always use latest**, or select a specific version.
To pin traffic to a specific version, update the agent's `version_selector`. Set `agent_version` to the version you want to serve.
```
PATCH {{endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: ******
Content-Type: application/merge-patch+json
{
"agent_endpoint": {
"version_selector": {
"version_selection_rules": [
{
"type": "FixedRatio",
"agent_version": "2",
"traffic_percentage": 100
}
]
}
}
}
```
## What happens when you publish?
When you publish an agent, Foundry performs the following steps:
* Validates the properties you submit, such as the display name, description, and version.
* Compiles a Teams app manifest as a `.zip` package. For more information, see [App manifest schema for Microsoft Teams](/microsoftteams/platform/teams-sdk/teams/manifest).
* Submits the manifest to the Microsoft 365 Copilot and Teams agent catalogs on your behalf.
* Enables the `activity` protocol, which the agent needs to exchange messages with Microsoft 365 and Teams.
* Enables an authorization scheme, either `BotServiceRbac` or `BotServiceTenant`, that controls who can call the agent, based on the scope you select.
### Who can see and call the agent
The scope you select controls *visibility* — who can discover the agent in the Microsoft 365 Copilot and Teams stores. Foundry sets the matching authorization scheme, which controls who can *call* the agent:
* **Just you** (Foundry portal) or `publishScope` set to `Shared` (REST API): Enables `BotServiceRbac` and requires no admin approval. The agent appears in the stores only for you. If you add it to a Teams chat, participants who have the required Foundry permissions on the project can use it.
* **People in your organization** (Foundry portal) or `publishScope` set to `Tenant` (REST API): Enables `BotServiceTenant` and requires admin approval in the [Microsoft 365 admin center](https://admin.cloud.microsoft/?#/agents/all/requested). After approval, the agent appears for everyone in your tenant under **Built by your org**, and anyone in the tenant can discover and use it.
## Publish to Microsoft 365 and Teams
Publishing from the portal calls Foundry's Microsoft 365 publish API and builds the Teams app package for you. To publish by using the REST API instead, for example to automate publishing or to publish from a project that disables public network access, see [Publish a virtual network agent to Microsoft 365 and Teams](/agents/publish-copilot-virtual-network). Steps 1 through 4 in that article are the REST equivalent of this portal flow and work for any project; only the final networking step is specific to disabled public network access.
You can open the publish dialog from the **Details** tab (in the **Channels** section, select **Teams & Microsoft 365 Copilot**) or from the **Publish** button. These steps use the **Publish** button.
1. In Microsoft Foundry portal, select **Publish**, and then select **Teams and Microsoft 365 Copilot**.
**Expected result**: The **Publish to Teams and Microsoft 365** dialog opens.
2. An Azure Bot Service resource is either automatically created or shown as read-only if one already exists.
3. Complete the required metadata:
| Field | Description |
| --------------------- | ------------------------------------------------------------------------------- |
| **Name** | Display name for your agent (appears in the agent store) |
| **Publish version** | Three-part version number (major.minor.patch) |
| **Short description** | One-sentence description of what your agent does |
| **Description** | Longer description of your agent's responsibilities and the actions it can take |
| **Developer** | Your name or organization name (under **Author**) |
To add optional metadata, expand **More** and complete the following fields:
| Field | Description |
| --------------------- | ------------------------------------------- |
| **Developer website** | URL to your website (HTTPS required) |
| **Terms of use** | URL to your terms of use (HTTPS required) |
| **Privacy statement** | URL to your privacy policy (HTTPS required) |
Don't include secrets, API keys, or sensitive information in any metadata fields. These fields are visible to users.
1. Select **Next: Publish options**.
2. Choose how to publish. You can either [publish your agent directly from Foundry](#direct-publish) or [download and customize the agent manifest, then manually sideload it in Teams](#download-and-customize).
### Direct publish
1. On the **Publish options** step, select the **Direct publish** tab.
**Expected result**: Section **Choose who can use this agent** is displayed.
2. Under **Choose who can use this agent**, select a scope:
| Option | Behavior | Admin approval | Best for |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------ |
| **Just you** | Available immediately. The agent appears under **Your agents** in the agent store. Share it with others by sending the agent link. | Not required | Personal testing, small teams, pilots |
| **People in your organization** | The agent is submitted for admin approval. Your Microsoft 365 admin reviews the request and assigns access. Once approved, the agent appears under **Built by your org** for all tenant users. | Required | Organization-wide distribution, production deployments |
**Just you**:
* Available immediately after publishing — no admin approval required.
* Only you see the agent initially under **Your agents** in the agent store.
* Share with specific users by sending the agent link.
**People in your organization**:
* After publishing, a Microsoft 365 admin must review and approve the request in the [Microsoft 365 admin center](https://admin.cloud.microsoft/?#/agents/all/requested).
* Once approved, the agent appears under **Built by your org** in the agent store for all tenant users.
* App policies in your tenant control which users can access the agent.
* To check approval status, go to the [Microsoft 365 admin center](https://admin.cloud.microsoft/?#/agents/all/requested) and look for your agent under **Requests**.
1. Select **Publish**.
**Expected result**: A **Publish successful** dialog confirms the agent was successfully published.
### Download and customize
If you want to customize the agent manifest before distributing:
1. On the **Publish options** step, select the **Download & customize** tab.
**Expected result**: The tab displays instructions for after downloading and a **Download ZIP** button.
2. Select **Download ZIP**.
**Expected result**: A `.zip` file containing the agent manifest downloads to your local machine.
3. Customize the manifest in the downloaded package as needed.
4. In Microsoft Teams, upload the package you downloaded
1. Go to **Apps** > **Manage your apps** > **Upload an app**
2. Select **Upload a custom app** or **Submit an app to your org** and choose the downloaded `.zip` file.
## Update a published agent in M365/Teams
### Update the active agent version
To roll out a new agent version, update the agent's version selector in the Foundry portal. The stable endpoint URL stays the same — no need to republish to M365/Teams.
### Update end user metadata in M365/Teams
To update metadata visible in Teams and M365 (display name, descriptions, URLs), in the **Publish** dropdown select **Update agent Teams and Microsoft 365 Copilot display properties**. The updated fields overwrite the existing values; unchanged fields are carried forward; and version will auto increment if not manually incremented.
## Limitations
For agent publishing limitations, including requirements when your project disables public network access, see [Limitations](/agents/publish-copilot-virtual-network#limitations).
## Troubleshoot publishing
Use the following table to resolve errors that occur while you publish from the portal. For more extensive troubleshooting, including how to find a published agent in the store and resolve errors when you chat with it, see [Troubleshooting](/agents/publish-copilot-virtual-network#troubleshooting).
| Symptom | Cause | Resolution |
| --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Error publishing the agent | Invalid metadata or version | Ensure the agent has a unique identity (`agent.identity` isn't null). Confirm the developer name is 32 characters or fewer. |
| Azure Bot Service creation fails | Missing permissions or unregistered provider | Confirm you have permission to create resources. Register `Microsoft.BotService` if needed. |
| The **Azure bot services** field shows a `403 AuthorizationFailed` error for `Microsoft.BotService/botServices/write` | Your identity doesn't have permission to create or update the Azure Bot Service resource in the target resource group | Assign the **Azure Bot Service Contributor Role** (or the broader **Contributor** or **Owner** role) on the resource group that contains the bot service, then refresh your credentials and reopen the publish flow. |
If the portal shows **This agent uses an older format that can no longer be published to Teams and Microsoft 365 Copilot. Upgrade to new format to publish.**, the agent uses the older agent application format, which the generally available publish flow doesn't support for new publishing. Upgrade the agent to the new format, and then publish. Existing agents in the older format keep working and can still be updated. See [Migrate from agent applications to the new agent model](/agents/migrate-agent-applications).
## FAQs
**If I select Organization scope, where do I approve the agent?**
In the Microsoft 365 admin center. Once approved, the agent appears under **Built by your org** in the agent store.
**If I publish my agent to Individual Scope (previously called Shared Scope), how do I share it with others in my organization?**
The agent appears under Your agents in the agent store for Microsoft 365 Copilot. You can share it by sending the agent link to selected users in your organization.
**What happens when I create a new agent version if my agent is published to M365?**
If the version selector is set to "Always use latest" (the default), the new version is automatically served in M365/Teams. If pinned to a specific version, you must update the version selector to serve the new version.
## Related content
* [Configure your agent endpoint and settings](/agents/configure-agent)
* [Publish a virtual network agent to Microsoft 365 and Teams](/agents/publish-copilot-virtual-network)
* [Role-based access control in the Foundry portal](../../concepts/rbac-foundry)
* [Migrate from Agent Applications to the new agent model](/agents/migrate-agent-applications)