microsoft
diff --git a/‎learn/agents/1-using-tools-with-agents.md‎
Lines changed: 184 additions & 0 deletions b/‎learn/agents/1-using-tools-with-agents.md‎
Lines changed: 184 additions & 0 deletions
diff --git a/‎learn/agents/2-extending-agents-with-mcp-servers.md‎
Lines changed: 164 additions & 0 deletions b/‎learn/agents/2-extending-agents-with-mcp-servers.md‎
Lines changed: 164 additions & 0 deletions
@@ -0,0 +1,184 @@
+---
+ContentId: 5d7a2a1e-9f1c-4d2a-8c6a-1c2a8f7d4a01
+DateApproved: 05/21/2026
+MetaDescription: Practice choosing agent tools, tool sets, approvals, and sandboxing settings for focused AI workflows in VS Code.
+MetaSocialImage: ../images/shared/agent-first-development-social.png
+Keywords:
+  - copilot
+  - agents
+  - tools
+  - tool sets
+  - approvals
+  - sandboxing
+---
+
+# Using tools with agents
+
+Tools are how agents act on your request. They search your workspace, read files, edit code, run terminal commands, fetch web content, and call external services. In this guide, you will start with a small task, choose only the tools the task needs, and decide when to use a tool set, approvals, or sandboxing.
+
+## Prerequisites
+
+Before you start, install VS Code, enable AI features, and sign in to GitHub Copilot. You also need access to any extra tools you want to try, 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)
+
+## Start with a task
+
+Imagine you want the agent to explain how authentication works in a repository and then suggest one small test to add. That task needs repository context, but it probably does not need terminal access, web access, or external services at the start.
+
+Use this prompt in an agent session:
+
+```prompt
+Explain the authentication flow in this project. Find the main files involved, then suggest one focused test I should add next.
+```
+
+Before you send it, decide which tools the agent should have. 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 from the enabled tools based on your prompt and context. Your job is to give it enough capability to finish the task without giving it a noisy list of unrelated options.
+
+## Choose tools for the first pass
+
+1. Open the Chat view.
+
+1. Select **Agent** from the agent picker.
+
+1. Select **Configure Tools** in the chat input.
+
+1. Keep repository search and file-reading tools enabled.
+
+1. Leave terminal, web, and external service tools off for this first pass.
+
+1. Send the prompt.
+
+![Screenshot showing the Chat view with the Configure Tools button in the chat input.](../images/agents/agent-mode-select-tools.png)
+
+Starting small helps the agent stay focused. It also reduces tool definitions in the model context window. VS Code can expose some groups as virtual tools to keep tool counts manageable, but a smaller active set still makes the task easier for the model to reason about.
+
+> [!TIP]
+> If the agent says it needs to run tests or inspect generated output, add the terminal tool for the next request instead of restarting with every tool enabled.
+
+## Add a specific tool when needed
+
+Sometimes you know exactly which tool should ground the answer. Type `#` in the chat input to see available tools, context sources, and tool sets.
+
+For example, revise the previous prompt like this:
+
+```prompt
+Explain the authentication flow in this project. Focus on repository context. #codebase
+```
+
+Use explicit tool references when the task has a clear source of truth:
+
+* Use `#codebase` when the answer should come from your repository.
+* Use `#problems` when you want the agent to fix current diagnostics.
+* Use `#web` when the answer needs current external documentation.
+
+![Screenshot showing the tool picker drop-down with built-in tools, MCP servers, and user-defined tool sets.](../images/agents/chat-tools-picker.png)
+
+## Decide between individual tools and tool sets
+
+Individual tools work well for one-off requests. Tool sets work better when you repeat the same setup.
+
+| Use | Good fit | Example |
+| --- | --- | --- |
+| Individual tools | A short task with one clear source of context. | Explain a file with `#codebase` and no terminal access. |
+| Tool set | A repeated workflow that needs the same group of tools. | A Python maintenance workflow with search, edit, testing, and Python language tools. |
+| Custom agent tools | A role that should always run with the same boundaries. | A planning agent with search and web tools, but no edit or terminal tools. |
+
+## Create a tool set for repeat work
+
+In this step, create a reusable tool set for repository cleanup work.
+
+1. Open the Command Palette.
+
+1. Run **Chat: Configure Tool Sets** and select **Create new tool sets file**.
+
+1. In the `.jsonc` file that opens, add the tools you use for the cleanup workflow, such as search, edit, and test tools, plus a `description` and `icon`.
+
+1. Save the file.
+
+1. Return to Chat and select the tool set from **Configure Tools**, or reference it in a prompt by typing `#` followed by the tool set name.
+
+Now try a prompt that uses the saved setup:
+
+```prompt
+Find one small cleanup opportunity in this repository, make the change, and run the focused validation for it.
+```
+
+Tool sets solve the problem of repeatedly rebuilding the same tool selection. They also make reviews easier because the saved file shows which tools are expected for a workflow.
+
+## 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 edit the `tools` field directly, or open the tools picker with the **Configure Tools** button in the Chat view and let VS Code update the agent's list for you.
+
+Use a custom agent when the tool boundary is part of the role. For example, a planning agent should not edit files by accident, so give it search and web tools but leave out edit and terminal tools. An implementation agent needs a broader set because its job is to modify code and validate the change.
+
+## Pick a permission level
+
+Next, decide how much review you want before tools run. 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.
+
+Use the mode that matches the risk of the task:
+
+* Use **Default Approvals** while exploring unfamiliar code or when the agent can run commands you want to review.
+* Use **Bypass Approvals** for routine workflows in a trusted workspace after you know which tools will run.
+* Use **Autopilot** for contained tasks where the agent can keep iterating until it reaches a result you can review.
+
+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.](../images/agents/chat-approval-options.png)
+
+## Add sandboxing for terminal work
+
+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 when the agent needs terminal access but should not reach beyond the workspace or approved domains. For example, use sandboxing before asking the agent to run a generated script, start a local tool, or inspect a project with unfamiliar package scripts.
+
+## Your turn
+
+Try the same repository task three ways:
+
+1. Run it with only repository search and file-reading tools.
+
+1. Add the terminal tool and ask the agent to run one focused validation.
+
+1. Save the tool selection as a tool set and reuse it in a new chat.
+
+After each run, compare what changed. Notice whether the agent stayed focused, asked for missing permissions, or used tools you did not expect.
+
+## Why this matters
+
+The right tool mix keeps agents focused. Tool sets make good workflows repeatable. Custom agents make tool boundaries part of a role. Approvals and sandboxing help you stay in 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)
@@ -0,0 +1,164 @@
+---
+ContentId: 7a2e1d9c-4b8f-4a3d-8e0c-2f5d6b7c8a02
+DateApproved: 05/21/2026
+MetaDescription: Install, use, configure, and sandbox an MCP server to give VS Code agents focused external capabilities.
+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 this guide, you will install an MCP server, use one of its tools in chat, choose the right configuration scope, and decide when to sandbox the server.
+
+## Prerequisites
+
+Before you start, install VS Code, enable AI features, and sign in to GitHub Copilot. 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)
+
+## Start with a concrete server
+
+For this lesson, use the Playwright MCP server as the example. It gives the agent browser tools so it can open pages, interact with them, and capture screenshots.
+
+1. Open the Extensions view.
+
+1. Search for `@mcp playwright`.
+
+1. Select **Install** to install the Playwright MCP server in your user profile.
+
+1. When VS Code asks whether you trust the server, review the publisher and server details, then confirm if you trust it.
+
+When the server starts, VS Code discovers its tools and makes them available in chat.
+
+![Screenshot showing the MCP servers in the Extensions view.](../images/agents/extensions-view-mcp-servers.png)
+
+## Use the server in chat
+
+Now give the agent a task that actually needs browser access.
+
+1. Open the Chat view.
+
+1. Select **Agent**.
+
+1. Select **Configure Tools**.
+
+1. Enable the Playwright tools.
+
+1. Send this prompt:
+
+    ```prompt
+    Go to code.visualstudio.com, decline the cookie banner if it appears, and describe the main navigation items on the homepage.
+    ```
+
+The agent should call the Playwright MCP tools because the task requires browser interaction. If it asks for approval before a tool call, review the action and approve it when it matches the task.
+
+![Screenshot showing an MCP tool invocation in chat with the input and output shown.](../images/agents/chat-agent-mode-tool-invocation.png)
+
+## Decide where the configuration belongs
+
+Installing a server writes configuration to an `mcp.json` file. Choose the scope based on who should use the server.
+
+| Scope | Use it when | Example |
+| --- | --- | --- |
+| User profile | The server is useful across your own workspaces. | A browser automation server or documentation lookup server. |
+| Workspace | The server is part of how the project works. | A project-specific API server or database inspection tool. |
+| Remote user profile | The server must run on a remote machine. | A server that needs access to tools installed in a dev container or remote environment. |
+
+Use **MCP: Open User Configuration** to inspect your user profile configuration. Use **MCP: Open Workspace Folder Configuration** when you want a `.vscode/mcp.json` file for the current project.
+
+For servers that need credentials, do not hardcode secrets in a workspace file. Store sensitive values with input variables or environment files.
+
+> [!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.](../images/agents/mcp-server-config-lenses.png)
+
+## Learn what MCP can provide
+
+MCP is built around a few capabilities. Each one solves a different problem.
+
+* **Tools** let the agent take actions, such as opening a browser or querying an API.
+* **Resources** provide read-only context that you attach to a request, such as a database schema or document.
+* **Prompts** provide reusable templates from the server, such as a standard research prompt.
+* **MCP Apps** render interactive UI in chat when a server supports richer input or output.
+
+Use tools when the agent needs to do something. Use resources when it needs to read something. Use prompts when your team wants a repeatable interaction pattern.
+
+## Sandbox a local server
+
+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.
+
+Add sandboxing when a server needs useful powers but should stay inside clear boundaries. For example, with the Playwright MCP server, sandboxing lets the agent navigate pages and run browser tasks without prompting on every step because the work is isolated from your host.
+
+To enable sandboxing for a local stdio server, set `sandboxEnabled` to `true` in the server configuration. If the server needs more access, update the sandbox rules for that server instead of widening access for the whole machine.
+
+```json
+{
+  "servers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@microsoft/mcp-server-playwright"],
+      "sandboxEnabled": true
+    }
+  }
+}
+```
+
+![Screenshot showing the MCP server trust prompt.](../images/agents/mcp-server-trust-dialog.png)
+
+## Practice with a second server
+
+After you try Playwright, install a documentation or API-focused MCP server and compare the workflow.
+
+1. Search for `@mcp` in the Extensions view.
+
+1. Pick a server that connects to documentation, issue tracking, or another system you use.
+
+1. Install it in your user profile if it is personal tooling, or in the workspace if the project should share it.
+
+1. Enable its tools in Chat.
+
+1. Ask a prompt that requires that external source.
+
+For example, with a documentation MCP server enabled, ask a question that should be grounded in that documentation instead of the model's general knowledge.
+
+## 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.](../images/agents/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.](../images/agents/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)