---
title: Custom agents configuration
shortTitle: Custom agents configuration
intro: 'Reference for configuring {% data variables.copilot.custom_agents_short %}.'
versions:
  feature: copilot
contentType: reference
category:
  - Configure Copilot
---

This reference article provides detailed configuration information for {% data variables.copilot.custom_agents_short %}. For general information about creating {% data variables.copilot.custom_agents_short %}, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/create-custom-agents).

{% data reusables.copilot.custom-agents-ide-preview %}

## YAML frontmatter properties

The following table outlines the properties that you can configure for {% data variables.copilot.agent_profiles %} in {% data variables.product.prodname_dotcom_the_website %}, the {% data variables.copilot.copilot_cli_short %}, 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.

{% rowheaders %}

| Property      | Type      | Purpose |
| ------------- | ----------------------- | --- |
| `name`        | string     | Display name for the {% data variables.copilot.copilot_custom_agent_short %}. Optional. |
| `description` | **Required** string     | Description of the {% data variables.copilot.copilot_custom_agent_short %}'s purpose and capabilities |
| `target` | string     | Target environment or context for the {% data variables.copilot.copilot_custom_agent_short %} (`vscode` or `github-copilot`). If unset, defaults to both environments. |
| `tools`       | list of strings, string | List of tool names the {% data variables.copilot.copilot_custom_agent_short %} can use. Supports both a comma separated string and yaml string array. If unset, defaults to all tools. See [Tools](#tools). |
| `model`       | string | Model to use when this {% data variables.copilot.copilot_custom_agent_short %} executes. If unset, inherits the default model. |
| `disable-model-invocation`  | boolean | Disables {% data variables.copilot.copilot_cloud_agent %} from automatically using this {% data variables.copilot.copilot_custom_agent_short %} 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 {% data variables.copilot.copilot_custom_agent_short %} 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 | **{% data variables.release-phases.retired_caps %}**. Use `disable-model-invocation` and `user-invocable` instead. Enables {% data variables.copilot.copilot_cloud_agent %} to automatically use this {% data variables.copilot.copilot_custom_agent_short %} 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 {% data variables.copilot.copilot_custom_agent_short %}. **Not used in {% data variables.product.prodname_vscode_shortname %} and other IDE {% data variables.copilot.custom_agents_short %}.** |
| `metadata`   | object consisting of a name and value pair, both strings | Allows annotation of the agent with useful data. **Not used in {% data variables.product.prodname_vscode_shortname %} and other IDE {% data variables.copilot.custom_agents_short %}.** |

{% endrowheaders %}

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 {% data variables.product.prodname_vscode_shortname %} and other IDE {% data variables.copilot.custom_agents_short %} are currently not supported for {% data variables.copilot.copilot_cloud_agent %} on {% data variables.product.prodname_dotcom_the_website %}. They are ignored to ensure compatibility.
> * For more information on {% data variables.copilot.copilot_custom_agent_short %} file structure in {% data variables.product.prodname_vscode_shortname %}, see [{% data variables.copilot.custom_agents_caps_short %} in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/copilot/customization/custom-agents#_custom-agent-file-structure) in the {% data variables.product.prodname_vscode_shortname %} documentation.

## Tools

The {% data variables.copilot.copilot_custom_agent_short %} `tools` property controls which tools are available to your agent, including those from MCP servers.

Your {% data variables.copilot.copilot_custom_agent_short %} will have access to MCP server tools that have been configured in both its {% data variables.copilot.agent_profile %} and/or the repository settings. For more information on configuring shared repository MCP servers on {% data variables.product.github %}, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers).

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 {% data variables.copilot.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](#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 {% data variables.copilot.copilot_custom_agent_short %}. 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 {% data variables.product.prodname_vscode_shortname %} 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 {% data variables.copilot.agent_profile %} without causing problems.

### Tool aliases

The following tool aliases are available for {% data variables.copilot.custom_agents_short %}. All aliases are case insensitive:

| Primary alias | Compatible aliases                        | {% data variables.copilot.copilot_cloud_agent_short_cap_c %} 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`                                       | "{% data variables.copilot.copilot_custom_agent_caps_short %}" tools                                             | Allows a different {% data variables.copilot.copilot_custom_agent_short %} to be invoked to accomplish a task. |
| `web`         | `WebSearch`, `WebFetch`                      | Currently not applicable for {% data variables.copilot.copilot_cloud_agent_short %}. | Allows fetching content from URLs and performing a web search                                            |
| `todo`        | `TodoWrite`                                  | Currently not applicable for {% data variables.copilot.copilot_cloud_agent_short %}. | Creates and manages structured task lists. Not supported in {% data variables.copilot.copilot_cloud_agent_short %} today, but supported by {% data variables.product.prodname_vscode_shortname %}. |

### Tool names for "out-of-the-box" MCP servers

The following MCP servers are available out-of-box for {% data variables.copilot.copilot_cloud_agent %} 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 {% data variables.copilot.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:

```text
---
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: {% raw %}${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}{% endraw %}
---

Prompt with suggestions for behavior and output
```

The `mcp-servers` property in an {% data variables.copilot.agent_profile %} is a YAML representation of the JSON configuration format used to configure MCP servers for repositories on {% data variables.product.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 {% data variables.product.github %} that are relevant to {% data variables.copilot.custom_agents_short %}. For more information about the JSON configuration format, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers#writing-a-json-configuration-for-mcp-servers).

### MCP server type

For compatibility, the `stdio` type used by Claude Code and {% data variables.product.prodname_vscode_shortname %} is mapped to {% data variables.copilot.copilot_cloud_agent_short %}'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 [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/configure-secrets-and-variables).

{% data variables.copilot.copilot_custom_agent_caps_short %} MCP configuration supports the same environment variable and secret replacement capabilities as existing repository-level MCP configurations. Similar to repository-level configurations, secrets and variables can be sourced from Agents secrets and variables for {% data variables.copilot.copilot_cloud_agent %}, configured at either the organization or repository level. The syntax for referencing these values has been expanded to support common patterns used in {% data variables.product.prodname_actions %} and Claude Code.

Both the repository-level MCP JSON configuration and the {% data variables.copilot.copilot_custom_agent_short %} YAML configuration support the following syntax patterns:

* `$COPILOT_MCP_ENV_VAR_VALUE` - Environment variable and header
* `${COPILOT_MCP_ENV_VAR_VALUE}` - Environment variable and header (Claude Code syntax)
* `${COPILOT_MCP_ENV_VAR_VALUE:-default}` - Environment variable and header with default

The {% data variables.copilot.copilot_custom_agent_short %} YAML configuration supports the following additional syntax patterns:

* `{% raw %}${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}{% endraw %}` - Environment variable and header
* `{% raw %}${{ vars.COPILOT_MCP_ENV_VAR_VALUE }}{% endraw %}` - Environment variable and header

## Example {% data variables.copilot.agent_profile %} configurations

{% data reusables.copilot.custom-agents-example-profiles %}

## Processing of {% data variables.copilot.custom_agents_short %}

### {% data variables.copilot.custom_agents_caps_short %} names

In the case of naming conflicts, the lowest level configuration overrides higher-level configurations. This means that a repository-level agent would take precedence over an organization-level agent, and the organization-level agent would override an enterprise-level agent.

### Versioning

{% data variables.copilot.copilot_custom_agent_caps_short %} versioning is based on Git commit SHAs for the {% data variables.copilot.agent_profile %} file. This allows you to create branches or tags with different versions of {% data variables.copilot.custom_agents_short %} as needed. When you assign a {% data variables.copilot.copilot_custom_agent_short %} to a task, the {% data variables.copilot.copilot_custom_agent_short %} will be instantiated using the latest version of the {% data variables.copilot.agent_profile %} for that repository and branch. When the agent creates a pull request, interactions within the pull request use the same version of the {% data variables.copilot.copilot_custom_agent_short %} for consistency.

### Tools processing

The `tools` list filters the set of tools that are made available to the agent - whether built-in or sourced from MCP servers. When you configure tools in your {% data variables.copilot.agent_profile %}, the behavior depends on what you specify:

* If no tools are specified, all available tools are enabled
* An empty tools list (`tools: []`) disables all tools
* A specific list (`tools: [...]`) enables only those tools

### MCP server configurations

For MCP server configurations, there is a specific processing order that ensures proper override behavior: out-of-the-box MCP configurations (like the {% data variables.product.github %} MCP) are processed first, followed by the {% data variables.copilot.copilot_custom_agent_short %} MCP configuration, and finally MCP configurations specified through repository settings. This allows each level to override settings from the previous level as appropriate.

## Further reading

* [AUTOTITLE](/copilot/how-tos/copilot-cli)
* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#custom-agents-reference)