Pro User
  • All of Microsoft
  • My Role
    • All in My Role
    • Pro User
    • Administrator
  • Focus
    • All in Focus
    • Microsoft Ignite 2026
    • Microsoft Copilot
    • All about AI
    • M365 Admin
    • What's Hot
    • M365 Release
Timespan
explore our new search
SharePoint agents: upgrade .agent files to Agent Builder
SharePoint Online

SharePoint agents: upgrade .agent files to Agent Builder

by HubSite 365 about Ami Diamond [MVP]

M365 Adoption Lead | 2X Microsoft MVP |Copilot | SharePoint Online | Microsoft Teams |Microsoft 365| at CloudEdge

Move an existing SharePoint agent into Agent Builder, then review its sharing and permissions before users rely on it.

Key insights

  • New agents created from SharePoint or OneDrive open in Microsoft Copilot Agent Builder during the transition.
  • Traditional SharePoint .agent files are scheduled to stop working at the end of March 2027.
  • The upgrade prompt lets you keep the original .agent file or move it to the Recycle Bin.
  • After upgrading, an agent may be private; review its sharing and permissions separately.
  • The SharePoint content used as knowledge can remain in place after the agent is upgraded.

SharePoint agents are moving from .agent files to Microsoft Copilot Agent Builder, changing where users create, update, and share their agents. SharePoint site owners and people responsible for existing agents should review their agent files and plan how each one will be maintained. Ami Diamond [MVP] demonstrates the upgrade flow and creation of a new agent in a YouTube walkthrough.

What's new

Traditional SharePoint agents were stored as .agent files in a SharePoint or OneDrive library. Microsoft is shifting new agent creation to Agent Builder: beginning in mid-November 2026, creating an agent from SharePoint or OneDrive opens Agent Builder rather than producing the traditional file. The transition is expected to complete in early December 2026.

Existing agents can be upgraded through the interface. Microsoft plans to retire the traditional .agent approach at the end of March 2027, and agents that have not been upgraded by then will no longer be accessible. The change is primarily about the agent’s management model; the SharePoint knowledge source itself does not have to move just because the agent is upgraded.

After upgrading, the agent is managed as a Microsoft 365 agent in Agent Builder. Its configuration can include instructions, skills, and knowledge. Ami’s demonstration shows the knowledge source continuing to point to a SharePoint folder after conversion, while future edits happen in the Agent Builder experience rather than by editing the original file.

Who it is for and what you need

This change matters to SharePoint site owners, agent creators, and administrators who maintain or provide access to custom agents. Start by finding the .agent files in the relevant SharePoint or OneDrive libraries and identifying which are still in use. A basic inventory should include each agent’s purpose, owner, knowledge source, and audience.

Do not assume that every existing agent needs the same destination. A custom agent that should remain a named conversational assistant across Microsoft 365 may be a candidate for upgrading. A focused repeatable process may fit a skill, while a simple question-answering need about one site may be served by the built-in Copilot experience in SharePoint. Retiring an unused or duplicated agent is another option.

New agents created from SharePoint or OneDrive are routed to Agent Builder as the rollout proceeds. The transition schedule in current guidance places the start in mid-November 2026, expected completion in early December 2026, and retirement of traditional agents at the end of March 2027.

How it works

For an existing agent, the upgrade begins from its .agent file in the SharePoint library. In Ami Diamond’s example, the file appears in the document library; opening it and selecting Edit agent reveals the upgrade option. The interface offers an upgrade to a Microsoft 365 agent and presents a choice about what to do with the original file.

  1. Locate the .agent file in the SharePoint or OneDrive library. Review its purpose and current audience before changing it.
  2. Open the agent and choose Edit agent. Select Upgrade to Microsoft 365 agent from the upgrade prompt.
  3. Choose whether to keep the original agent file or move it to the Recycle Bin, then confirm the upgrade.
  4. When the upgrade completes, open the agent in Agent Builder and review its instructions, skills, and knowledge source.
  5. Set up access for the intended audience and test the agent with representative questions.

In the demonstrated flow, the upgraded agent is initially private and accessible only to its creator. The completion message says previous permissions could not be saved during the upgrade and prompts the owner to share the Microsoft 365 agent to make it available to others. This is a key operational difference: access granted through the SharePoint site should not be treated as a substitute for sharing the upgraded agent.

Creating a new agent from SharePoint follows the newer route directly into Agent Builder. The demonstrated new agent includes instructions and skills and has a knowledge scope associated with the document library. Check that scope and adjust the source to the intended content rather than assuming the initial selection is correct.

Limitations and alternatives

The main migration risk is losing expected access: the upgraded agent may be private, and prior permissions may not carry over. Owners should re-share the agent with the people who need it and verify access with an appropriate user. Keep the original .agent file during the transition if you need it as a reference; the upgrade prompt makes this a choice.

Also review how the agent is used before selecting a migration path. The transition guidance identifies Copilot in SharePoint for general questions about a site, skills for focused repeatable tasks, and an upgraded Microsoft 365 agent for a named assistant intended to be available across Microsoft 365. An agent that no longer has a clear purpose or owner can be retired instead.

Where an agent is embedded on a SharePoint page, page configuration may need review; the guidance identifies the Agent Chat web part for the new experience. Check any Teams use and update references or sharing as needed. Test the converted agent and its knowledge scope before relying on it for business processes.

Sources

Frequently asked questions

When do traditional SharePoint .agent files stop working?

Traditional SharePoint .agent files are scheduled to stop working at the end of March 2027. The transition to creating new agents in Agent Builder begins in mid-November 2026 and is expected to complete in early December.

How do I upgrade a SharePoint agent to Agent Builder?

Open the .agent file, choose Edit agent, and select Upgrade to Microsoft 365 agent. Decide whether to keep the original file or move it to the Recycle Bin, then review the upgraded agent in Agent Builder.

Will my existing SharePoint agent permissions transfer?

Do not assume they will. The demonstrated upgrade reports that previous permissions could not be saved, and the upgraded agent may be private until you share it with the intended audience.

Do I need to move the SharePoint files used as agent knowledge?

No. The transition changes how the agent is managed; the SharePoint content used as its knowledge source can remain where it is. Review the source and scope in Agent Builder after upgrading.