Skip to content

Commit 4cae216

Browse files
ntroghntrogh
authored
Update AI extensibility guidance (#8531)
* Move AI extension guides under AI subsection * Update implementation options * Update ToC * Update decision options and next steps * Edit pass and remove draft * Update why extend AI * Refresh Tools extension guide * Update MCP api guide * Update chat extension guide * Update language model guide * Update after PM review * Move MCP developer guide to API docs * Add redirect page from main docs * Update API ToC
1 parent a30696b commit 4cae216

40 files changed

+787
-669
lines changed

‎api/extension-guides/ai/ai-extensibility-overview.md

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
ContentId: e375ec2a-43d3-4670-96e5-fd25a6aed272
3+
DateApproved: 06/12/2025
4+
MetaDescription: Overview of how to extend the AI features in your Visual Studio Code extension by using the Language Model, Tools, and Chat APIs.
5+
---
6+
# AI extensibility in VS Code
7+
8+
This article provides an overview of AI extensibility options in Visual Studio Code, helping you choose the right approach for your extension.
9+
10+
VS Code includes powerful AI features that enhance the coding experience:
11+
12+
- **Code completion**: Offers inline code suggestions as you type
13+
- **Agent mode**: Enables AI to autonomously plan and execute development tasks with specialized tools
14+
- **Chat**: Lets developers use natural language to ask questions or make edits in codebase through chat interfaces
15+
- **Smart actions**: Use AI-enhanced actions for common development tasks, integrated throughout the editor
16+
17+
You can extend and customize each of these built-in capabilities to create tailored AI experiences that meet the specific needs of your users.
18+
19+
## Why extend AI in VS Code?
20+
21+
Adding AI capabilities to your extension brings several benefits to your users:
22+
23+
- **Domain-specific knowledge in agent mode**: Let agent mode access your company's data sources and services
24+
- **Enhanced user experience**: Provide intelligent assistance tailored to your extension's domain
25+
- **Domain specialization**: Create AI features specific to a programming language, framework, or domain
26+
- **Extend chat capabilities**: Add specialized tools or assistants to the chat interface for more powerful interactions
27+
- **Improved developer productivity**: Enhance common developer tasks, like debugging, code reviewing or testing, with AI capabilities
28+
29+
## Extend the chat experience
30+
31+
### Language model tool
32+
33+
Language model tools enable you to extend agent mode in VS Code with domain-specific capabilities. In agent mode, these tools are automatically invoked based on the user's chat prompt to perform specialized tasks or retrieve information from a data source or service. Users can also reference these tools explicitly in their chat prompt by #-mentioning the tool.
34+
35+
To implement a language model tool, use the [Language Model Tools API](/api/extension-guides/ai/tools) within your VS Code extension. A language model tool can access all VS Code extension APIs and provide deep integration with the editor.
36+
37+
**Key benefits**:
38+
39+
- Domain-specific capabilities as part of an autonomous coding workflow
40+
- Your tool implementation can use VS Code APIs since it runs in the extension host process
41+
- Easy distribution and deployment via the Visual Studio Marketplace
42+
43+
**Key considerations**:
44+
45+
- Remote deployment requires the extension to implement the client-server communication
46+
- Reuse across different tools requires modular design and implementation
47+
48+
### MCP tool
49+
50+
Model Context Protocol (MCP) tools provide a way to integrate external services with language models by using a standardized protocol. In agent mode, these tools are automatically invoked based on the user's chat prompt to perform specialized tasks or retrieve information from external data sources.
51+
52+
MCP tools run outside of VS Code, either locally on the user's machine or as a remote service. Users can add MCP tools through JSON configuration or VS Code extension can configure them programmatically. You can implement MCP tools through various language SDKs and deployment options.
53+
54+
As MCP tools run outside of VS Code, they do not have access to the VS Code extension APIs.
55+
56+
**Key benefits**:
57+
58+
- Add domain-specific capabilities as part of an autonomous coding workflow
59+
- Local and remote deployment options
60+
- Reuse MCP servers in other MCP clients
61+
62+
**Key considerations**:
63+
64+
- No access to VS Code extension APIs
65+
- Distribution and deployment require users to set up the MCP server
66+
67+
### Chat participant
68+
69+
Chat participants are specialized assistants that enable users to extend ask mode with domain-specific experts. In chat, users can invoke a chat participant by @-mentioning it and passing in a natural language prompt about a particular topic or domain. The chat participant is responsible for handling the entire chat interaction.
70+
71+
To implement a chat participant, use the [Chat API](/api/extension-guides/ai/chat) within your VS Code extension. A chat participant can access all VS Code extension APIs and provide deep integration with the editor.
72+
73+
**Key benefits**:
74+
75+
- Control the end-to-end interaction flow
76+
- Running in the extension host process allows access to VS Code extension APIs
77+
- Easy distribution and deployment via the Visual Studio Marketplace
78+
79+
**Key considerations**:
80+
81+
- Remote deployment requires the extension to implement the client-server communication
82+
- Reuse across different tools requires modular design and implementation
83+
84+
## Build your own AI-powered features
85+
86+
VS Code gives you direct programmatic access to AI models for creating custom AI-powered features in your extensions. This approach enables you to build editor-specific interactions that use AI capabilities without relying on the chat interface.
87+
88+
To use language models directly, use the [Language Model API](/api/extension-guides/ai/language-model) within your VS Code extension. You can incorporate these AI capabilities into any extension feature, such as code actions, hover providers, custom views, and more.
89+
90+
**Key benefits**:
91+
92+
- Integrate AI capabilities into existing extension features or build new ones
93+
- Running in the extension host process allows access to VS Code extension APIs
94+
- Easy distribution and deployment via the Visual Studio Marketplace
95+
96+
**Key considerations**:
97+
98+
- Reuse across different experiences requires modular design and implementation
99+
100+
## Decide which option to use
101+
102+
When choosing the right approach for extending AI in your VS Code extension, consider the following guidelines:
103+
104+
1. **Choose Language Model Tool when**:
105+
- You want to extend chat in VS Code with specialized capabilities
106+
- You want automatic invocation based on user intent in agent mode
107+
- You want access to VS Code APIs for deep integration in VS Code
108+
- You want to distribute your tool through the VS Code Marketplace
109+
110+
1. **Choose MCP Tool when**:
111+
- You want to extend chat in VS Code with specialized capabilities
112+
- You want automatic invocation based on user intent in agent mode
113+
- You don't need to integrate with VS Code APIs
114+
- Your tool needs to work across different environments (not just VS Code)
115+
- Your tool should run remotely or locally
116+
117+
1. **Choose Chat Participant when**:
118+
- You want to extend ask mode with a specialized assistant with domain expertise
119+
- You need to customize the entire interaction flow and response behavior
120+
- You want access to VS Code APIs for deep integration in VS Code
121+
- You want to distribute your tool through the VS Code Marketplace
122+
123+
1. **Choose Language Model API when**:
124+
- You want to integrate AI capabilities into existing extension features
125+
- You're building UI experiences outside the chat interface
126+
- You need direct programmatic control over AI model requests
127+
128+
## Next steps
129+
130+
Choose the approach that best fits your extension's goals:
131+
132+
- [Implement a language model tool](/api/extension-guides/ai/tools)
133+
- [Register MCP tools in your VS Code extension](/api/extension-guides/ai/mcp)
134+
- [Integrate AI in your extension with the Language Model API](/api/extension-guides/ai/language-model)
135+
- [Implement a chat participant](/api/extension-guides/ai/chat)
136+
- [Extend code completions with the Inline Completions API](/api/references/vscode-api#InlineCompletionItemProvider)
137+
138+
### Sample projects
139+
140+
- [Chat sample](https://github.com/microsoft/vscode-extension-samples/tree/main/chat-sample): Extension with agent mode tool and chat participant
141+
- [Code tutor chat participant tutorial](/api/extension-guides/ai/chat-tutorial): Building a specialized chat assistant
142+
- [AI-powered code annotations tutorial](/api/extension-guides/ai/language-model-tutorial): Step-by-step guide for using the Language Model API
143+
- [MCP extension sample](https://github.com/microsoft/vscode-extension-samples/blob/main/mcp-extension-sample): Extension that registers an MCP tool

‎api/extension-guides/chat-tutorial.md renamed to ‎api/extension-guides/ai/chat-tutorial.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -188,15 +188,15 @@ Press `kbstyle(F5)` to run the code. A new window of VS Code will open with your
188188

189189
In the Copilot Chat pane, you can now invoke your participant by typing `@tutor`!
190190

191-
![Participant in Chat pane](images/chat-tutorial/participant.png)
191+
![Participant in Chat pane](../images/ai/chat-tutorial/participant.png)
192192

193193
Test it out by typing what you want to learn about. You should see a response giving you an overview of the concept!
194194

195195
If you type a related message to continue the conversation, you'll notice that the participant doesn't give a follow-up response based on your conversation. That's because our current participant is only sending in the user's current message, and not the participant message history.
196196

197197
In the screenshot below, the tutor correctly responds with a starting explanation of stacks. However, in the follow-up, it does not understand that the user is continuing the conversation to see an implementation of stacks in Python, so it instead gives a generic response about Python.
198198

199-
![Participant with no message history](images/chat-tutorial/participant-no-message-history.png)
199+
![Participant with no message history](../images/ai/chat-tutorial/participant-no-message-history.png)
200200

201201
## Step 7: Add message history for more context
202202

@@ -248,7 +248,7 @@ const handler: vscode.ChatRequestHandler = async (request: vscode.ChatRequest, c
248248

249249
Now when you run the code, you can have a conversation with your participant with all the context of the previous messages! In the screenshot below, the participant correctly understands that the user is requesting to see an implementation of stacks in Python.
250250

251-
![Participant with message history](images/chat-tutorial/participant-message-history.png)
251+
![Participant with message history](../images/ai/chat-tutorial/participant-message-history.png)
252252

253253
## Step 8: Add a command
254254

@@ -338,16 +338,16 @@ And that's all that needs to be added! The rest of the logic to get the message
338338

339339
Now you can type `/exercise`, which will bring up your chat participant, and you can get interactive exercises to practice coding!
340340

341-
![Participant with a slash command](images/chat-tutorial/exercise-command.png)
341+
![Participant with a slash command](../images/ai/chat-tutorial/exercise-command.png)
342342

343343
## Next steps
344344

345-
Congratulations! You have successfully created a chat participant that can provide explanations and sample exercises for programming concepts. You can further extend your participant by fine-tuning the prompts, adding more slash commands, or leveraging other APIs like the [Language Model API](/api/extension-guides/language-model). Once ready, you can also publish your extension to the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/vscode).
345+
Congratulations! You have successfully created a chat participant that can provide explanations and sample exercises for programming concepts. You can further extend your participant by fine-tuning the prompts, adding more slash commands, or leveraging other APIs like the [Language Model API](/api/extension-guides/ai/language-model). Once ready, you can also publish your extension to the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/vscode).
346346

347347
You can find the complete source code for this tutorial in the [vscode-extensions-sample repository](https://github.com/microsoft/vscode-extension-samples/tree/main/chat-tutorial).
348348

349349
## Related content
350350

351-
- [Chat API extension guide](/api/extension-guides/chat)
352-
- [Tutorial: Generate AI-powered code annotations by using the Language Model API](/api/extension-guides/language-model-tutorial)
353-
- [Language Model API extension guide](/api/extension-guides/language-model)
351+
- [Chat API extension guide](/api/extension-guides/ai/chat)
352+
- [Tutorial: Generate AI-powered code annotations by using the Language Model API](/api/extension-guides/ai/language-model-tutorial)
353+
- [Language Model API extension guide](/api/extension-guides/ai/language-model)

0 commit comments

Comments
 (0)