diff --git a/api/extension-guides/chat.md b/api/extension-guides/chat.md index 007f498fa3..5e5d82cd7e 100644 --- a/api/extension-guides/chat.md +++ b/api/extension-guides/chat.md @@ -72,7 +72,7 @@ As a starting point for developing a chat extension, you can refer to our [chat ### Register the chat extension -The first step to create a chat extension is to register it in your `package.json` by providing a unique `id`, the `name`, and `description`: +The first step to create a chat extension is to register it in your `package.json` by providing a unique `id`, the `name`, and `description`. ```json "contributes": { @@ -88,10 +88,14 @@ The first step to create a chat extension is to register it in your `package.jso } ``` -We suggest using a lowercase `name` to align with existing chat participants. `name` can not contain spaces. Users can then reference the chat participant in the Chat view by using the `@` symbol and the `name` you provided. We suggest using title case for the `fullName`, which is shown in the title area of a response from your participant. Some participant names are reserved, and in case you use a reserved name VS Code will display the fully qualified name of your participant (including the extension ID). The `description` is shown in the chat input field as a placeholder text. +Users can then reference the chat participant in the Chat view by using the `@` symbol and the `name` you provided. The `fullName` is shown in the title area of a response from your participant. The `description` is used as placeholder text in the chat input field. The `isSticky` property controls whether the chat participant is persistent, which means that the participant name is automatically prepended in the chat input field after the user has started interacting with the participant. +We suggest using a lowercase `name` and using title case for the `fullName` to align with existing chat participants. Get more info about the [naming conventions for chat participants](#chat-participant-naming-conventions). + +> **Note**: Some participant names are reserved, and in case you use a reserved name VS Code will display the fully qualified name of your participant (including the extension ID). + Up-front registration of participants and [commands](#register-commands) in `package.json` is required, so that VS Code can activate your extension at the right time, and not before it is needed. After registration, all your extension has to do is create the participant by using `vscode.chat.createChatParticipant`. When creating the participant, you have to provide the ID, which you defined in `package.json`, and a [request handler](#implement-a-request-handler). @@ -242,6 +246,8 @@ Chat participants can contribute commands with their description by adding them } ``` +Get more info about the [naming conventions for slash commands](#slash-command-naming-conventions). + ### Register follow-up requests After each chat request, VS Code invokes follow-up providers to get suggested follow-up questions to show to the user. The user can then select the follow-up question, and immediately send it to the chat extension. Follow-up questions can provide inspiration to the user to take the conversation further, or to discover more capabilities of the chat extension. @@ -465,6 +471,26 @@ cat.onDidReceiveFeedback((feedback: vscode.ChatResultFeedback) => { Any other user interaction with your chat response should be measured as a positive metric (for example, the user selecting a button that was generated in a chat response). Measuring success with telemetry is crucial when working with AI, since it is a nondeterministic technology. Run experiments, measure and iteratively improve your participant to ensure a good user experience. +## Naming restrictions and conventions + +### Chat participant naming conventions + +| Property | Description | Naming guidelines | +|----------|-------------|-------------------| +| `id` | Globally unique identifier for the chat participant | | +| `name` | Name of the chat participant, referenced by users through the `@` symbol | | +| `fullName` | (Optional) The full name of the participant, which is shown as the label for responses coming from the participant | | +| `description` | (Optional) Short description of what the chat participant does, shown as placeholder text in the chat input field or in the list of participants | | + +When referring to your chat participant in any of the user-facing elements, such as properties, chat responses, or chat user interface, it's recommended to not use the term *participant*, as it's the name of the API. For example, the `@cat` extension could be called "Cat extension for GitHub Copilot". + +### Slash command naming conventions + +| Property | Description | Naming guidelines | +|----------|-------------|-------------------| +| `name` | Name of the slash command, referenced by users through the `/` symbol | | +| `description` | (Optional) Short description of what the slash command does, shown as placeholder text in the chat input field or in the list of participants and commands | | + ## Guidelines Chat participants should not be purely question-answering bots. When building a chat participant, be creative and use the existing VS Code API to create rich integrations in VS Code. Users also love rich and convenient interactions, such as buttons in your responses, menu items that bring users to your participant in chat. Think about real life scenarios where AI can help your users.