SharePoint agents and Copilot
AI and Copilot

Upgrade agents in SharePoint and OneDrive - SharePoint in Microsoft 365

In brief

The documentation says the upgrade experience begins rolling out in mid-November 2026. Existing .agent files used in Teams or Microsoft Copilot will stop responding until upgraded; Teams chats require upgrading all agents together. The SharePoint Agents icon and Main agent setting will also be removed.

What SharePoint admins need to know

Identify affected agents and plan upgrades. For Teams chats, remove the old agent and add the upgraded agent; verify user access to the agent and its knowledge sources.

Summaries are generated from the documentation change itself.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

Upgrade agents in SharePoint and OneDrive - SharePoint in Microsoft 365 | Microsoft Learn

Learn how to upgrade your agent experiences in SharePoint and OneDrive. Upgrading allowsBy upgrading, your agents tocan leverage Copilot in SharePoint and all the functionality of the Microsoft Copilot extensibility ecosystem.

What is changing?

Microsoft is upgrading the agent experience in SharePoint and OneDrive. Upgrading better aligns your agents with the Microsoft Copilot extensibility ecosystem, ensuring your agents are part of the Microsoft Copilot app Home experience and the Microsoft plugin registry, the shared catalog for discovering, publishing, and governing organization-approved and custom-built plugins across Microsoft Copilot experiences, Microsoft 365 apps, OneDriveOneDrive, and SharePoint.

Existing agents in the .agent file format will continue to work across SharePoint, Microsoft Teams, and the Copilot app until the end of March 2027. You can start upgrading or moving each experience to a supported path that best fits its purpose now. After March 2027, .agent files will stop responding and you will have to upgrade to continue using them.

| Provides a customized Q&A, retrieval, or analysis experience | Upgrade the agent with Microsoft Copilot Agent Builder | | Is a custom engine agent built in Copilot Studio and published to SharePoint | Publish the existing Copilot Studio agent to Microsoft Copilot app |

Starting in mid-November 2026, you'll use Microsoft Copilot Agent Builder to create agents for SharePoint and OneDrive. You can still select SharePoint and OneDrive content as knowledge sources and use a provided prompt to start building a conversational agent. However, creating an agent no longer saves a .agent file in SharePoint or OneDrive. You can edit, share, and monitor your agents through the Copilot app and manage them through Agent 365Agent 365.

Are agents in SharePoint and OneDrive being retired?

Agents in .agent file format stop responding to prompts:

  1. .agent files that you added to a Teams chat or channel stop responding. Users will see a message indicating it needs to be upgraded before it can be used.

  2. .agent files that you used in Microsoft Copilot app stop responding. Users will see a message indicating it needs to be upgraded before it can be used.

  3. In SharePoint and OneDrive:

    • Accessing a .agent file (directly or through a share link) displays a message that indicates an upgrade is required.
    • The agent no longer opens in the immersive viewer, Copilot app, or SharePoint side chat pane.
    • The agents icon on the SharePoint navigation no longer appears.will be removed.
    • The only main agent available on a SharePoint site is Copilot, so thisthe Main agent setting in the Site AI pane is no longer needed and will be removed.

Upgrade paths

You can chooseChoose from different Copilot capabilities to upgrade toto, based on what your existing agent does and where people need to use it.

As you upgrade an existing SharePoint or OneDrive agent, consider the outcome it provides today and choose the upgrade path that best preserves that outcome. Also consider reviewing agents with no recent use or no clear owner for archival or deletion, instead of upgrading them.

In SharePoint, site owners can bring agents directly to their audience by adding them to the pages where people need them using the Agent Chat web part. Site owners control where these agents appear as part of the overall site experience. Usage by unlicensed users is consolidated under Copilot app pay-as-you-go (PAYG).

Note

Start upgrading agents that are used only on SharePoint sites and Copilot App first.

If the agent is used in a Teams chat and channel, all agents used in a single chat need to be upgraded at the same time. The old agent needs to be removed and the upgraded agent added to the chat.

Upgrade the agent with Microsoft Copilot Agent Builder

The agent is a customized Q&A, retrieval, or analysis experience with an identity, description, starter prompts, and instructions. Before you start, confirm you have the following access:

Note

The upgrade experience described here will be available startingbegins rolling out mid-November 2026.

  1. Take note of who has access to the agent and where the agent is used.
  2. Edit the .agent file.

Screenshot of SharePoint Builder showing the Upgrade confirmation dialog with the Move file to Recycle bin option selected.

  1. Select Upgrade to Microsoft 365 agent to confirm. Teams and Copilot app will automatically use the upgraded agent.

    • If you plan to add the agent to a page Agent Chat web part, select Move file to Recycle bin.
    • If you want to continue using the .agent file configuration as the main agent for the site until March 2027, through an Agent Link web part open in the SharePoint chat pane, don't select Move file to Recycle bin.
  2. On a successful upgrade, the agent uses Microsoft Copilot Agent Builder for all future updates. You can no longer edit the original .agent file and it won't be changed by Microsoft Copilot Agent Builder.

  3. If you shared the original agent was shared with everyone in the organization, this access continues in the upgraded agent. Otherwise, the agent is private to you and you can share it to the necessary Microsoft 365 groups. Verify that users who need the agent can access both the agent and the selected knowledge sources.

Screenshot of the upgraded agent confirmation for a private agent, with Share and Start chat options shown.

Note

The convert-agent-file-to-skill skill will be availablebegins rolling out mid-November 2026.

Skills customize what Copilot in SharePoint can do for specific business outcomes.

To convert the agent to a skill:

  1. Prompt to use the skill, convert-agent-file-to-skill, with the .agent or .copilot agent file. You will have the option to create a site or personal skill.

    Screenshot of the convert-agent-file-to-skill built-in skill available to users.

    You can choose between a skill for this site or a personal one.

    Screenshot of selecting the skill and pointing to the agent to convert to start the process.

  2. To help users discover a site skill, add a Button web part to the page to open Copilot in SharePoint to run a prompt with the skill. This step is optional.

  3. You can delete the .agent file after the conversion.

To upgrade the agent, you need:

What should I do if I use an agent that someone else created?

In Copilot app, the upgraded agent automatically loads when requested. OneDrive users should use Copilot app to use their agents.

In aStart upgrading agents that are not used in Teams chat or channel,channel first. There are improvements coming to Teams soon which will make this upgrade easier. If you choose to upgrade an agent that is used in Teams, please note that you need to upgrade all agents used in the chat at the same time or else one upgraded agent iswill render all other (.agent file) agents unusable. You also need to add the upgraded but needs to be re-addedagent to the chat or channel. Remove the agent that's in the chat or channel now, thenagain. You can add the upgraded agent by grabbing a link to it and adding it to a message to the chat or channel.

How do I know an agent is upgraded?

Is my existing agent already gone?

No. You can use existing .agent files duringreliably until the transition. The announcement providesend of March 2027. Use this time to inventory, evaluate, upgrade, and test experiences before .agent files stop responding to prompts after March 2027.

New agents will be created through Copilot Agent Builder.

When will the experience change?

  1. Update internal guidance, support processes, training, and communications before the creation experience changes.
  2. Allow time to test sharing, content access, Teams placement, SharePoint placement, and representative prompts.

Where willcan users find upgraded agents?

Users can discover declarative agents and Copilot Studio agents through supported Microsoft 365 experiences, including the plugin store, Microsoft Copilot app, and Teams.