Skip to content

docs: edit the ai agents doc #17521

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 23, 2025
Merged

docs: edit the ai agents doc #17521

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7f2b5e6
edit agents
EdwardAngert Apr 23, 2025
1d7f9cf
make lint/fmt
EdwardAngert Apr 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 71 additions & 32 deletions docs/ai-coder/agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Coding Agents
# AI Coding Agents

> [!NOTE]
>
Expand All @@ -7,50 +7,89 @@
> 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:
Coding agents are rapidly emerging to help developers tackle repetitive tasks,
explore codebases, and generate solutions with increasing effectiveness.

- **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.
You can run these agents in Coder workspaces to leverage the power of cloud resources
and deep integration with your existing development workflows.

## Headless agents
## Why Run AI Coding Agents in Coder?

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.
Coder provides unique advantages for running AI coding agents:

| 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 |
- **Consistent environments**: Agents work in the same standardized environments as your developers.
- **Resource optimization**: Leverage powerful cloud resources without taxing local machines.
- **Security and isolation**: Keep sensitive code, API keys, and secrets in controlled environments.
- **Seamless collaboration**: Multiple developers can observe and interact with agent activity.
- **Deep integration**: Status reporting and task management directly in the Coder UI.
- **Scalability**: Run multiple agents across multiple projects simultaneously.
- **Persistent sessions**: Agents can continue working even when developers disconnect.

## Types of Coding Agents

AI coding agents generally fall into two categories, both fully supported in Coder:

### Headless Agents

Headless agents can run without an IDE open, making them ideal for:

- **Background automation**: Execute repetitive tasks without supervision.
- **Resource-efficient development**: Work on projects without keeping an IDE running.
- **CI/CD integration**: Generate code, tests, or documentation as part of automated workflows.
- **Multi-project management**: Monitor and contribute to multiple repositories simultaneously.

Additionally, with Coder, headless agents benefit from:

- Status reporting directly to the Coder dashboard.
- Workspace lifecycle management (auto-stop).
- Resource monitoring and limits to prevent runaway processes.
- API-driven management for enterprise automation.

| Agent | Supported models | Coder integration | Notes |
|---------------|---------------------------------------------------------|---------------------------|-----------------------------------------------------------------------------------------------|
| Claude Code ⭐ | Anthropic Models Only (+ AWS Bedrock and GCP Vertex AI) | First class integration ✅ | Enhanced security through workspace isolation, resource optimization, task status in Coder UI |
| Goose | Most popular AI models + gateways | First class integration ✅ | Simplified setup with Terraform module, environment consistency |
| Aider | Most popular AI models + gateways | In progress ⏳ | Coming soon with workspace resource optimization |
| OpenHands | Most popular AI models + gateways | In progress ⏳ ⏳ | Coming soon |

[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).
> [!INFO]
> Any agent can run in a Coder workspace via our [MCP integration](./headless.md),
> even if we don't have a specific module for it yet.

### In-IDE agents

In-IDE agents run within development environments like VS Code, Cursor, or Windsurf.

These are ideal for exploring new codebases, complex problem solving, pair programming,
or rubber-ducking.

| Agent | Supported Models | Coder integration | Coder key advantages |
|-----------------------------|-----------------------------------|--------------------------------------------------------------|----------------------------------------------------------------|
| Cursor (Agent Mode) | Most popular AI models + gateways | ✅ [Cursor Module](https://registry.coder.com/modules/cursor) | Pre-configured environment, containerized dependencies |
| Windsurf (Agents and Flows) | Most popular AI models + gateways | ✅ via Remote SSH | Consistent setup across team, powerful cloud compute |
| Cline | Most popular AI models + gateways | ✅ via VS Code Extension | Enterprise-friendly API key management, consistent environment |

## Agent status reports in the Coder dashboard

Claude Code and Goose can report their status directly to the Coder dashboard:

## In-IDE agents
- Task progress appears in the workspace overview.
- Completion status is visible without opening the terminal.
- Error states are highlighted.

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.
## Get started

| 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 |
Ready to deploy AI coding agents in your Coder deployment?

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.
1. [Create a Coder template for agents](./create-template.md).
1. Configure your chosen agent with appropriate API keys and permissions.
1. Start monitoring agent activity in the Coder dashboard.

## Next Steps

- [Create a Coder template for agents](./create-template.md)
- [Integrate with your issue tracker](./issue-tracker.md)
- [Learn about MCP and adding AI tools](./best-practices.md)
Loading