synced/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2025-07-12 00:14:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Some content is still being merged, but the structure is still there

Preview: https://coder.com/docs/@ai-features/tutorials/ai-agents
This commit is contained in:
Ben Potter
2025-04-01 19:57:05 -05:00
committed by GitHub
parent 4604f191e9
commit a61c3e7a1c
20 changed files with 498 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/tutorials/ai-agents/README.md Normal file
View File

@ -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>

55
docs/tutorials/ai-agents/agents.md Normal file
View File

@ -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)

68
docs/tutorials/ai-agents/best-practices.md Normal file
View File

@ -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)

28
docs/tutorials/ai-agents/coder-dashboard.md Normal file
View File

@ -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)

57
docs/tutorials/ai-agents/create-template.md Normal file
View File

@ -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)

54
docs/tutorials/ai-agents/headless.md Normal file
View File

@ -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)

29
docs/tutorials/ai-agents/ide-integration.md Normal file
View File

@ -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)

60
docs/tutorials/ai-agents/issue-tracker.md Normal file
View File

@ -0,0 +1,60 @@
# 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
Coder has first-class support for managing agents through Github, but can also
integrate with other issue trackers. Use our action to interact with agents
directly in issues and PRs.
## Prerequisites
- A Coder deployment with v2.21 or later
- A [template configured for AI agents](./create-template.md)
## GitHub
### GitHub Action
The [start-workspace](https://github.com/coder/start-workspace-action) GitHub
action will create a Coder workspace based on a specific phrase in a comment
(e.g. `@coder`).
![GitHub Issue](../../images/guides/ai-agents/github-action.png)
When properly configured with an [AI template](./create-template.md), the agent
will begin working on the issue.
### Pull Request Support (Coming Soon)
We're working on adding support for an agent automatically creating pull
requests and responding to your comments. Check back soon or
[join our Discord](https://discord.gg/coder) to stay updated.
![GitHub Pull Request](../../images/guides/ai-agents/github-pr.png)
## Integrating with Other Issue Trackers
While support for other issue trackers is under consideration, you can can use
the [REST API](../../reference/api/) or [CLI](../../reference/cli/) to integrate
with other issue trackers or CI pipelines.
In addition, an [Open in Coder](../../admin/templates/open-in-coder.md) flow can
be used to generate a URL and/or markdown button in your issue tracker to
automatically create a workspace with specific parameters.
## Next Steps
- [Best practices & adding tools via MCP](./best-practices.md)
- [Supervise Agents in the UI](./coder-dashboard.md)
- [Supervise Agents in the IDE](./ide-integration.md)
- [Supervise Agents Programmatically](./headless.md)
- [Securing Agents with Boundaries](./securing.md)

47
docs/tutorials/ai-agents/securing.md Normal file
View File

@ -0,0 +1,47 @@
> [!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.
As the AI landscape is evolving, we are working to ensure Coder remains a secure
platform for running AI agents just as it is for other cloud development
environments.
## Use Trusted Models
Most [agents](./agents.md) can be configured to either use a local LLM (e.g.
llama3), an agent proxy (e.g. OpenRouter), or a Cloud-Provided LLM (e.g. AWS
Bedrock). Research which models you are comfortable with and configure your
[Coder templates](./create-template.md) to use those.
## Set up Firewalls and Proxies
Many enterprises run Coder workspaces behind a firewall or a proxy to prevent
threats or bad actors. These same protections can be used to ensure AI agents do
not access or upload sensitive information.
## Separate API keys and scopes for agents
Many agents require API keys to access external services. It is recommended to
create a separate API key for your agent with the minimum permissions required.
This will likely involve editing your
[template for Agents](./create-template.md) to set different scopes or tokens
from the standard one.
Additional guidance and tooling is coming in future releases of Coder.
## Set Up Agent Boundaries (Premium)
Agent Boundaries add an additional layer and isolation of security between the
agent and the rest of the environment inside of your Coder workspace, allowing
humans to have more privileges and access compared to agents inside the same
workspace.
Trial agent boundaries in your workspaces by following the instructions in the
[boundary-releases](https://github.com/coder/boundary-releases) repository.
- [Contact us for more information](https://coder.com/contact)