What Microsoft is changing for agents in SharePoint and OneDrive
Microsoft is retiring the .agent file format used by agents in SharePoint and OneDrive. Existing .agent files keep working until the end of March 2027, and after that they stop responding. Message Center post MC1511052 announced the change on 16 October 2026. Agents themselves are not being retired: new agents are built with Microsoft Copilot Agent Builder, and existing ones are upgraded to it.
The first changes arrive in mid-November 2026, and Microsoft expects the rollout to finish by early December 2026 in the worldwide and government clouds. From mid-November:
- Creating an agent from SharePoint or OneDrive uses Microsoft Copilot Agent Builder. It no longer saves a .agent file in SharePoint or OneDrive.
- The Upgrade to Microsoft 365 agent button appears in the SharePoint agent builder.
- The
convert-agent-file-to-skillskill becomes available in Copilot in SharePoint. - The Agent Chat web part, which Microsoft lists as coming soon (roadmap ID 575298), becomes the main way to place an agent on a SharePoint page.
Nothing is upgraded for you. Microsoft states there is no automatic upgrade, because an agent owner or site owner has to choose the path that keeps the original purpose of each agent.
Which agents are affected
The change applies to agents stored as .agent files in SharePoint or OneDrive. People use these today in the SharePoint chat pane, through the Agent Link web part, in the agent immersive viewer, in a Microsoft Teams chat or channel, and in the Copilot app.
Copilot Studio agents published to SharePoint are not affected, and you do not need to recreate them. Review their publishing configuration and publish them to the Microsoft Copilot app so they can be shown in the Agent Chat web part.
What stops working after March 2027
After March 2027, agents in .agent format stop responding to prompts:
- A .agent file you added to a Teams chat or channel stops responding.
- A .agent file you used in the Microsoft Copilot app stops responding.
- In SharePoint and OneDrive, opening a .agent file, directly or through a share link, shows a message that an upgrade is required. The agent no longer opens in the immersive viewer, the Copilot app or the SharePoint side chat pane.
- The agents icon in SharePoint navigation no longer appears, and the setting for choosing a main agent on a site is removed, because the only main agent left on a site is Copilot.
Which upgrade path fits each agent
Microsoft's guidance is to choose the path that keeps what the agent does for people today.
| What the agent does | Recommended path |
|---|---|
| Mostly answers questions about content on the current SharePoint site | Use Copilot in SharePoint directly |
| Performs a repeatable action, workflow or task within the SharePoint site | Convert the agent to a skill |
| Gives 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 the Microsoft Copilot app |
Microsoft also suggests reviewing agents with no recent use or no clear owner for archiving or deletion instead of upgrading them. Deleted .agent files go to the Recycle Bin.
How to upgrade an agent to a Microsoft 365 agent
The upgrade experience is available from mid-November 2026. You need edit permission on the .agent file, the ability to share the agent, and permission to edit pages if you plan to add the agent to a page with the Agent Chat web part.
- Note who has access to the agent and where it is used.
- Edit the .agent file. The SharePoint builder shows an upgrade banner.
- Select Upgrade to Microsoft 365 agent. A confirmation dialog appears.
- Select Upgrade to Microsoft 365 agent again to confirm. Teams and the Copilot app then use the upgraded agent automatically.
- Choose what happens to the original file:
- Select Move file to Recycle bin if you plan to put the agent on a page with the Agent Chat web part.
- Leave it unselected if you want the .agent file to stay as the site's main agent, through an Agent Link web part open in the SharePoint chat pane, until March 2027.
After a successful upgrade the agent uses Microsoft Copilot Agent Builder for all future updates. You can no longer edit the original .agent file, and Copilot Agent Builder does not change it.
What changes after the upgrade
- Sharing. A .agent file uses SharePoint file permissions and can inherit access from its site or library. An upgraded agent uses agent-level sharing, set in Microsoft Copilot Agent Builder, with people, Microsoft 365 groups and email addresses, but not SharePoint groups. If the .agent file was shared with everyone in the organization, that access carries over. Otherwise the upgraded agent is private to its creator until they share it.
- Content access. Access to an agent does not grant access to the SharePoint or OneDrive content it draws on. People need permission to both the agent and its knowledge sources.
- Teams. The agent is upgraded but must be re-added. Remove the agent from the chat or channel, copy the agent's sharing link and post it to the chat or channel again.
- The site chat pane. An upgraded agent cannot be used in the site's chat pane, so it cannot be the main agent for the site. Add the Agent Chat web part to a page to make it prominent, and set the site's main agent to Copilot.
- Where people find it. The upgraded agent is available through the plugin store in the Copilot app according to your sharing and administrative policies. Not every upgraded agent is published broadly.
- History. Usage history from the .agent file does not transfer. Analytics for the upgraded agent start fresh, so capture any reporting you need for records or adoption before you finish the transition.
- Management. Owners edit, share and monitor the agent in the Copilot app, and administrators manage it through Agent 365.
How to convert a .agent file to a skill
A skill suits an agent that performs a focused, repeatable task inside one SharePoint site, such as drafting a document from the site's content or reviewing a document. Users run skills through Copilot in SharePoint.
Before you start, confirm the intended users have a Microsoft Copilot license, because only Copilot-licensed users can use Copilot in SharePoint. Confirm Copilot in SharePoint is available on the site, and that the agent's actions do not need to be available in the Copilot app or Teams.
- From mid-November 2026, prompt Copilot in SharePoint to use the
convert-agent-file-to-skillskill with the .agent file. You can create a site skill or a personal skill. - Optionally, add a Button web part to the page that opens Copilot in SharePoint with a prompt that runs the skill, so people can find it.
- Delete the .agent file once the skill works. The file moves to the skill location as a backup.
Microsoft's rule of thumb: use a skill when Copilot should perform a focused task or multistep workflow in the site, and use an agent when people need a customized experience for questions, retrieval or analysis.
How to find the .agent files in your tenant
- SharePoint, as an owner: open Build in SharePoint and look in the Owned by you Agents section.
- SharePoint, as an admin: use the agent reports in SharePoint Advanced Management to inventory agents, filter the agent registry to SharePoint agents, or search for agents on a site for bulk actions. See SharePoint Advanced Management for what the add-on includes.
- OneDrive: use the filters on the Home, Shared or Favorites views, or open My Files > Documents > Agents.
Prioritize agents with high usage, broad audiences, business-critical scenarios, custom instructions, pay-as-you-go dependencies, Teams distribution or a prominent place on a SharePoint page.
An admin checklist for the transition
Microsoft's preparation steps, in order:
- Inventory the .agent files in SharePoint and OneDrive.
- Identify each agent's owner, audience, purpose, knowledge sources and current access points.
- Choose the best-fit upgrade path for each.
- Upgrade or re-create the experience, then set up sharing and placement.
- Test with representative users and familiar prompts before switching.
- Archive or delete the original .agent file once the replacement is validated.
Also make sure agent creators can share agents, update your internal guidance and support process before the creation experience changes in mid-November, and learn about Agent 365 for governing upgraded agents.
Pay-as-you-go and licensing
SharePoint Agents pay-as-you-go applies only to .agent files. Upgraded agents follow the capabilities and licensing model for agents in the Microsoft Copilot app, and usage by unlicensed users is consolidated under Copilot app pay-as-you-go. SharePoint Agents pay-as-you-go does not apply to Copilot in SharePoint, which needs a Microsoft Copilot license for each user.
Agents, Copilot and archived SharePoint content
Agents and Copilot answer from the SharePoint content they can reach. Content moved with Microsoft 365 Archive leaves the SharePoint search index, so Copilot does not use it. With Squirrel and the AI Summarisation add-on, the stub that stays in SharePoint carries a summary of the archived document, so Copilot can still surface it. The detail is in keeping archived SharePoint content visible to Copilot.
Frequently asked questions
Are agents in SharePoint and OneDrive being retired?
No. Only the .agent file format is being retired. You can keep delivering named conversational experiences and focused site tasks grounded in SharePoint content through Copilot in SharePoint and Microsoft Copilot Agent Builder.
When do .agent files stop working?
Microsoft says existing .agent files continue to work until the end of March 2027, and stop responding after that. Plan to finish upgrades before the end of March.
Do I need to act now?
No. Nothing changes for existing .agent files today, and they can still be edited during the transition. Microsoft recommends starting with agents that are business-critical, widely shared, placed on SharePoint pages, added to Teams or dependent on pay-as-you-go.
Will Microsoft upgrade my agents automatically?
No. An agent owner or site owner reviews each .agent file and picks the path, so a named chat experience is not turned into a skill, or a site task into a wider agent, without a decision.
Do existing permissions and sharing transfer?
Partly. Sharing with everyone in the organization carries over. Anything narrower does not, and the upgraded agent is private until its owner shares it with people, groups or email addresses. SharePoint groups cannot be used for agent sharing.
What happens to usage history?
It does not transfer to the replacement. Analytics for the upgraded agent or skill start as a new experience.
Does this apply to government clouds?
Yes. All the upcoming changes apply to Microsoft Government Cloud. Converting to a skill becomes available there when Copilot in SharePoint arrives in the government cloud, which Microsoft lists as coming soon.
Related reading
- Microsoft Copilot and archived SharePoint content - what Copilot can and cannot see.
- SharePoint Advanced Management - the add-on with the agent reports.
- SharePoint and OneDrive storage changes, November 2026 - the other dated Microsoft changes landing this month.
- SharePoint admin center - where the admin settings live.
- SharePoint inactive files policy - Microsoft's archive policy for inactive content.
Mark Smith co-founded SmiKar Software in 2015 and has spent the past decade helping organisations solve Microsoft 365 data management challenges. He works with the SmiKar team to build solutions for SharePoint archiving, storage optimisation, governance and compliance, supporting customers from growing businesses through to Fortune 500 enterprises.
More about SmiKar
