docs: add tutorials for using early access AI agent features (#17186)

Some content is still being merged, but the structure is still there Preview: https://coder.com/docs/@ai-features/tutorials/ai-agents
coder · evgeniy-scherbina · Apr 4, 2025 · Mar 28, 2025 · Mar 28, 2025 · Mar 28, 2025
commit a61c3e7a1cf7510e863e4953a57506286cce827a
diff --git a/docs/images/guides/ai-agents/duplicate.png b/docs/images/guides/ai-agents/duplicate.png
diff --git a/docs/images/guides/ai-agents/github-action.png b/docs/images/guides/ai-agents/github-action.png
diff --git a/docs/images/guides/ai-agents/github-pr.png b/docs/images/guides/ai-agents/github-pr.png
diff --git a/docs/images/guides/ai-agents/ide-integration.png b/docs/images/guides/ai-agents/ide-integration.png
diff --git a/docs/images/guides/ai-agents/landing.png b/docs/images/guides/ai-agents/landing.png
diff --git a/docs/images/guides/ai-agents/workspace-details.png b/docs/images/guides/ai-agents/workspace-details.png
diff --git a/docs/images/guides/ai-agents/workspaces-list.png b/docs/images/guides/ai-agents/workspaces-list.png
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -705,6 +705,60 @@
 					"description": "Learn how to install and run Coder quickly",
 					"path": "./tutorials/quickstart.md"
 				},
+				{
+					"title": "Run AI Coding Agents with Coder",
+					"description": "Learn how to run and secure agents in Coder",
+					"path": "./tutorials/ai-agents/README.md",
+					"state": ["early access"],
+					"children": [
+						{
+							"title": "Learn about coding agents",
+							"description": "Learn about the different AI agents and their tradeoffs",
+							"path": "./tutorials/ai-agents/agents.md"
+						},
+						{
+							"title": "Create a Coder template for agents",
+							"description": "Create a purpose-built template for your AI agents",
+							"path": "./tutorials/ai-agents/create-template.md",
+							"state": ["early access"]
+						},
+						{
+							"title": "Integrate with your issue tracker",
+							"description": "Assign tickets to AI agents and interact via code reviews",
+							"path": "./tutorials/ai-agents/issue-tracker.md",
+							"state": ["early access"]
+						},
+						{
+							"title": "Best practices \u0026 adding tools via MCP",
+							"description": "Improve results by adding tools to your agents",
+							"path": "./tutorials/ai-agents/best-practices.md",
+							"state": ["early access"]
+						},
+						{
+							"title": "Supervise agents via Coder UI",
+							"description": "Interact with agents via the Coder UI",
+							"path": "./tutorials/ai-agents/coder-dashboard.md",
+							"state": ["early access"]
+						},
+						{
+							"title": "Supervise agents via the IDE",
+							"description": "Interact with agents via VS Code or Cursor",
+							"path": "./tutorials/ai-agents/ide-integration.md",
+							"state": ["early access"]
+						},
+						{
+							"title": "Programmatically manage agents",
+							"description": "Manage agents via MCP, the Coder CLI, and/or REST API",
+							"path": "./tutorials/ai-agents/headless.md",
+							"state": ["early access"]
+						},
+						{
+							"title": "Securing agents in Coder",
+							"description": "Learn how to secure agents with boundaries",
+							"path": "./tutorials/ai-agents/securing.md"
+						}
+					]
+				},
 				{
 					"title": "Write a Template from Scratch",
 					"description": "Learn how to author Coder templates",

diff --git a/docs/tutorials/ai-agents/README.md b/docs/tutorials/ai-agents/README.md
@@ -0,0 +1,36 @@
+# Run AI Agents in Coder (Early Access)
+
+> [!NOTE]
+>
+> This functionality is in early access and subject to change. Do not run in
+> production as it is unstable. Instead, deploy these changes into a demo or
+> staging environment.
+>
+> Join our [Discord channel](https://discord.gg/coder) or
+> [contact us](https://coder.com/contact) to get help or share feedback.
+
+AI Coding Agents such as [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview), [Goose](https://block.github.io/goose/), and [Aider](https://github.com/paul-gauthier/aider) are becoming increasingly popular for:
+
+- Protyping web applications or landing pages
+- Researching / onboarding to a codebase
+- Assisting with lightweight refactors
+- Writing tests and documentation
+- Small, well-defined chores
+
+With Coder, you can self-host AI agents in isolated development environments with proper context and tooling around your existing developer workflows. Whether you are a regulated enterprise or an individual developer, running AI agents at scale with Coder is much more productive and secure than running them locally.
+
+![AI Agents in Coder](../../images/guides//ai-agents/landing.png)
+
+## Prerequisites
+
+Coder is free and open source for developers, with a [premium plan](https://coder.com/pricing) for enterprises. You can self-host a Coder deployment in your own cloud provider.
+
+- A [Coder deployment](../../install/) with v2.21.0 or later
+- A Coder [template](../../admin/templates/) for your project(s).
+- Access to at least one ML model (e.g. Anthropic Claude, Google Gemini, OpenAI)
+  - Cloud Model Providers (AWS Bedrock, GCP Vertex AI, Azure OpenAI) are supported with some agents
+  - Self-hosted models (e.g. llama3) and AI proxies (OpenRouter) are supported with some agents
+
+## Table of Contents
+
+<children></children>
diff --git a/docs/tutorials/ai-agents/agents.md b/docs/tutorials/ai-agents/agents.md
@@ -0,0 +1,55 @@
+# Coding Agents
+
+> [!NOTE]
+>
+> This page is not exhaustive and the landscape is evolving rapidly. Please
+> [open an issue](https://github.com/coder/coder/issues/new) or submit a pull
+> request if you'd like to see your favorite agent added or updated.
+
+There are several types of coding agents emerging:
+
+- **Headless agents** can run without an IDE open and are great for rapid
+  prototyping, background tasks, and chat-based supervision.
+- **In-IDE agents** require developers keep their IDE opens and are great for
+  interactive, focused coding on more complex tasks.
+
+## Headless agents
+
+Headless agents can run without an IDE open, or alongside any IDE. They
+typically run as CLI commands or web apps. With Coder, developers can interact
+with agents via any preferred tool such as via PR comments, within the IDE,
+inside the Coder UI, or even via the REST API or an MCP client such as Claude
+Desktop or Cursor.
+
+| Agent         | Supported Models                                        | Coder Support             | Limitations                                             |
+|---------------|---------------------------------------------------------|---------------------------|---------------------------------------------------------|
+| Claude Code ⭐ | Anthropic Models Only (+ AWS Bedrock and GCP Vertex AI) | First class integration ✅ | Beta (research preview)                                 |
+| Goose         | Most popular AI models + gateways                       | First class integration ✅ | Less effective compared to Claude Code                  |
+| Aider         | Most popular AI models + gateways                       | In progress ⏳             | Can only run 1-2 defined commands (e.g. build and test) |
+| OpenHands     | Most popular AI models + gateways                       | In progress ⏳ ⏳           | Challenging setup, no MCP support                       |
+
+[Claude Code](https://github.com/anthropics/claude-code) is our recommended
+coding agent due to its strong performance on complex programming tasks.
+
+> Note: Any agent can run in a Coder workspace via our
+> [MCP integration](./headless.md).
+
+## In-IDE agents
+
+Coding agents can also run within an IDE, such as VS Code, Cursor or Windsurf.
+These editors and extensions are fully supported in Coder and work well for more
+complex and focused tasks where an IDE is strictly required.
+
+| Agent                       | Supported Models                  | Coder Support                                                |
+|-----------------------------|-----------------------------------|--------------------------------------------------------------|
+| Cursor (Agent Mode)         | Most popular AI models + gateways | ✅ [Cursor Module](https://registry.coder.com/modules/cursor) |
+| Windsurf (Agents and Flows) | Most popular AI models + gateways | ✅ via Remote SSH                                             |
+| Cline                       | Most popular AI models + gateways | ✅ via VS Code Extension                                      |
+
+In-IDE agents do not require a special template as they are not used in a
+headless fashion. However, they can still be run in isolated Coder workspaces
+and report activity to the Coder UI.
+
+## Next Steps
+
+- [Create a Coder template for agents](./create-template.md)
diff --git a/docs/tutorials/ai-agents/best-practices.md b/docs/tutorials/ai-agents/best-practices.md
@@ -0,0 +1,68 @@
+# Best Practices & Adding Tools via MCP
+
+> [!NOTE]
+>
+> This functionality is in early access and subject to change. Do not run in
+> production as it is unstable. Instead, deploy these changes into a demo or
+> staging environment.
+>
+> Join our [Discord channel](https://discord.gg/coder) or
+> [contact us](https://coder.com/contact) to get help or share feedback.
+
+## Overview
+
+Coder templates should be pre-equipped with the tools and dependencies needed
+for development. With AI Agents, this is no exception.
+
+## Prerequisites
+
+- A Coder deployment with v2.21 or later
+- A [template configured for AI agents](./create-template.md)
+
+## Best Practices
+
+- Since agents are still early, it is best to use the most capable ML models you
+  have access to in order to evaluate their performance.
+- Set a system prompt with the `AI_SYSTEM_PROMPT` environment in your template
+- Within your repositories, write a `.cursorrules`, `CLAUDE.md` or similar file
+  to guide the agent's behavior.
+- To read issue descriptions or pull request comments, install the proper CLI
+  (e.g. `gh`) in your image/template.
+- Ensure your [template](./create-template.md) is truly pre-configured for
+  development without manual intervention (e.g. repos are cloned, dependencies
+  are built, secrets are added/mocked, etc.)
+  > Note: [External authentication](../../admin/external-auth.md) can be helpful
+  > to authenticate with third-party services such as GitHub or JFrog.
+- Give your agent the proper tools via MCP to interact with your codebase and
+  related services.
+- Read our recommendations on [securing agents](./securing.md) to avoid
+  surprises.
+
+## Adding Tools via MCP
+
+Model Context Protocol (MCP) is an emerging standard for adding tools to your
+agents.
+
+Follow the documentation for your [agent](./agents.md) to learn how to configure
+MCP servers. See
+[modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)
+to browse open source MCP servers.
+
+### Our Favorite MCP Servers
+
+In internal testing, we have seen significant improvements in agent performance
+when these tools are added via MCP.
+
+- [Playwright](https://github.com/microsoft/playwright-mcp): Instruct your agent
+  to open a browser, and check its work by viewing output and taking
+  screenshots.
+- [desktop-commander](https://github.com/wonderwhy-er/DesktopCommanderMCP):
+  Instruct your agent to run long-running tasks (e.g. `npm run dev`) in the
+  background instead of blocking the main thread.
+
+## Next Steps
+
+- [Supervise Agents in the UI](./coder-dashboard.md)
+- [Supervise Agents in the IDE](./ide-integration.md)
+- [Supervise Agents Programmatically](./headless.md)
+- [Securing Agents](./securing.md)
diff --git a/docs/tutorials/ai-agents/coder-dashboard.md b/docs/tutorials/ai-agents/coder-dashboard.md
@@ -0,0 +1,28 @@
+> [!NOTE]
+>
+> This functionality is in early access and subject to change. Do not run in
+> production as it is unstable. Instead, deploy these changes into a demo or
+> staging environment.
+>
+> Join our [Discord channel](https://discord.gg/coder) or
+> [contact us](https://coder.com/contact) to get help or share feedback.
+
+## Prerequisites
+
+- A Coder deployment with v2.21 or later
+- A [template configured for AI agents](./create-template.md)
+
+## Overview
+
+Once you have an agent running and reporting activity to Coder, you can view
+status and switch between workspaces from the Coder dashboard.
+
+![Coder Dashboard](../../images/guides/ai-agents/workspaces-list.png)
+
+![Workspace Details](../../images/guides/ai-agents/workspace-details.png)
+
+## Next Steps
+
+- [Supervise Agents in the IDE](./ide-integration.md)
+- [Supervise Agents Programmatically](./headless.md)
+- [Securing Agents](./securing.md)
diff --git a/docs/tutorials/ai-agents/create-template.md b/docs/tutorials/ai-agents/create-template.md
@@ -0,0 +1,57 @@
+# Create a Coder template for agents
+
+> [!NOTE]
+>
+> This functionality is in early access and subject to change. Do not run in
+> production as it is unstable. Instead, deploy these changes into a demo or
+> staging environment.
+>
+> Join our [Discord channel](https://discord.gg/coder) or
+> [contact us](https://coder.com/contact) to get help or share feedback.
+
+## Overview
+
+This tutorial will guide you through the process of creating a Coder template
+for agents.
+
+## Prerequisites
+
+- A Coder deployment with v2.21 or later
+- A template that is pre-configured for your projects
+- You have selected an [agent](./agents.md) based on your needs
+
+## 1. Duplicate an existing template
+
+It is best to create a separate template for AI agents based on an existing
+template that has all of the tools and dependencies installed.
+
+This can be done in the Coder UI:
+
+![Duplicate template](../../images/guides/ai-agents/duplicate.png)
+
+## 2. Add a module for supported agents
+
+We currently publish a module for Claude Code and Goose. Additional modules are
+[coming soon](./agents.md).
+
+- [Add the Claude Code module](https://registry.coder.com/modules/claude-code)
+- [Add the Goose module](https://registry.coder.com/modules/goose)
+
+Follow the instructions in the Coder Registry to install the module. Be sure to
+enable the `experiment_use_screen` and `experiment_report_tasks` variables to
+report status back to the Coder control plane.
+
+> Alternatively, you can report status from a custom agent back to the Coder
+> control plane via our MCP server. For more information,
+> [join our Discord](https://discord.gg/coder) or
+> [contact us](https://coder.com/contact).
+
+## 3. Confirm tasks are streaming in the Coder UI
+
+The Coder dashboard should now show tasks being reported by the agent.
+
+![AI Agents in Coder](../../images/guides//ai-agents/landing.png)
+
+## Next Steps
+
+- [Integrate with your issue tracker](./issue-tracker.md)
diff --git a/docs/tutorials/ai-agents/headless.md b/docs/tutorials/ai-agents/headless.md
@@ -0,0 +1,54 @@
+> [!NOTE]
+>
+> This functionality is in early access and subject to change. Do not run in
+> production as it is unstable. Instead, deploy these changes into a demo or
+> staging environment.
+>
+> Join our [Discord channel](https://discord.gg/coder) or
+> [contact us](https://coder.com/contact) to get help or share feedback.
+
+## Prerequisites
+
+- A Coder deployment with v2.21 or later
+- A [template configured for AI agents](./create-template.md)
+
+## Overview
+
+Once you have an agent running and reporting activity to Coder, you can manage
+it programmatically via the MCP server, Coder CLI, and/or REST API.
+
+## MCP Server
+
+Power users can configure [Claude Desktop](https://claude.ai/download), Cursor,
+or other tools with MCP support to interact with Coder in order to:
+
+- List workspaces
+- Create/start/stop workspaces
+- Run commands on workspaces
+- Check in on agent activity
+
+In this model, an [IDE Agent](./agents.md#in-ide-agents) could interact with a
+remote Coder workspace, or Coder can be used in a remote pipeline or a larger
+workflow.
+
+The Coder CLI has options to automatically configure MCP servers for you. On
+your local machine, run the following command:
+
+```sh
+coder mcp claude-desktop # Configure Claude Desktop to interact with Coder
+coder mcp cursor # Configure Cursor to interact with Coder
+```
+
+## Coder CLI
+
+Workspaces can be created, started, and stopped via the Coder CLI. See the
+[CLI docs](../../reference/cli/) for more information.
+
+## REST API
+
+The Coder REST API can be used to manage workspaces and agents. See the
+[API docs](../../reference/api/) for more information.
+
+## Next Steps
+
+- [Securing Agents](./securing.md)
diff --git a/docs/tutorials/ai-agents/ide-integration.md b/docs/tutorials/ai-agents/ide-integration.md
@@ -0,0 +1,29 @@
+> [!NOTE]
+>
+> This functionality is in early access and subject to change. Do not run in
+> production as it is unstable. Instead, deploy these changes into a demo or
+> staging environment.
+>
+> Join our [Discord channel](https://discord.gg/coder) or
+> [contact us](https://coder.com/contact) to get help or share feedback.
+
+## Prerequisites
+
+- A Coder deployment with v2.21 or later
+- A [template configured for AI agents](./create-template.md)
+- VS Code, Windsurf, or Cursor IDE with the
+  [Coder Extension](https://github.com/coder/vscode-coder/releases) v1.6.0+ or
+  the [experimental AI VSIX](https://github.com/coder/vscode-coder/releases/)
+
+## Overview
+
+Once you have an agent running and reporting activity to Coder, you can view the
+status and switch between workspaces from the IDE. This can be very helpful for
+reviewing code, working along with the agent, and more.
+
+![IDE Integration](../../images/guides/ai-agents/ide-integration.png)
+
+## Next Steps
+
+- [Programmatically manage agents](./headless.md)
+- [Securing Agents with Boundaries](./securing.md)