Extending Agents Course

learn/agents/1-using-tools-with-agents.md

@@ -0,0 +1,112 @@
+---
+ContentId: 5d7a2a1e-9f1c-4d2a-8c6a-1c2a8f7d4a01
+DateApproved: 05/21/2026
+MetaDescription: Learn how to use built-in tools, MCP tools, extension tools, approvals, and sandboxing with agents in VS Code.
+MetaSocialImage: ../images/shared/agent-first-development-social.png
+Keywords:
+  - copilot
+  - agents
+  - tools
+  - tool sets
+  - approvals
+  - sandboxing
+---
+
+# Using tools with agents
+
+Tools give agents in VS Code access to the workspace, the web, APIs, and other capabilities they need to finish real tasks. This course shows how to choose tools, group them into tool sets, and keep agent work safe with approvals and sandboxing.
+
+## Prerequisites
+
+Before you start: you'll need VS Code Insiders installed and the GitHub Copilot and GitHub Copilot Chat extensions set up and signed in. You also need access to the tools you want to use, such as MCP servers or extensions that contribute tools.
+
+* [Download VS Code](https://code.visualstudio.com/)
+* [Set up GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/overview#_step-1-set-up-copilot)
+
+## What tools do
+
+Agents use tools to search code, read files, run commands, fetch content, and call services. VS Code supports three kinds of tools:
+
+* Built-in tools, such as read, edit, search, execute, and web.
+* MCP tools from installed Model Context Protocol servers.
+* Extension tools contributed by VS Code extensions.
+
+The agent selects tools from the enabled set based on your prompt and context. If you want to force a specific tool, type `#` and the tool name in chat.
+
+For example, use `#codebase` in a prompt when you want the agent to focus on your repository context.
+
+To install more tools, open the Extensions view and search with the `@mcp` filter for MCP servers, or search normally for extensions that contribute tools.
+
+## Choose the right tools
+
+Open the Chat view, switch to **Agent**, and use the **Configure Tools** button in the chat input to choose the tools for the current session.
+
+![Screenshot showing the Chat view with the Configure Tools button in the chat input.](../../docs/copilot/images/chat-tools/agent-mode-select-tools.png)
+
+Select only the tools you need. A smaller tool set gives the model less to sort through and usually leads to better results. Every enabled tool also consumes part of the model's context window.
+
+A chat request can have a maximum of 128 tools enabled at a time, so keeping the active set focused also helps avoid tool count issues.
+
+![Screenshot showing the tool picker drop-down with built-in tools, MCP servers, and user-defined tool sets.](../../docs/copilot/images/chat-tools/chat-tools-picker.png)
+
+> [!TIP]
+> Start with the fewest tools that can complete the task, then add more only when the agent needs them.
+
+## Group related tools with tool sets
+
+Tool sets let you save related tools as a single reusable group. You can use them in chat prompts, prompt files, and custom agents.
+
+Create a tool set from the Command Palette with **Chat: Configure Tool Sets**, or from the cog in the tool picker with **Create a new tool set file**. Then add the tools you want in the generated `.jsonc` file.
+
+Use tool sets when you want a repeatable setup for a task such as Python work, web research, or repository changes. Tool sets you create show up under **User defined tool sets** in the tool picker.
+
+## Limit tools for a custom agent
+
+When you build a [custom agent](https://code.visualstudio.com/docs/copilot/customization/custom-agents), you can list the tools and tool sets it has access to in the `tools` field of the agent's markdown frontmatter:
+
+```yaml
+---
+description: Python testing helper
+tools: ['search', 'edit', 'pylance', 'runTests']
+---
+```
+
+You can also select **Configure Tools** in the agent file to pick tools from a quick pick and have VS Code update the list for you.
+
+## Manage approvals
+
+The permissions picker controls how much autonomy the agent has during a session.
+
+* **Default Approvals** asks before sensitive actions.
+* **Bypass Approvals** auto-approves tool calls.
+* **Autopilot** (Preview) auto-approves tool calls and continues working until the task is done.
+
+You can keep your preferred mode across sessions with `setting(chat.permissions.default)`. Autopilot is available when `setting(chat.autopilot.enabled)` is on.
+
+> [!CAUTION]
+> Higher autonomy levels reduce the amount of review you do before tools run. Use them with care, especially when the agent can edit files or run terminal commands.
+
+![Screenshot of approval options.](../../docs/copilot/chat/images/copilot-chat/chat-approval-options.png)
+
+## Use sandboxing for risky commands
+
+Agent sandboxing adds OS-level isolation for terminal commands run by the agent. It limits file system and network access, and sandboxed commands are auto-approved because they already run in a controlled environment.
+
+Enable it with `setting(chat.agent.sandbox.enabled)`. On macOS and Linux, you can choose full isolation or file system isolation with network access.
+
+Sandboxing is a good fit for tasks that need terminal access but should not reach beyond the workspace or approved domains.
+
+## Why this matters
+
+The right tool mix keeps agents focused. A smaller set reduces noise, while approvals and sandboxing help you keep control when the agent can make changes or reach outside the workspace.
+
+## What's next
+
+Now that you know how to use tools, the next course shows how MCP servers add external data and actions to an agent session.
+
+## Learn more
+
+* [Use tools with agents](https://code.visualstudio.com/docs/copilot/agents/agent-tools)
+* [Tools concepts](https://code.visualstudio.com/docs/copilot/concepts/tools)
+* [Agent sandboxing](https://code.visualstudio.com/docs/copilot/concepts/trust-and-safety#agent-sandboxing)
+* [Agent approvals and permissions](https://code.visualstudio.com/docs/copilot/agents/agent-tools#permission-levels)

learn/agents/2-extending-agents-with-mcp-servers.md

@@ -0,0 +1,114 @@
+---
+ContentId: 7a2e1d9c-4b8f-4a3d-8e0c-2f5d6b7c8a02
+DateApproved: 05/21/2026
+MetaDescription: Learn how MCP servers extend agents in VS Code with tools, resources, prompts, and apps.
+MetaSocialImage: ../images/shared/agent-first-development-social.png
+Keywords:
+  - mcp
+  - model context protocol
+  - agents
+  - tools
+  - api
+  - customization
+---
+
+# Extending agents with MCP servers
+
+MCP servers connect agents to external tools and data sources. In VS Code, they extend an agent with capabilities such as file operations, database access, API calls, resources, and prompts.
+
+This course shows how to install an MCP server, configure it in your workspace or user profile, secure it with sandboxing, and manage it from VS Code.
+
+## Prerequisites
+
+Before you start: you'll need VS Code Insiders installed and the GitHub Copilot and GitHub Copilot Chat extensions set up and signed in. You also need access to an MCP server or the ability to add one from the marketplace.
+
+* [Download VS Code](https://code.visualstudio.com/)
+* [Set up GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/overview#_step-1-set-up-copilot)
+
+## What MCP adds
+
+[Model Context Protocol](https://modelcontextprotocol.io/) is an open standard maintained by the Linux Foundation, and VS Code has full spec support. Think of MCP as the connector between agents and the external tools, data, and prompts they need.
+
+MCP is built around three primitives:
+
+* **Tools**: actions the agent can invoke.
+* **Resources**: context the agent can read.
+* **Prompts**: reusable prompt templates that standardize interactions.
+
+Servers can also expose interactive UI through MCP Apps, which render forms or visualizations inline in chat.
+
+## Install an MCP server
+
+Use the Extensions view and search for `@mcp` to browse the MCP server gallery. From there, you can install a server in your user profile or in your workspace.
+
+When you install a server, VS Code writes the configuration into `mcp.json` and discovers the server's tools for use in chat.
+
+![Screenshot showing the MCP servers in the Extensions view.](../../docs/copilot/images/mcp-servers/extensions-view-mcp-servers.png)
+
+## Configure MCP servers
+
+There are two common configuration scopes:
+
+* **Workspace**: `.vscode/mcp.json`
+* **User profile**: the user-level `mcp.json` file
+
+Use workspace configuration when you want a server tied to a project. Use user profile configuration when you want the server available across workspaces.
+
+You can also add a server through **MCP: Add Server** or open the user configuration with **MCP: Open User Configuration**. For servers that need credentials, store them in inputs in the user `mcp.json` so secrets are not committed to the workspace.
+
+> [!TIP]
+> VS Code provides IntelliSense and inline actions for `mcp.json`, which makes it easier to start, stop, and inspect servers.
+
+![MCP server configuration with lenses to manage server.](../../docs/copilot/images/mcp-servers/mcp-server-config-lenses.png)
+
+## Use an MCP server in chat
+
+Once a server is installed and enabled, open Chat, switch to **Agent**, and select the server's tools in the tools picker.
+
+The agent can then call the server's tools when your prompt needs external context or actions. For example, with the Microsoft Learn MCP server enabled, a prompt like "What are the Microsoft Python best practices?" grounds the answer in official documentation by calling the server's tools.
+
+![Screenshot showing an MCP tool invocation in chat with the input and output shown.](../../docs/copilot/images/mcp-servers/chat-agent-mode-tool-invocation.png)
+
+## Secure MCP servers
+
+Treat local MCP servers as code that can run on your machine. Review the publisher and configuration before you install one.
+
+By default, MCP tool calls prompt for approval before running, which keeps a human in the loop. For local stdio servers on macOS and Linux, you can enable sandboxing to restrict file system and network access. Sandboxed servers are auto-approved because they already run in a controlled environment.
+
+For example, with the Playwright MCP server, enabling sandboxing lets the agent navigate pages and run browser tasks without prompting on every step, because the work is isolated from your host.
+
+If a server needs more access, update the sandbox rules instead of widening access for the whole machine.
+
+![Screenshot showing the MCP server trust prompt.](../../docs/copilot/images/mcp-servers/mcp-server-trust-dialog.png)
+
+## Manage MCP servers
+
+You can manage servers from several places in VS Code:
+
+* The Extensions view.
+* The `mcp.json` editor.
+* The Command Palette, including **MCP: List Servers**.
+* The Agent Customizations view from the cog in the Chat view.
+
+Use these surfaces to start or stop a server, browse the marketplace, and install additional servers.
+
+![Screenshot showing the actions for an MCP server in the Command Palette.](../../docs/copilot/images/mcp-servers/mcp-list-servers-actions.png)
+
+To debug a server, select **Show Output** from the server's actions to see logs from every request the server handles.
+
+![Screenshot showing the MCP server output panel with logs.](../../docs/copilot/images/mcp-servers/mcp-server-error-output.png)
+
+## Why this matters
+
+MCP gives agents a standard way to reach outside the model and work with the systems you already use. That means less ad hoc prompting and more repeatable workflows.
+
+## What's next
+
+Next, you will see how agent plugins package skills, agents, hooks, and MCP servers into a single installable bundle.
+
+## Learn more
+
+* [Add and manage MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
+* [MCP configuration reference](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration)
+* [MCP sandbox configuration](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration#sandbox-configuration)
+* [Use tools with agents](https://code.visualstudio.com/docs/copilot/agents/agent-tools)

learn/agents/3-agent-plugins.md

@@ -0,0 +1,115 @@
+---
+ContentId: 9c8b7a6d-5e4f-4c3b-9a2d-1f0e2d3c4b05
+DateApproved: 05/21/2026
+MetaDescription: Learn how agent plugins bundle commands, skills, agents, hooks, and MCP servers in VS Code.
+MetaSocialImage: ../images/shared/agent-first-development-social.png
+Keywords:
+  - plugins
+  - agents
+  - skills
+  - hooks
+  - mcp
+  - customization
+---
+
+# Agent plugins
+
+Agent plugins bundle multiple customizations into one installable package. Instead of setting up each capability separately, you can install a plugin that brings commands, skills, custom agents, hooks, and MCP servers into VS Code together.
+
+This course shows how to install plugins, browse available collections, use plugin-provided tools, and share recommended plugins with your team.
+
+## Prerequisites
+
+Before you start: you'll need VS Code Insiders installed and the GitHub Copilot and GitHub Copilot Chat extensions set up and signed in. Then enable support for agent plugins in your settings.
+
+* [Download VS Code](https://code.visualstudio.com/)
+* [Set up GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/overview#_step-1-set-up-copilot)
+
+## What plugins provide
+
+A plugin can include any combination of:
+
+* Slash commands
+* Agent skills
+* Custom agents
+* Hooks
+* MCP servers
+
+That makes plugins useful for sharing a team workflow or adopting a prebuilt package of agent behavior.
+
+## Install and manage plugins
+
+Agent plugins are currently in preview. Enable them with `setting(chat.plugins.enabled)` in your user settings before you can install or browse plugins.
+
+By default, VS Code discovers plugins from the [copilot-plugins](https://github.com/github/copilot-plugins) and [awesome-copilot](https://github.com/github/awesome-copilot/) marketplaces. You can add more with `setting(chat.plugins.marketplaces)`.
+
+Open the **Agent Customizations** view from the cog in the Chat view, then select **Plugins** in the left menu to browse available plugins.
+
+From there, you can:
+
+* Browse the marketplace.
+* Install a plugin from source.
+* Create your own plugin.
+* Review which customizations are already installed.
+
+After installation, the plugin's customizations appear alongside your local ones in the **Agent Plugins - Installed** section of the Extensions view.
+
+![Screenshot of browsing agent plugins in the Extensions sidebar.](../../docs/copilot/images/agent-plugins/extensions-view.png)
+
+![Screenshot of the Agent Plugins - Installed view in the Extensions view.](../../docs/copilot/images/agent-plugins/installed-plugins.png)
+
+## Use plugin-provided customizations
+
+Plugins can expose custom agents, skills, and MCP servers all in one place. In chat, you can invoke plugin content with slash commands or by selecting the relevant customization from the picker.
+
+For example, after installing the awesome-copilot plugin, you can run `/awesome-copilot:suggest` to have the plugin look across your project and recommend related collections you can install next.
+
+That makes plugins useful when you want a single install to add a complete workflow, such as a testing package that includes a testing skill, a review agent, and an MCP server for reporting.
+
+![Screenshot of the Agent Customizations editor showing installed plugin content.](../../docs/copilot/images/customization/chat-customizations-editor-plugins.png)
+
+> [!CAUTION]
+> Plugins can run hooks and MCP servers on your machine. Review the contents and publisher before you install one.
+
+## Plugin structure
+
+Plugins are defined by a `plugin.json` manifest and can point to folders for skills, agents, hooks, and MCP server definitions. The plugin format is shared between VS Code, GitHub Copilot CLI, and Claude Code, so a single plugin repository can work across all three tools.
+
+## Share recommended plugins
+
+To share a curated set of plugins with your team, add an `extraKnownMarketplaces` and `enabledPlugins` block to your project's `.github/copilot/settings.json` (or `.claude/settings.json`) file and commit it.
+
+```json
+{
+    "extraKnownMarketplaces": {
+        "company-tools": {
+            "source": {
+                "source": "github",
+                "repo": "your-org/plugin-marketplace"
+            }
+        }
+    },
+    "enabledPlugins": {
+        "code-formatter@company-tools": true
+    }
+}
+```
+
+Use this approach when you want consistent tooling across a team without forcing a plugin into every workspace. VS Code shows a notification the first time a chat message is sent, and team members can also view the recommended plugins from the Extensions view with the `@agentPlugins @recommended` filter.
+
+## Why this matters
+
+Plugins turn a set of related customizations into one package. That makes it easier to share a workflow, install a collection once, and keep teammates aligned on the same agent behavior.
+
+## What's next
+
+The last course in this series shows how to use third-party agents like Claude and Codex without leaving VS Code.
+
+## Learn more
+
+* [Agent plugins in VS Code](https://code.visualstudio.com/docs/copilot/customization/agent-plugins)
+* [Customize AI in Visual Studio Code](https://code.visualstudio.com/docs/copilot/concepts/customization)
+* [Use agent skills in VS Code](https://code.visualstudio.com/docs/copilot/customization/agent-skills)
+* [Use custom agents in VS Code](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
+* [Use hooks in VS Code](https://code.visualstudio.com/docs/copilot/customization/hooks)
+* [Add and manage MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)