Updates for VS Code custom agents (#58483)
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Jenni C <97056108+dihydroJenoxide@users.noreply.github.com>
This commit is contained in:
Sarita Iyer
@@ -53,9 +53,9 @@ You can define {% data variables.copilot.agent_profiles %} at the repository lev
|
||||
|
||||
## Where you can use {% data variables.copilot.custom_agents_short %}
|
||||
|
||||
Once created, your {% data variables.copilot.custom_agents_short %} are available wherever you can use {% data variables.copilot.copilot_coding_agent %}, including {% data variables.product.prodname_dotcom_the_website %} (the agents tab and panel, issue assignment, pull requests), the {% data variables.copilot.copilot_cli %}, and {% data variables.product.prodname_vscode %} (as chat modes). Each interaction maintains consistency based on the agent's defined profile, ensuring targeted support tailored to your specific needs.
|
||||
Once created, your {% data variables.copilot.custom_agents_short %} are available wherever you can use {% data variables.copilot.copilot_coding_agent %}, including {% data variables.product.prodname_dotcom_the_website %} (the agents tab and panel, issue assignment, pull requests), the {% data variables.copilot.copilot_cli %}, and {% data variables.product.prodname_vscode %}. Each interaction maintains consistency based on the agent's defined profile, ensuring targeted support tailored to your specific needs.
|
||||
|
||||
{% data variables.copilot.agent_profiles_caps %} can be used directly in {% data variables.product.prodname_vscode %} as chat modes, though some properties may differ between the two environments. For more information on chat modes, see [Use chat modes in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes?utm_source=docs-vscode-custom-agents&utm_medium=docs&utm_campaign=universe25post).
|
||||
{% data variables.copilot.agent_profiles_caps %} can be used directly in {% data variables.product.prodname_vscode %}, though some properties may function differently or be ignored between the {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_vscode_shortname %} environments. See [{% data variables.copilot.custom_agents_caps_short %} in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/copilot/customization/custom-agents?utm_source=docs-signup-custom-agents&utm_medium=docs&utm_campaign=universe25post) in the {% data variables.product.prodname_vscode_shortname %} documentation.
|
||||
|
||||
## Next steps
|
||||
|
||||
|
||||
@@ -22,9 +22,10 @@ topics:
|
||||
> Organization and enterprise owners can create organization and enterprise-level {% data variables.copilot.custom_agents_short %} in a `.github-private` repository that are available across all repositories within their organization or enterprise. For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents).
|
||||
|
||||
1. Optionally, select the branch you want to create the {% data variables.copilot.agent_profile %} in. The default is the main branch.
|
||||
1. Click {% octicon "copilot" aria-label="Select a custom agent" %}, then click **{% octicon "plus" aria-label="Plus button" %} Create an agent**. This will open a template agent profile called `my-agent.md` in the `.github/agents` directory of your target repository.
|
||||
1. Click {% octicon "copilot" aria-label="Select a custom agent" %}, then click **{% octicon "plus" aria-label="Plus button" %} Create an agent**. This will open a template agent profile called `my-agent.agent.md` in the `.github/agents` directory of your target repository.
|
||||
1. If you are creating an organization or enterprise-level custom agent, delete the `.github/` portion of the file path to move your template to the root `agents` directory.
|
||||
1. Edit the filename and configure the {% data variables.copilot.agent_profile %}, including the name, description, tools, and prompts. For more information on what the {% data variables.copilot.agent_profile %} can include, see the section below.
|
||||
1. Edit the filename (the text before `.agent.md`), selecting a unique, descriptive name that identifies the agent's purpose. Note that the filename may only contain the following characters: `.`, `-`, `_`, `a-z`, `A-Z`, `0-9`.
|
||||
1. Configure the {% data variables.copilot.agent_profile %}, including the name, description, tools, and prompts. For more information on what the {% data variables.copilot.agent_profile %} can include, see the section below.
|
||||
1. Commit the file to the repository and merge it into the default branch. Go back to the agents tab and refresh the page if needed. Your custom agent will now appear in the dropdown when you click {% octicon "copilot" aria-hidden="true" aria-label="copilot" %} in the prompt box.
|
||||
|
||||
## Configuring an {% data variables.copilot.agent_profile %}
|
||||
@@ -35,10 +36,11 @@ For detailed configuration information about YAML properties, tools, MCP server
|
||||
|
||||
To configure your {% data variables.copilot.agent_profile %}:
|
||||
|
||||
1. Choose a `name` for your {% data variables.copilot.copilot_custom_agent_short %}. Select a unique, descriptive name that identifies the agent's purpose.
|
||||
1. Write a brief `description` explaining what your agent does and its specific capabilities or domain expertise.
|
||||
1. Optionally, write a `name` for your {% data variables.copilot.copilot_custom_agent_short %}. If unset, the name will default to the filename (without the `.md` or `.agent.md` suffix).
|
||||
1. Write a brief `description` (required) explaining what your agent does and its specific capabilities or domain expertise.
|
||||
1. In the `tools` property, define which tools the agent can use. This is a list of tool names or aliases, including tools from MCP servers configured in the repository settings or the {% data variables.copilot.agent_profile %} (for example, `tools: ["read", "edit", "search", "some-mcp-server/tool-1"]`). If you omit this property, the agent will have access to all available tools.
|
||||
1. If creating an organization or enterprise level agent, you can use the `mcp-servers` property to optionally configure MCP servers that will be available only to this agent to extend its capabilities.
|
||||
1. Optionally, set the `target` property to `vscode` or `github-copilot` if you want to only use the agent in a specific environment. The agent will be available in both environments if you omit the property.
|
||||
1. Write the agent's prompt. Define the agent's behavior, expertise, and instructions in the Markdown content below the YAML frontmatter.
|
||||
|
||||
## Example {% data variables.copilot.agent_profiles %}
|
||||
@@ -57,11 +59,11 @@ When {% data variables.product.prodname_copilot_short %} opens pull requests, it
|
||||
|
||||
For more information on using {% data variables.copilot.copilot_coding_agent %}, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr).
|
||||
|
||||
### Using {% data variables.copilot.custom_agents_short %} as {% data variables.product.prodname_vscode_shortname %} chat modes
|
||||
### Using {% data variables.copilot.custom_agents_short %} in {% data variables.product.prodname_vscode_shortname %}
|
||||
|
||||
You can also use your custom {% data variables.copilot.agent_profiles %} directly in {% data variables.product.prodname_vscode %} as chat modes. In {% data variables.product.prodname_vscode_shortname %}, you switch between chat modes using the mode dropdown in the Chat view, allowing you to access specialized configurations for different tasks like planning, code editing, or research. For more information, see [Use chat modes in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes&utm_source=docs-vscode-custom-agents&utm_medium=docs&utm_campaign=universe25post).
|
||||
You can also use your custom {% data variables.copilot.agent_profiles %} directly in {% data variables.product.prodname_vscode %}. In {% data variables.product.prodname_vscode_shortname %}, you switch between {% data variables.copilot.custom_agents_short %} using the mode dropdown in the Chat view, allowing you to access specialized configurations for different tasks like planning, code editing, or research. For more information, see [{% data variables.copilot.custom_agents_caps_short %} in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/copilot/customization/custom-agents).
|
||||
|
||||
Note that some properties may function differently between the {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_vscode_shortname %} environments. For more information, see [AUTOTITLE](/copilot/reference/custom-agents-configuration).
|
||||
Note that some properties may function differently, or be ignored, between the {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_vscode_shortname %} environments. For more information on supported properties, see [AUTOTITLE](/copilot/reference/custom-agents-configuration#yaml-frontmatter-properties).
|
||||
|
||||
## Next steps
|
||||
|
||||
|
||||
@@ -13,21 +13,23 @@ This reference article provides detailed configuration information for {% data v
|
||||
|
||||
## YAML frontmatter properties
|
||||
|
||||
The following table outlines the properties that are supported in repository-level {% data variables.copilot.agent_profiles %}, organization or enterprise level {% data variables.copilot.agent_profiles %}, and in {% data variables.product.prodname_vscode_shortname %} chat modes.
|
||||
The following table outlines the properties that are supported in repository-level {% data variables.copilot.agent_profiles %}, organization or enterprise level {% data variables.copilot.agent_profiles %}, and in {% data variables.product.prodname_vscode_shortname %}.
|
||||
|
||||
{% rowheaders %}
|
||||
|
||||
| Property | Type | Purpose | Repository | Organization / enterprise | {% data variables.product.prodname_vscode_shortname %} chat modes |
|
||||
| Property | Type | Purpose | Repository | Organization / enterprise | {% data variables.product.prodname_vscode_shortname %} |
|
||||
| ------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------- | ------------------ |
|
||||
| `name` | **Required** string | Unique name for the {% data variables.copilot.copilot_custom_agent_short %}.<br/> Lowest level configuration takes precedence when there is a naming conflict. | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
|
||||
| `description` | **Required** string | Description of the {% data variables.copilot.copilot_custom_agent_short %}'s purpose purpose and capabilities | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
|
||||
| `name` | string | Unique name for the {% data variables.copilot.copilot_custom_agent_short %}. Optional, if unset defaults to the filename (without `.md` or `.agent.md` suffix). <br/> Lowest level configuration takes precedence when there is a naming conflict. | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
|
||||
| `description` | **Required** string | Description of the {% data variables.copilot.copilot_custom_agent_short %}'s purpose and capabilities | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
|
||||
| `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. | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
|
||||
| `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). | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
|
||||
| `mcp-servers` | object | Additional MCP servers and tools that should be used by the {% data variables.copilot.copilot_custom_agent_short %}. | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} |
|
||||
| `metadata` | object consisting of a name and value pair, both strings | Allows annotation of the agent with useful data | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} |
|
||||
|
||||
{% endrowheaders %}
|
||||
|
||||
> [!NOTE]
|
||||
> The `model` property from {% data variables.product.prodname_vscode_shortname %} chat modes is not supported for {% data variables.copilot.copilot_coding_agent %}. It is ignored to ensure compatibility.
|
||||
> The `model`, `argument-hint`, and `handoffs` properties from {% data variables.product.prodname_vscode_shortname %} {% data variables.copilot.custom_agents_short %} are currently not supported for {% data variables.copilot.copilot_coding_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
|
||||
|
||||
|
||||
@@ -75,7 +75,7 @@ Test this agent by giving it a task to complete:
|
||||
1. Go to the agents tab at [https://github.com/copilot/agents](https://github.com/copilot/agents?ref_product=copilot&ref_type=engagement&ref_style=text&utm_source=docs-web-copilot-custom-agent&utm_medium=docs&utm_campaign=universe25post).
|
||||
1. Using the dropdown menus in the text box, select the repository and branch you're comfortable testing with (ideally one with a minimal or outdated README).
|
||||
1. Click {% octicon "copilot" aria-hidden="true" aria-label="copilot" %}, then click **{% octicon "plus" aria-label="Plus button" %} Create an agent**.
|
||||
1. An {% data variables.copilot.agent_profile %} template called `my-agent.md` will open in the `.github/agents` directory, in the repository you chose. Name the file `readme-specialist.md` and paste in the example {% data variables.copilot.agent_profile %}.
|
||||
1. An {% data variables.copilot.agent_profile %} template called `my-agent.agent.md` will open in the `.github/agents` directory, in the repository you chose. Name the file `readme-specialist.agent.md` and paste in the example {% data variables.copilot.agent_profile %}.
|
||||
1. Commit and merge this file into your repository's default branch. Go back to the agents tab (you may need to refresh the page), and in the text box, select your "readme-specialist" agent from the dropdown.
|
||||
1. In the text box, enter a task for the agent (such as the example below) and click **{% octicon "paper-airplane" aria-label="Start task" %} Start task** or press <kbd>Return</kbd>.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user