Edit an agent in SharePoint

Applies To
Microsoft365.com

Important

This article explains how to edit a .agent file.

Upgrades are coming mid-November 2026 to agents in SharePoint. Learn more in Upgrade agents in SharePoint.

You can edit an agent so that it's tailored to your team's needs by:

  • Customizing its branding and purpose.
  • Adding or removing which sites, pages, lists, and files your agent should include as knowledge sources beyond the current SharePoint site.
  • Refining the agent's behavior by writing customized prompts tailored to the purpose and scope of the agent.

Before you begin

To edit an agent, you must:

  • Have a Microsoft Copilot license, or belong to an organization that has pay-as-you-go billing enabled for agents in SharePoint.
  • Have edit permissions on the SharePoint site and the agent file.

Note

The agent can use information from the sites, pages, and files that you include as sources and that you have permission to access. It might also use its broader knowledge to answer questions. The Only use specified sources setting prioritizes your selected sources but doesn't block general knowledge. Make sure you and the people you share the agent with have access to all the sources you want the agent to use.

Open an agent for editing

You can open the agent builder from any of these locations:

  • In the SharePoint agent chat pane, select the agent, select the ellipsis next to it, and then select Edit agent.

    Screenshot of the SharePoint agent menu with Edit agent highlighted.

  • Find the .agent file, open its context menu, and then select Edit.

    Screenshot of the context menu for a SharePoint agent file with Edit highlighted.

You can also start editing while using the agent in Microsoft Copilot app or Teams.

Customize the agent's identity

On the Overview tab, update the agent's name, icon, and purpose. Use the purpose to explain what the agent does and how people should use it.

Screenshot of the Edit agent dialog on the Overview tab, with fields for the agent name, icon, and purpose and an agent preview.

Specify the agent's knowledge sources

On the Sources tab, add or remove SharePoint sites, document libraries, folders, pages, lists, and files. Search by site title, enter a URL, or select From OneDrive. People who use the agent receive information only from sources that they already have permission to access.

Screenshot of the Edit agent dialog on the Sources tab, with controls to search for a SharePoint source, enter a URL, or select From OneDrive.

Screenshot of the SharePoint source picker for selecting sites, libraries, lists, pages, folders, and files for an agent.

Your agent starts searching for information within the sources you select but might refer to its broader knowledge to provide complete and consistent answers. Use the toggle to have the agent prioritize the selected knowledge sources in such cases.

Refine the agent's behavior

On the Behavior tab, enter a welcome message, starter prompts, and instructions for the agent. Use the agent preview to test the agent, and adjust the instructions and starter prompts as needed.

Screenshot of the Edit agent dialog on the Behavior tab, with fields for welcome messaging, starter prompts, and agent instructions and an agent preview.

Select Save and close. The updated agent is then available to use in SharePoint and share with others.

Note

  • When a SharePoint hub site is included as the source for the agent, it automatically includes its associated sites. Your agent uses information from both the hub site and its associated sites to respond.
  • When you share an agent with others, ensure they have access to the sources for optimal experience.

FAQ and data handling

To learn more about agents in SharePoint, see Frequently asked questions about agents in SharePoint.

For more information on how Microsoft Copilot works, see Data, Privacy, and Security for Microsoft Copilot.