diff --git a/api/references/contribution-points.md b/api/references/contribution-points.md index aa0ecc09e6..695d8c6d35 100644 --- a/api/references/contribution-points.md +++ b/api/references/contribution-points.md @@ -13,6 +13,7 @@ MetaDescription: To extend Visual Studio Code, your extension (plug-in) declares - [`authentication`](/api/references/contribution-points#contributes.authentication) - [`breakpoints`](/api/references/contribution-points#contributes.breakpoints) +- [`chatAgents`](/api/references/contribution-points#contributes.chatAgents) - [`chatInstructions`](/api/references/contribution-points#contributes.chatInstructions) - [`chatPromptFiles`](/api/references/contribution-points#contributes.chatPromptFiles) - [`chatSkills`](/api/references/contribution-points#contributes.chatSkills) @@ -28,6 +29,8 @@ MetaDescription: To extend Visual Studio Code, your extension (plug-in) declares - [`jsonValidation`](/api/references/contribution-points#contributes.jsonValidation) - [`keybindings`](/api/references/contribution-points#contributes.keybindings) - [`languages`](/api/references/contribution-points#contributes.languages) +- [`languageModelChatProviders`](/api/references/contribution-points#contributes.languageModelChatProviders) +- [`languageModelTools`](/api/references/contribution-points#contributes.languageModelTools) - [`menus`](/api/references/contribution-points#contributes.menus) - [`problemMatchers`](/api/references/contribution-points#contributes.problemMatchers) - [`problemPatterns`](/api/references/contribution-points#contributes.problemPatterns) @@ -83,6 +86,33 @@ Usually a debugger extension will also have a `contributes.breakpoints` entry wh } ``` +## contributes.chatAgents + +Contributes [custom agents](/docs/agent-customization/custom-agents.md) for Copilot Chat. Custom agents are pre-configured AI personas with specific instructions and tool restrictions. Use this contribution point to bundle reusable custom agents with your extension so they appear alongside user-defined agents in the agents dropdown. + +Each entry requires a `path` to a `.agent.md` file relative to the extension root. You can optionally specify a `when` clause to conditionally enable the agent. Specify the agent's `name`, `description`, and other metadata inside the `.agent.md` frontmatter rather than in the contribution point. + +```json +{ + "contributes": { + "chatAgents": [ + { + "path": "./agents/planner.agent.md" + } + ] + } +} +``` + +### chatAgents properties + +| Property | Type | Required | Description | +| -------- | ---- | -------- | ----------- | +| `path` | `string` | Yes | Path to the `.agent.md` file relative to the extension root. The path must resolve to a location inside the extension. | +| `when` | `string` | No | A [when clause](/api/references/when-clause-contexts) condition that must be true for this entry to be enabled. | + +See [Custom agents in VS Code](/docs/agent-customization/custom-agents.md) for the required `.agent.md` file format, including the `name`, `description`, `tools`, and `model` frontmatter fields. + ## contributes.chatInstructions Contributes [instructions files](/docs/agent-customization/custom-instructions.md) for Copilot Chat. Instructions files provide custom guidelines that are automatically included in chat requests to steer the behavior of Copilot. Use this contribution point to bundle reusable instructions with your extension, such as coding conventions, framework-specific guidelines, or domain-specific rules. @@ -887,6 +917,107 @@ The main effects of `contributes.languages` are: } ``` +## contributes.languageModelChatProviders + +Contributes a language model chat provider to VS Code, enabling extensions to supply custom language models that users can select in the model picker. Each provider manages its own set of models and handles chat requests on their behalf. + +Register one entry per provider, giving it a unique `vendor` ID. Then use `vscode.lm.registerLanguageModelChatProvider` in your extension activation to wire up the implementation. + +```json +{ + "contributes": { + "languageModelChatProviders": [ + { + "vendor": "my-provider", + "displayName": "My Provider" + } + ] + } +} +``` + +You can add an optional `managementCommand` to let users configure the provider (for example, to enter API keys). The value must be a command declared in `contributes.commands`: + +```json +{ + "contributes": { + "languageModelChatProviders": [ + { + "vendor": "my-provider", + "displayName": "My Provider", + "managementCommand": "my-provider.manage" + } + ], + "commands": [ + { + "command": "my-provider.manage", + "title": "Manage My Provider" + } + ] + } +} +``` + +### languageModelChatProviders properties + +| Property | Type | Required | Description | +| -------- | ---- | -------- | ----------- | +| `vendor` | `string` | Yes | Unique identifier for the provider, used as the first argument to `vscode.lm.registerLanguageModelChatProvider`. | +| `displayName` | `string` | Yes | Human-readable name shown in the model picker UI. | +| `managementCommand` | `string` | No | Command ID that opens a UI for managing this provider (for example, configuring API keys). Must be declared in `contributes.commands`. | + +See the [Language Model Chat Provider API guide](/api/extension-guides/ai/language-model-chat-provider) for full implementation details. + +## contributes.languageModelTools + +Contributes [language model tools](/api/extension-guides/ai/tools) that the language model can invoke automatically as part of an agentic coding workflow. Tools extend agent mode with domain-specific capabilities such as querying databases, calling external APIs, or interacting with the editor. + +Define each tool in the `contributes.languageModelTools` section, then register the implementation with `vscode.lm.registerTool` in your extension activation. + +```json +{ + "contributes": { + "languageModelTools": [ + { + "name": "my-extension_queryDatabase", + "displayName": "Query Database", + "modelDescription": "Executes a read-only SQL query against the project database and returns the results as JSON. Use this tool when the user asks about data stored in the database.", + "canBeReferencedInPrompt": true, + "toolReferenceName": "queryDatabase", + "icon": "$(database)", + "inputSchema": { + "type": "object", + "properties": { + "query": { + "type": "string", + "description": "The SQL SELECT statement to execute." + } + }, + "required": ["query"] + } + } + ] + } +} +``` + +### languageModelTools properties + +| Property | Type | Required | Description | +| -------- | ---- | -------- | ----------- | +| `name` | `string` | Yes | Unique name of the tool used in the extension implementation. Use the `{verb}_{noun}` format and prefix with your extension name to avoid collisions. | +| `displayName` | `string` | No | User-friendly name displayed in the UI. | +| `modelDescription` | `string` | Yes | Description used by the language model to decide when and how to invoke the tool. Be precise: explain what the tool does, what it returns, and when it should or should not be used. | +| `userDescription` | `string` | No | User-facing description displayed in the UI alongside the tool name. | +| `canBeReferencedInPrompt` | `boolean` | No | Set to `true` to allow the tool to be used by agents or referenced via `#` in a chat prompt. When `true`, users can enable or disable the tool in the Chat view. | +| `toolReferenceName` | `string` | No | The name users type after `#` to reference this tool in a chat prompt (for example, `#queryDatabase`). Required when `canBeReferencedInPrompt` is `true`. | +| `icon` | `string` | No | Icon shown in the UI, using the [icon ID](/api/references/icons-in-labels) format (for example, `$(database)`). | +| `inputSchema` | `object` | No | JSON Schema that describes the tool's input parameters. The schema must describe an `object` with typed properties. | +| `when` | `string` | No | A [when clause](/api/references/when-clause-contexts) that controls when the tool is available. For example, restrict a debugging tool with `"debugState == 'running'"`. | +| `tags` | `string[]` | No | Tags used to categorize or group the tool. | + +See the [Language Model Tool API guide](/api/extension-guides/ai/tools) for implementation details, including how to handle confirmations, stream results, and define typed input parameters. + ## contributes.menus Contribute a menu item for a command to the editor or Explorer. The menu item definition contains the command that should be invoked when selected and the condition under which the item should show. The latter is defined with the `when` clause, which uses the key bindings [when clause contexts](/api/references/when-clause-contexts).