Connect and configure an agent for Teams and Microsoft Copilot

Note

This article describes features used in agents or agent flows powered by the standard harness.

This article describes the Copilot Studio process for making an agent available in Teams and Microsoft Copilot, not general plugin setup.

After you publish your agent, make it available to users in Teams and Microsoft 365. This way you, your teammates, and your broader organization can interact with it. You must publish the agent at least once before users can interact with the agent in Teams or Microsoft 365.

When you make your agent available in Teams and Microsoft Copilot, the agent is added to the Microsoft plugin registry. The Microsoft plugin registry stores both agents and plugins which you can see in the Microsoft 365 Agent Store, your organization's catalog, and the Microsoft 365 admin center. Learn more in Plugins.

Note

As Microsoft 365 Copilot moves to the Plugins experience, you can still find your agents in the Agents view. Each Microsoft 365 app shows only the agents and plugins that it supports, so your agent might not be available in every app.

You can:

  • Customize your agent's appearance for Teams and Microsoft Copilot.
  • Install the agent for yourself in Teams and Microsoft Copilot.
  • Share the agent's installation link with other users.
  • Show the agent to shared users by adding it to the Shared with you section of the Microsoft 365 Agent Store.
  • Share the agent with the organization by submitting the agent for admin approval to be featured in the Built for your org section of the Teams app store or the Built by your org section of the Microsoft 365 Agent Store.
  • Add the agent to a team channel.
  • Download the app manifest for your agent to distribute it within your Teams tenant.

Note

When you add an agent to Teams, you share some of your data, such as agent content and user chat content, with Teams. Your data might flow outside of your organization's compliance and geographic or regional boundaries. Learn more in Understand the permissions of and the information accessed by Teams apps.

Prerequisites

  • All agent users in your organization can use Microsoft Copilot.

  • Agent makers have permissions to create and access a Copilot Studio environment.

  • Share your agent with other users so they can install and chat with the agent in Teams and Microsoft Copilot.

  • Your organization must allow Power Platform apps to be added to Teams before you or other users can:

    • Directly install an agent in Teams, or
    • Find an agent in the Teams app store.

    Work with your admin to Manage Microsoft Power Platform apps in the Microsoft Teams admin center if it's disabled for your organization.

  • Admins manage agents that appear in the Built for your org section (approved by an admin) separately in the Teams admin center's Manage apps page.

  • Before installing an agent for yourself or sharing it with others, publish the agent at least once.

Connect an agent to the Teams and Microsoft Copilot channels

After you publish your agent at least once, you can connect it to the Microsoft 365 and Microsoft Teams channels so users can chat with it in both Teams and Microsoft Copilot.

Note

To prevent individuals outside of your organization from using these agents, turn on security settings for agents built for Teams, Microsoft Copilot, or internal employee use.

  1. Open the configuration panel for the Teams and Microsoft Copilot channels.

  2. If you want your agent to be available in both Microsoft Copilot and Teams, under Turn on Microsoft 365, make sure Make agent available in Microsoft Copilot is selected.

    Note

    If you don't select Make agent available in Microsoft Copilot, your agent is only available in Teams.

  3. Select Add channel.

Customize the appearance of an agent for Teams and Microsoft Copilot

Before you make an agent available to other users, provide the right description and appearance. This information helps users understand the agent's purpose and branding.

  1. Open the configuration panel for the Teams and Microsoft Copilot channels.

  2. Select Edit details to change the agent's icon, color, and descriptions. These attributes are visible in the Teams app store and on the app's About tab after the user installs the agent. Review the app icon format guidelines for Teams.

    Important

    Users who already installed the agent from a shared link or from the Shared with you section of the Microsoft 365 Agent Store don't see changes to an agent's details. Users must reinstall the agent to get the updates.

    For agents already approved by an admin, you must submit the agent again for approval.

  3. Select More to add the following information:

    • Developer name
    • Website
    • Privacy statement
    • Terms of use

    Provide this information to inform users about your agent. Learn more in Create a privacy statement and terms of use in Microsoft Teams.

  4. Select Save. Your changes to the color, icon, and short description are now visible on the configuration panel.

Note

Icon customization in this section only applies to the agent avatar for agents that are approved by an admin. It doesn't apply to users who install the agent with a direct installation link or from the Shared with you section of the Microsoft 365 Agent Store. You can customize the agent avatar at Customize the look and feel of the agent.

Install an agent in Teams and Microsoft Copilot

After you publish your agent, you can add it to your Teams profile directly from Copilot Studio.

Important

New content in a freshly published agent doesn't appear in conversations that are currently ongoing. You can enter "start over" in an existing conversation to start a new conversation right away and see the latest updates to the agent.

Add your agent to your own profile in Teams first, before sharing it with others.

  1. Open the configuration panel for the Teams and Microsoft Copilot channels.

  2. Select See agent in Teams.

    If you configured your agent to be available in Microsoft Copilot when you first added the channel, selecting See agent in Teams installs your agent to both Teams and Microsoft Copilot. If you didn't configure your agent for Microsoft Copilot, your agent installs only to Teams.

  3. Select Add.

    Screenshot of the Add agent window in Teams.

    The agent appears in the agent list on the left.

  4. To ask your new agent a question in Microsoft Copilot, enter @, select your agent from the list that appears, enter your question, and select Enter.

Note

A user can install or reach an agent in Teams but still be unable to chat with it if the agent isn't shared with that user or an applicable security group. Verify that the user has access to the agent, and then retest with the affected account.

  1. Open the configuration panel for the Teams and Microsoft Copilot channels.

  2. Select Availability options.

  3. Select Copy link.

  4. Share the link with users so they can install the agent in Teams.

Important

Only users who can access the agent can use the link to install the agent. You can share the agent to give users access to the agent.

You can't use an installation link in the Teams mobile app. To make sure your agent is available to Teams mobile users, configure it to show in the Teams app store.

Show an agent in the Teams app store or in the Microsoft 365 Agent Store

After you publish your agent, you can show it in the Teams app store or in the Microsoft 365 Agent Store so users can find and install it.

Show an agent to shared users

You can share your agent by adding it to the Microsoft 365 Agent Store. Once the agent is available to specific users in the Shared with you section of the Microsoft 365 Agent Store, they can also install it to Teams.

  1. Open the configuration panel for the Teams and Microsoft Copilot channels.

  2. Select Availability options.

  3. Select Show to my teammates and shared users.

  4. Review who has access to the agent.

  5. Select Share. Your agent becomes available to your teammates and shared users in the Shared with you section of the Microsoft 365 Agent Store.

    Important

    The agent doesn't show for everyone in the organization even if you configure it to allow everyone to use the agent. To make the agent available to everyone in the organization, submit the agent for an admin's approval to show it in the Built for your org section of the Teams app store or in the Built by your org section of the Microsoft 365 Agent Store.

Show to the organization

You can share an agent with your organization by submitting it for admin approval to feature it in the Built for your org section of the Teams app store or in the Built by your org section of the Microsoft 365 Agent Store. Featuring your app in the Teams app store and in the Microsoft 365 Agent Store is a great way to broadly distribute your agent by partnering with your admin to roll it out to everyone in the organization or to a subset of users.

Admins can also use app setup policies to automatically install and pin an agent for users in the organization so they can access it directly from their app bar in Teams.

Before submitting an agent to your organization, ensure that:

  • Your agent is ready for release and complies with company standards, rules, and policies.
  • You coordinate with other agent managers. After you submit an agent, a different user can't resubmit it until an admin approves or rejects the previous submission.

Note

After an admin approves an agent, the admin manages the agent availability in the Built for your org section of the Teams app store and the Built by your org section of the Microsoft 365 Agent Store. Only an admin can remove the agent from these sections.

Submit an agent for admin approval

  1. Open the configuration panel for the Teams and Microsoft Copilot channels.

  2. Select Availability options.

  3. Select Show to everyone in my org.

  4. Review the requirements for submission, and select Submit to org catalog.

    Note

    Ensure the content is ready for an admin to review. You must submit a new approval request to update the icon and descriptions for agents that were previously approved.

    Once an agent is approved, all new and existing users of the agent in Teams and Microsoft Copilot receive the update.

    A new approval is only required if you modify the agent details. You can make content updates to your agent and publish it as often as desired. You don't need to submit your agent for approval again after publishing such content changes.

    A final confirmation prompt appears.

  5. Select Yes to continue. The agent is sent to your admin for approval, and you can see a note indicating the status of your submission.

    Note

    After submitting the agent for admin approval, don't change the agent's access setting to be less than everyone in your organization.

    Setting the access to less than everyone results in users in the organization being unable to chat with the agent after installing it from the Teams app store or the Microsoft 365 Agent Store.

    Work with your admin on the Microsoft Teams app policy to determine who can find and install the agent.

  6. Wait for your admin's approval. You can check the latest status by selecting Refresh, or opening the Make the agent available to others window from the Publish page.

  7. After your admin approves the agent, the status is updated to Approved. You can directly open the agent and share the approved version's link with other users.

  8. Optionally, ask your admin to use app setup policies to automatically install and pin an agent for users in the organization so they can access it directly from their app bar in Teams.

Note

If your app is marked as Approved but doesn't appear in the Built for your org section of the Teams app store, your Teams app might be caching information.

Try signing out and back in again (if you're using the desktop app) or refreshing your browser (if you're using the Teams web app).

Allow users to add an agent to a team in Teams

In Teams, users can add an agent to a specific team. Once an agent is available for a team, team members can "@mention" it in any of that team's channels, and all teammates see the responses from the agent. This feature is useful for situations such as the following examples:

  • Your agent supports collaboration, like sharing the latest sales report insight with the rest of the Sales team.
  • You want to allow all team members to engage with the agent in a team channel or via private chat without needing to manually install the agent themselves.

Two options determine whether users can add an agent to any team that they're part of, or to group and meeting chats in Teams. When you select these options, the agent gets access to the conversation history from the team channel, group chat, or meeting chat, which helps the agent provide answers better suited to the context of the conversation.

When users install an agent from the Teams app store or by using an installation link they can perform one or both of the following operations, depending on the collaborative scope you set for the agent:

  • Add the agent to a team channel
  • Add the agent to group and meeting chats in Teams

Important

Configure the agent to allow everyone in the organization to chat with it. This setting ensures all team members have permission to chat with the agent. Don't change the security setting of the agent after enabling this capability. Otherwise, users might see permission errors when they try to interact with the agent in Teams channels or group chats.

  1. Open the configuration panel for the Teams and Microsoft Copilot channels.

  2. Select Edit details.

    • If you want to allow users to add the agent to a team, select Users can add this agent to a team.
    • If you want to allow users to invoke the agent in group chats and in meeting chats, select Use this agent for group and meeting chats.
  3. Select Save.

Note

  • Teams caches information, so it can take a while before users see the option to add the agent to a team or group chat. Users can refresh the browser (or sign out of the Teams desktop client and sign back in) to get the latest changes.
  • If you previously submitted the agent for admin approval, you must submit it again after enabling this option. The admin must approve your changes before users can add the agent to their teams from the Built for your org section of the Teams app store.

Prevent users from adding an agent to a team

When you turn off this option, users can't add an agent to a new team. It doesn't remove the agent for users who already have it in their teams. They must manually remove the agent.

To prevent users from adding an agent to a team:

  1. Open the configuration panel for the Teams and Microsoft Copilot channels.

  2. Select Edit details.

  3. Clear the Users can add this agent to a team checkbox.

  4. Select Save.

Prevent users from adding an agent to group and meeting chats

When you turn off this option, users can't add an agent to a new group or meeting chat. It doesn't remove the agent from group chats and meeting chats that already have it. You must manually remove the agent from those chats.

To prevent users from adding an agent to a group or meeting chat:

  1. Open the configuration panel for the Teams and Microsoft Copilot channels.

  2. Select Edit details.

  3. Clear the Use this agent for group and meeting chats checkbox.

  4. Select Save.

Configure private greeting behavior

Private greetings from an agent are useful when you want team members to have one-on-one conversations with the agent without needing to manually install the agent themselves.

Note

Private greeting configuration is available for classic chatbots only.

When you configure this behavior, your agent automatically starts a conversation with team members. To customize the agent's greeting message, modify the Greeting system topic.

Consider how relevant the agent is to team members. Ensure the agent's greeting helps them understand what to do with it, describes its limitations, and, most importantly, gets them comfortable interacting with it.

To configure when an agent sends a private greeting:

  1. Open the configuration panel for the Teams and Microsoft Copilot channels.

  2. Select Settings.

  3. Configure the private greeting options.

  4. Select Save.

Download the Teams app manifest for an agent (advanced)

You can download the agent's Teams app manifest to make detailed changes to the manifest directly and share it with your admin or users in the tenant. You can also directly upload an app manifest into Teams if your organization's policy allows you to upload custom applications. Learn more in Upload your app in Teams.

  1. Open the configuration panel for the Teams and Microsoft Copilot channels.

  2. Select Availability options.

  3. Select Download .zip. The manifest is generated as a .zip file and saved according to your browser's settings.

  4. In Teams, select Apps > Manage your apps > Upload an app.

  5. Under Upload a custom app, select Upload.

  6. Browse for the downloaded .zip file, and select it.

  7. Select Add and then choose the place where you want to use your agent. Depending on how you configured your agent for the Teams and Microsoft Copilot channels, some of the following options might be unavailable:

    • To chat with your agent in Teams, select Open.
    • To chat with your agent in Copilot, select Open with Copilot.
    • To make your agent available to others, select the channel, group chat, or meeting chat you want.

Disconnect an agent from Teams and Copilot

You can take your agent offline so users can no longer chat with it in Teams and Copilot. When your agent is offline, it doesn't respond to anyone who tries to chat with it. Consider the need to disconnect your agent before you do so.

Disconnected agents don't appear in the Shared with you section of the Microsoft 365 Agent Store and you can't install them from a shared link. If a user already has such an agent installed in Teams, it remains available until the user uninstalls it.

If you disconnect an agent that an admin approved, it continues to appear in the Built for your org section of the Teams app store and the Built by your org section of the Microsoft 365 Agent Store. You must ask your admin to remove it.

  1. Open the configuration panel for the Teams and Microsoft Copilot channels.

  2. Select Remove channel.

  3. Review the information about disconnecting your agent, and select Disconnect to continue.

You can always reconnect your agent by selecting Add channel in the configuration panel for the Teams and Microsoft Copilot channels, republishing, and then reinstalling the agent in Teams.

Note

If you add the Teams channel again, without first uninstalling the agent from Teams, an Update now button appears instead of the Add button. In this case, select Update now to reinstall the agent in Teams.

Open the configuration panel for the Teams and Microsoft Copilot channels

  1. Open your agent in Copilot Studio.

  2. On the top menu bar, select Channels.

  3. Select the Microsoft 365 and Microsoft Teams tile. The configuration panel appears.

Known limitations

The known limitations differ depending on whether you're using Teams or Microsoft Copilot.

Known limitations in Teams

  • Agents that use the upgraded unified authoring canvas don't support the private greeting configuration.

  • Agents approved by an admin don't have the option for setting the avatar icon on the details page. These agents use the app icon as their avatar.

  • Teams applies rate limiting to agents. Depending on your business needs, you might want to keep your agent content concise for agents that you publish to Teams.

  • If your agent supports user authentication, the user can't explicitly sign out. This behavior fails the Teams Marketplace certification if you're publishing your agent in the Seller Dashboard. This limitation doesn't apply to personal or tenant usage of the agent. Learn how to publish your app to the Teams Store and about the Marketplace certification policy.

  • After you disconnect your agent from the Teams channel, it might take a few minutes before users in Teams can't reach the agent.

  • In Teams group chats and channels, Copilot Studio agents can't use knowledge sources that require end‑user authentication, such as SharePoint. This limitation is by design and helps prevent unintended data exposure. These agents are supported only in 1:1 chats.

  • Group chats and meeting chats don't support agents configured for manual authentication with single sign-on (SSO) for Teams. Depending on your business needs, you could either authenticate with Microsoft or remove SSO for Teams from your manual authentication.

Citations don't render for customized answers

When an agent uses a generative answers node with a customized response, Teams doesn't render citations in the response. Unlike standard (non-customized) generative answers, Teams doesn't automatically add citations to customized answers.

To render citations from a customized generative answers response in Teams:

  1. In the Create generative answers properties panel, expand the Advanced section and set Save LLM response to Complete (Recommended). This setting captures the full response, including citation metadata.

  2. In the topic's code editor, add a SendActivity node after the generative answers node. Include citationEntities and text attributes under activity, pointing to the variables that hold the citations and response text:

    - kind: SearchAndSummarizeContent
      id: search-content
      latencyMessageSettings:
        allowLatencyMessage: false
      autoSend: false
      variable: Topic.Answer
      userInput: =System.Activity.Text
      responseCaptureType: FullResponse
    
    - kind: SendActivity
      id: sendActivity_SnMFMq
      activity:
        text:
          - "{Topic.Answer.Text.Content}"
        citationEntities: =Topic.Answer.Text.CitationSources
    

Learn more in Edit topics by using the code editor.

SystemError after publishing or republishing an agent

When users interact with an agent in Teams, they might see the following message:

Sorry, something unexpected happened. We're looking into it.
Error code: SystemError

This problem happens when Teams keeps using a previously published version of the agent after you publish or republish the agent. In some cases, Teams doesn't immediately refresh the updated agent configuration. This problem causes a generic SystemError during agent execution.

To refresh the agent configuration, try the following steps as a workaround:

  1. In the Microsoft Teams admin center, locate the agent app, turn it off, wait a few seconds, and then turn it back on.
  2. In Copilot Studio, turn off the Teams channel for the agent, save your changes, and then turn the channel back on.
  3. Republish the agent to ensure the latest version is available to Teams.

If the problem persists, contact Microsoft Support and provide the Conversation ID, Agent ID, and the time when the error occurred.

Known limitations in Microsoft Copilot

  • Conversation Start topic not supported: The Microsoft Copilot channel doesn't support the Conversation Start topic, so you can't use general greetings. Instead, the agent offers suggested prompts. You can set variables through Activity Event-triggered topics, but this method isn't ideal for greetings due to side effects.

  • Unsupported media types: Media like GIF images don't render.

  • Embedded URLs: For security, Microsoft Copilot might remove embedded URLs. Citations from generative answers should include URLs in the citation section.

  • Unsupported node types:

    • Speech operations
    • Hand-off to customer service representative
    • Adaptive Cards with Action.Execute
  • Unsupported message types:

    • Basic cards (ContentFiltered error)
    • Video (ContentFiltered error)
    • Image (ContentFiltered error)
    • File
    • Speech (not sent)

    Note

    You can use Adaptive Cards to show images.

  • Inactivity trigger fires but doesn't post messages back to Microsoft Copilot.

  • Agents published to Microsoft Copilot don't support user feedback (reactions).