Text of docs.github.com › en › copilot › reference › custom-agents-configuration as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Custom agents configuration - GitHub Docs

Skip to main content Skip to content Collapse sidebar Expand sidebar Custom agents configuration Reference for configuring custom agents. In this article This reference article provides detailed configuration information for custom agents. For general information about creating custom agents, see Creating custom agents for Copilot cloud agent . Note Custom agents are in public preview for JetBrains IDEs, Eclipse, and Xcode, and subject to change.

YAML frontmatter properties The following table outlines the properties that you can configure for agent profiles in GitHub.com, the Copilot CLI, and supported IDEs (unless otherwise noted). Any environment-specific behavior is noted in the property description. The configuration file's name (minus .md or .agent.md ) is used for deduplication between levels so that the lowest level configuration takes precedence. Property Type Purpose name string Display name for the custom agent.

Optional. description Required string Description of the custom agent's purpose and capabilities target string Target environment or context for the custom agent ( vscode or github-copilot ). If unset, defaults to both environments. tools list of strings, string List of tool names the custom agent can use. Supports both a comma separated string and yaml string array. If unset, defaults to all tools. See Tools . model string Model to use when this custom agent executes.

If unset, inherits the default model. disable-model-invocation boolean Disables Copilot in the cloud from automatically using this custom agent based on task context. When true , the agent must be manually selected. Setting disable-model-invocation: true is equivalent to infer: false . If both are set, disable-model-invocation takes precedence. If unset, defaults to false . user-invocable boolean Controls whether this custom agent can be selected by a user.

When false , the agent cannot be manually selected and can only be accessed programmatically. If unset, defaults to true . infer boolean Retired . Use disable-model-invocation and user-invocable instead. Enables Copilot in the cloud to automatically use this custom agent based on task context. When false , the agent must be manually selected. If unset, defaults to true . mcp-servers object Additional MCP servers and tools that should be used by the custom agent.

Not used in VS Code and other IDE custom agents. metadata object consisting of a name and value pair, both strings Allows annotation of the agent with useful data. Not used in VS Code and other IDE custom agents. Define the agent's behavior, expertise, and instructions in the Markdown content below the YAML frontmatter. The prompt can be a maximum of 30,000 characters. Note The argument-hint and handoffs properties from VS Code and other IDE custom agents are currently not supported for Copilot in the cloud on GitHub.com.

They are ignored to ensure compatibility. For more information on custom agent file structure in VS Code, see Custom agents in VS Code in the VS Code documentation. Tools The custom agent tools property controls which tools are available to your agent, including those from MCP servers. Your custom agent will have access to MCP server tools that have been configured in both its agent profile and/or the repository settings.

For more information on configuring shared repository MCP servers on GitHub, see Configure MCP servers for your repository . You can configure tools using the following approaches: Enable all available tools : Omit the tools property entirely or use tools: ["*"] to enable all available tools. This will include all MCP server tools configured in the agent profile and/or repository settings. Enable specific tools : Provide a list of specific tool names or aliases (for example, tools: ["read", "edit", "search"] ) to enable only those tools.

For available tool aliases, see Tool aliases below. Note that if your repository has MCP servers configured, you can choose to make only specific tools from those servers available to your custom agent. Tool names from specific MCP servers can be prefixed with the server name followed by a / . For example, some-mcp-server/some-tool . You can also explicitly enable all tools from a specific MCP server using some-mcp-server/* .

Tools from VS Code extensions can use the extension name as a proxy, like azure.some-extension/some-tool . Disable all tools : Use an empty list ( tools: [] ) to disable all tools for the agent. All unrecognized tool names are ignored, which allows product-specific tools to be specified in an agent profile without causing problems. Tool aliases The following tool aliases are available for custom agents. All aliases are case insensitive: Primary alias Compatible aliases Cloud agent mapping Purpose execute shell , Bash , powershell Shell tools: bash or powershell Execute a command in the appropriate shell for the operating system. read Read , NotebookRead view Read file contents. edit Edit , MultiEdit , Write , NotebookEdit Edit tools: e.g. str_replace , str_replace_editor Allow LLM to edit.

Exact arguments can vary. search Grep , Glob search Search for files or text in files. agent custom-agent , Task "Custom agent" tools Allows a different custom agent to be invoked to accomplish a task. web WebSearch , WebFetch Currently not applicable for Copilot in the cloud. Allows fetching content from URLs and performing a web search todo TodoWrite Currently not applicable for Copilot in the cloud. Creates and manages structured task lists.

Not supported in Copilot in the cloud today, but supported by VS Code. Tool names for "out-of-the-box" MCP servers The following MCP servers are available out-of-box for Copilot in the cloud and can be referenced using namespacing: MCP server name Available tools github All read-only tools are available by default, but the token the server receives is scoped to the source repository. github/* includes all of them, or you can reference github/<tool name> where <tool name> is a value from the MCP server documentation. playwright All playwright tools are available by default, but the server is configured to only access localhost. playwright/* includes all of them, or you can reference playwright/<tool name> where <tool name> is a value from the MCP server documentation.

By default the token it has access to is scoped to the source code repository. MCP server configuration details The following sample agent profile shows an agent with an MCP server and a secret configured. Additionally, only one tool from the MCP server has been enabled in the tools property in the YAML frontmatter: --- name: my-custom-agent-with-mcp description: Custom agent description tools: ['tool-a', 'tool-b', 'custom-mcp/tool-1'] mcp-servers: custom-mcp: type: 'local' command: 'some-command' args: ['--arg1', '--arg2'] tools: ["*"] env: ENV_VAR_NAME: ${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }} --- Prompt with suggestions for behavior and output The mcp-servers property in an agent profile is a YAML representation of the JSON configuration format used to configure MCP servers for repositories on GitHub.

Most sub-properties are the same as the JSON representation. The following sections describe changes from the initial implementation of MCP configuration in repositories on GitHub that are relevant to custom agents. For more information about the JSON configuration format, see Configure MCP servers for your repository . MCP server type For compatibility, the stdio type used by Claude Code and VS Code is mapped to Copilot in the cloud's local type.

MCP server environment variables and secrets Note If your MCP server requires secrets or environment variables, these must be configured as Agents secrets or variables at either the organization or repository level. For more information, see Configure secrets and variables for Copilot cloud agent . Custom agent MCP configuration supports the same environment variable and secret replacement capabilities as existing repository-level M

The rest of this page is on the live site.