How to Edit a Copilot Agent | Studio, Builder & GitHub

Copilot agents are edited in three environments: Microsoft Copilot Studio, the Agent Builder inside Microsoft 365, and the GitHub cloud agent file system — each one uses a different workflow.

A Copilot agent is only as useful as the instructions and knowledge it pulls from, so knowing how to edit one matters whether you’re tuning a customer service bot or a developer helper. The editing method depends entirely on where the agent was built, and the three main platforms treat edits quite differently — one uses a visual node editor, another lets you rewrite natural-language instructions, and the third is a markdown file you commit to a repository. This article walks through each route with the exact steps, the settings to change, and the common mistakes that trip people up.

Which Editing Platform Fits Your Agent?

The platform your agent lives on decides how you edit it. An agent built inside Microsoft 365 Copilot using the Agent Builder stays in that environment unless you export it to Copilot Studio for deeper customization. A conversational agent with branching topics and complex responses belongs in Copilot Studio, where you can edit topic nodes visually or jump into the code editor. Developer-focused agents that run inside GitHub or respond to commands live as markdown profile files in a repository. And the Agent Mode inside Visual Studio is a separate feature — it edits your code, not the agent itself, though you configure it from the same Copilot settings.

Choose based on what kind of agent you need to edit and whether you have the right license to save changes.

Editing in Microsoft Copilot Studio

Copilot Studio gives you the most control over an agent’s conversation flow through a visual topic editor and a code editor for advanced changes. Open your agent at copilotstudio.microsoft.com and navigate to the Topics page.

To edit a topic’s conversation path, click the topic you want to change. Each topic is a sequence of nodes. You can add a new node by clicking the Add node icon beneath any existing node and choosing the type of action or response. To delete a node, click the three dots on the node and select Delete. To modify the trigger conditions, click the three dots on the Trigger node and select Properties.

For advanced edits, open the code editor. Select Add a topic then From blank if you are starting fresh, or click an existing topic. In the upper-right corner, click More, then Open code editor. Delete the existing code, write the new YAML or JSON, click Save, then Close code editor. All edits persist only after you click the main Save button at the top of the page.

Before publishing, use the Test your agent chat panel to confirm the updated topic behaves as expected. Then click Publish to deploy to a live or demo website.

Editing via Agent Builder in Microsoft 365 Copilot

Agents built inside Microsoft 365 Copilot use the Agent Builder, which relies on natural-language instructions and connected knowledge sources rather than visual topic trees. Open Microsoft 365 Copilot, navigate to All agents, and click the agent you want to edit. Click the three dots next to the agent name and select Edit to enter edit mode.

Three main components are editable. The Instructions field controls the agent’s behavior and tone — you can rewrite it as plain English, such as “respond as a technical support specialist who gives short, direct answers.” The Knowledge sources section lets you add or remove files from SharePoint, Outlook, Teams, or external URLs. The Suggested prompts section lets you edit the example questions shown to users by clicking the edit icon next to each one.

After making changes, use the Test your agent panel to verify the responses. Click Save at the top to persist the edits, then Publish to push the updated agent live.

If you outgrow the Agent Builder’s capabilities, you can export the agent to Copilot Studio for full topic editing and custom actions.

Editing GitHub Copilot Cloud Agent Profiles

GitHub Copilot cloud agents are defined as markdown files with YAML frontmatter inside a repository. To edit one, navigate to github.com/copilot/agents and use the dropdown to select the repository containing the agent. Open the file in the .github/agents directory — the filename is the agent name plus .agent.md.

The file has two sections. The YAML frontmatter sets the agent’s name, description, allowed tools, and target. The name defaults to the filename if omitted. The description is required and explains what the agent does. The tools list controls what the agent can do — common values include read, edit, and search. The target, optional, sets the interface where the agent runs, such as vscode or github-copilot.

Below the YAML frontmatter, the markdown content is the actual prompt that defines the agent’s behavior. Rewrite this section to change how the agent responds. Save the file, commit it, and merge to the default branch. Refresh the agents tab at github.com/copilot/agents to see the updated profile.

Filenames may only contain periods, hyphens, underscores, lowercase letters, uppercase letters, and digits — any other character will cause the agent to fail to load.

Visual Studio Agent Mode: Not the Same Thing

Visual Studio includes an Agent Mode inside Copilot Chat, but this feature edits your code, not a Copilot agent. It is included here only to prevent confusion. Agent Mode accepts a high-level prompt and streams edits across your project. To enable the planning capability that supports complex multi-file changes, go to Tools, Options, GitHub, Copilot, and check the Enable Planning checkbox.

Microsoft’s Copilot Studio editing documentation covers the full topic editor and code editor workflows in detail.

What Can Go Wrong When Editing?

Several mistakes surface repeatedly across all three platforms, and most of them stop edits from saving or deploying correctly. The table below covers the most common ones and how to sidestep them.

Editing Workflow by Platform

The fastest path through any edit starts with identifying the platform. For an agent built in Copilot Studio, open the Topics page, edit the nodes or code, test, save, and publish. For an agent built inside Microsoft 365 Copilot, open it from All agents, edit the instructions or knowledge sources, test, save, and publish. For a GitHub cloud agent, edit the .agent.md file in the repository, commit to the default branch, and refresh the agents tab. Each platform has the same four-stage rhythm — open, modify, test, deploy — but the specific buttons and file formats differ.

When the edit involves adding a knowledge source, verify that the source URL or file is accessible to all users who will interact with the agent. When rewriting instructions, read them aloud once to catch phrasing that might confuse the agent’s response logic. And when editing in Copilot Studio’s code editor, save the code before closing the editor — closing without saving discards the changes even if the main Save button is used afterward.