diff --git a/docs/ai-coder/agents.md b/docs/ai-coder/agents.md deleted file mode 100644 index 63c08751726ca..0000000000000 --- a/docs/ai-coder/agents.md +++ /dev/null @@ -1,95 +0,0 @@ -# AI 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. - -Coding agents are rapidly emerging to help developers tackle repetitive tasks, -explore codebases, and generate solutions with increasing effectiveness. - -You can run these agents in Coder workspaces to leverage the power of cloud resources -and deep integration with your existing development workflows. - -## Why Run AI Coding Agents in Coder? - -Coder provides unique advantages for running AI coding agents: - -- **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](https://registry.coder.com/modules/coder/claude-code) ✅ | Enhanced security through workspace isolation, resource optimization, task status in Coder UI | -| Goose | Most popular AI models + gateways | [First class integration](https://registry.coder.com/modules/coder/goose) ✅ | Simplified setup with Terraform module, environment consistency | -| Aider | Most popular AI models + gateways | [First class integration](https://registry.coder.com/modules/coder/aider) ✅ | Simplified setup with Terraform module, environment consistency | -| 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. - -> [!TIP] -> 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/coder/cursor) | Pre-configured environment, containerized dependencies | -| Windsurf (Agents and Flows) | Most popular AI models + gateways | ✅ [Windsurf Module](https://registry.coder.com/modules/coder/windsurf) | 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: - -- Task progress appears in the workspace overview. -- Completion status is visible without opening the terminal. -- Error states are highlighted. - -## Get started - -Ready to deploy AI coding agents in your Coder deployment? - -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) diff --git a/docs/ai-coder/best-practices.md b/docs/ai-coder/best-practices.md index 124cc7c221ee8..b96c76a808fea 100644 --- a/docs/ai-coder/best-practices.md +++ b/docs/ai-coder/best-practices.md @@ -1,71 +1,53 @@ -# Model Context Protocols (MCP) and adding AI tools +# Best Practices -> [!NOTE] -> -> This functionality is in beta and is evolving rapidly. -> -> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment. -> Always review AI-generated content before using it in critical systems. -> -> Join our [Discord channel](https://discord.gg/coder) or -> [contact us](https://coder.com/contact) to get help or share feedback. +This document includes a mix of cultural and technical best practices and guidelines for introducing AI agents into your organization. -## Overview +## Identify Use Cases -Coder templates should be pre-equipped with the tools and dependencies needed -for development. With AI Agents, this is no exception. +To successfully implement AI coding agents, identify 3-5 practical use cases where AI tools can deliver real value. Additionally, find a target group of developers and projects that are the best candidates for each specific use case. -## Prerequisites +Below are common scenarios where AI coding agents provide the most impact, along with the right tools for each use case: -- A Coder deployment with v2.21 or later -- A [template configured for AI agents](./create-template.md) +| Scenario | Description | Examples | Tools | +|------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------| +| **Automating actions in the IDE** | Supplement tedious development with agents | Small refactors, generating unit tests, writing inline documentation, code search and navigation | [IDE Agents](./ide-agents.md) in Workspaces | +| **Developer-led investigation and setup** | Developers delegate research and initial implementation to AI, then take over in their preferred IDE to complete the work | Bug triage and analysis, exploring technical approaches, understanding legacy code, creating starter implementations | [Tasks](./tasks.md), to a full IDE with [Workspaces](../user-guides/workspace-access/index.md) | +| **Prototyping & Business Applications** | User-friendly interface for engineers and non-technical users to build and prototype within new or existing codebases | Creating dashboards, building simple web apps, data analysis workflows, proof-of-concept development | [Tasks](./tasks.md) | +| **Full background jobs & long-running agents** | Agents that run independently without user interaction for extended periods of time | Automated code reviews, scheduled data processing, continuous integration tasks, monitoring and alerting | [Tasks](./tasks.md) API *(in development)* | +| **External agents and chat clients** | External AI agents and chat clients that need access to Coder workspaces for development environments and code sandboxing | ChatGPT, Claude Desktop, custom enterprise agents running tests, performing development tasks, code analysis | [MCP Server](./mcp-server.md) | -## Best Practices +## Provide Agents with Proper Context -- Use the most capable ML models you have access to in order to evaluate Agent - 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.). +While LLMs are trained on general knowledge, it's important to provide additional context to help agents understand your codebase and organization. - > Note: [External authentication](../admin/external-auth/index.md) can be helpful - > to authenticate with third-party services such as GitHub or JFrog. +### Memory -- 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. +Coding Agents like Claude Code often refer to a [memory file](https://docs.anthropic.com/en/docs/claude-code/memory) in order to gain context about your repository or organization. -## Adding Tools via MCP +Look up the docs for the specific agent you're using to learn more about how to provide context to your agents. -Model Context Protocol (MCP) is an emerging standard for adding tools to your -agents. +### Tools (Model Context Protocol) -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. +Agents can also use tools, often via [Model Context Protocol](https://modelcontextprotocol.io/introduction) to look up information or perform actions. A common example would be fetching style guidelines from an internal wiki, or looking up the documentation for a service within your catalog. -### Our Favorite MCP Servers +Look up the docs for the specific agent you're using to learn more about how to provide tools to your agents. -In internal testing, we have seen significant improvements in agent performance -when these tools are added via MCP. +#### 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. + Instruct your agent to run long-running tasks (e.g. `npm run dev`) in the background instead of blocking the main thread. + +## Security & Permissions + +LLMs and agents can be dangerous if not run with proper boundaries. Be sure not to give agents full permissions on behalf of a user, and instead use separate identities with limited scope whenever interacting autonomously. + +[Learn more about securing agents with Coder Tasks](./security.md) -## Next Steps +## Keep it Simple -- [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) +Today's LLMs and AI agents are not going to refactor entire codebases with production-grade code on their own! Using coding agents can be extremely fun and productive, but it is important to keep the scope of your use cases small and simple, and grow them over time. diff --git a/docs/ai-coder/coder-dashboard.md b/docs/ai-coder/coder-dashboard.md deleted file mode 100644 index 6232d16bfb593..0000000000000 --- a/docs/ai-coder/coder-dashboard.md +++ /dev/null @@ -1,29 +0,0 @@ -> [!NOTE] -> -> This functionality is in beta and is evolving rapidly. -> -> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment. -> Always review AI-generated content before using it in critical systems. -> -> 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/ai-coder/create-template.md b/docs/ai-coder/create-template.md deleted file mode 100644 index 53e61b7379fbe..0000000000000 --- a/docs/ai-coder/create-template.md +++ /dev/null @@ -1,66 +0,0 @@ -# Create a Coder template for agents - -> [!NOTE] -> -> This functionality is in beta and is evolving rapidly. -> -> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment. -> Always review AI-generated content before using it in critical systems. -> -> 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. - -> [!TIP] -> -> Alternatively, you can [use a custom agent](./custom-agents.md) that is -> not in our registry via MCP. - -The module uses `experiment_report_tasks` to stream changes to the Coder dashboard: - -```hcl -# Enable experimental features -experiment_use_screen = true # Or use experiment_use_tmux = true to use tmux instead -experiment_report_tasks = true -``` - -## 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/ai-coder/custom-agents.md b/docs/ai-coder/custom-agents.md index 3badc20cd8066..8755fc63a46f1 100644 --- a/docs/ai-coder/custom-agents.md +++ b/docs/ai-coder/custom-agents.md @@ -1,21 +1,11 @@ # Custom Agents -> [!NOTE] -> -> This functionality is in beta and is evolving rapidly. -> -> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment. -> Always review AI-generated content before using it in critical systems. -> -> Join our [Discord channel](https://discord.gg/coder) or -> [contact us](https://coder.com/contact) to get help or share feedback. - -Custom agents beyond the ones listed in the [Coder registry](https://registry.coder.com/modules?tag=agent) can be used with Coder. +Custom agents beyond the ones listed in the [Coder registry](https://registry.coder.com/modules?tag=agent) can be used with Coder Tasks. ## Prerequisites - A Coder deployment with v2.21 or later -- A [Coder workspace / template](./create-template.md) +- A [Coder workspace / template](../admin/templates/creating-templates.md) - A custom agent that supports Model Context Protocol (MCP) ## Getting Started @@ -31,8 +21,8 @@ From there, the agent can run the MCP server with the `coder exp mcp server` com Inside a Coder workspace, run the following commands: ```sh -coder login # be sure to be authenticated with the Coder CLI -export CODER_MCP_APP_STATUS_SLUG=my-agent # needs to be the same as the slug in the coder_app resource +coder login +export CODER_MCP_APP_STATUS_SLUG=my-agent # Use your own agent's logic and syntax here: any-custom-agent configure-mcp --name "coder" --command "coder exp mcp server" @@ -40,10 +30,9 @@ any-custom-agent configure-mcp --name "coder" --command "coder exp mcp server" This will start the MCP server and report activity back to the Coder control plane on behalf of the coder_app resource. -> See the [Goose module](https://github.com/coder/registry/blob/main/registry/coder/modules/goose/main.tf) source code for a real world example. +> [!NOTE] +> See [this version of the Goose module](https://github.com/coder/registry/blob/release/coder/goose/v1.3.0/registry/coder/modules/goose/main.tf) source code for a real world example. ## Contributing -We welcome contributions for various agents via the [Coder registry](https://registry.coder.com/modules?tag=agent)! - -See our [contributing guide](https://github.com/coder/registry/blob/main/CONTRIBUTING.md) for more information. +We welcome contributions for various agents via the [Coder registry](https://registry.coder.com/modules?tag=agent)! See our [contributing guide](https://github.com/coder/registry/blob/main/CONTRIBUTING.md) for more information. diff --git a/docs/ai-coder/headless.md b/docs/ai-coder/headless.md deleted file mode 100644 index 4a5b1190c7d15..0000000000000 --- a/docs/ai-coder/headless.md +++ /dev/null @@ -1,57 +0,0 @@ -> [!NOTE] -> -> This functionality is in beta and is evolving rapidly. -> -> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment. -> Always review AI-generated content before using it in critical systems. -> -> 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 exp mcp configure claude-desktop # Configure Claude Desktop to interact with Coder -coder exp mcp configure cursor # Configure Cursor to interact with Coder -``` - -> MCP is also used for various agents to report activity back to Coder. Learn more about this in [custom agents](./custom-agents.md). - -## Coder CLI - -Workspaces can be created, started, and stopped via the Coder CLI. See the -[CLI docs](../reference/cli/index.md) for more information. - -## REST API - -The Coder REST API can be used to manage workspaces and agents. See the -[API docs](../reference/api/index.md) for more information. - -## Next Steps - -- [Securing Agents](./securing.md) diff --git a/docs/ai-coder/ide-agents.md b/docs/ai-coder/ide-agents.md new file mode 100644 index 0000000000000..a6e960f28ee99 --- /dev/null +++ b/docs/ai-coder/ide-agents.md @@ -0,0 +1,26 @@ +Learn how to use Coder Workspaces with IDEs and plugins to run coding agents like Cursor, GitHub Copilot, Windsurf, RooCode, and more. + +## How it works + +Coder Workspaces are full development environments that run on your cloud infrastructure, such as Kubernetes or AWS EC2. Developers can connect with their favorite IDEs with pre-configured extensions and configuration for agentic coding. + +![Workspace Page](../images/guides/ai-agents/workspace-page.png) + +## Coder versus Local Development + +Running coding agents in Coder workspaces provides several advantages over running them locally: + +- **Fast, out-of-the-box setup**: LLMs, proxies, and MCP tools can be pre-configured for developers to use immediately, eliminating setup time and configuration hassles. +- **Consistent environments**: All developers use the same standardized environments, ensuring consistent access to tools and resources. +- **Resource optimization**: Leverage powerful cloud resources without taxing local machines. +- **Security and isolation**: Keep sensitive code, API keys, and secrets in controlled environments. + +[Learn more about Coder](https://coder.com/cde/compare) + +## IDE Support + +Follow the Coder Documentation for [Connecting to Workspaces](../user-guides/workspace-access/index.md) to connect to your Coder Workspaces with your favorite IDEs. + +## Pre-Configuring Extensions & Plugins + +Read our [VS Code module documentation](https://registry.coder.com/modules/coder/vscode-web) for examples on how to pre-install plugins like GitHub Copilot, RooCode, Sourcegraph Cody, and more in Coder workspaces. diff --git a/docs/ai-coder/ide-integration.md b/docs/ai-coder/ide-integration.md deleted file mode 100644 index fc61549aba739..0000000000000 --- a/docs/ai-coder/ide-integration.md +++ /dev/null @@ -1,30 +0,0 @@ -> [!NOTE] -> -> This functionality is in beta and is evolving rapidly. -> -> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment. -> Always review AI-generated content before using it in critical systems. -> -> 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) diff --git a/docs/ai-coder/index.md b/docs/ai-coder/index.md index 1d33eb6492eff..bb4d8ccda3da5 100644 --- a/docs/ai-coder/index.md +++ b/docs/ai-coder/index.md @@ -1,37 +1,19 @@ -# Use AI Coding Agents in Coder Workspaces +# Run AI Coding Agents in Coder -> [!NOTE] -> -> This functionality is in beta and is evolving rapidly. -> -> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment. -> Always review AI-generated content before using it in critical systems. -> -> Join our [Discord channel](https://discord.gg/coder) or -> [contact us](https://coder.com/contact) to get help or share feedback. +Learn how to run & manage coding agents with Coder, both alongside existing workspaces and for background task execution. -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: +## Agents in the IDE -- Protyping web applications or landing pages -- Researching / onboarding to a codebase -- Assisting with lightweight refactors -- Writing tests and draft documentation -- Small, well-defined chores +Coder [integrates with IDEs](../user-guides/workspace-access/index.md) such as Cursor, Windsurf, and Zed that include built-in coding agents to work alongside developers. Additionally, template admins can [pre-install extensions](https://registry.coder.com/modules/coder/vscode-web) for agents such as GitHub Copilot and Roo Code. -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. +These agents work well inside existing Coder workspaces as they can simply be enabled via an extension or are built-into the editor. -![AI Agents in Coder](../images/guides/ai-agents/landing.png) +## Agents with Coder Tasks (Beta) -## Prerequisites +In cases where the IDE is secondary, such as protyping or long-running background jobs, agents like Claude Code or Aider are better for the job and new SaaS interfaces like [Devin](https://devin.ai) and [ChatGPT Codex](https://openai.com/index/introducing-codex/) are emerging. -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. +[Coder Tasks](./tasks.md) is a new interface inside Coder to run and manage coding agents with a chat-based UI. Unlike SaaS-based products, Coder Tasks is self-hosted (included in your Coder deployment) and allows you to run any terminal-based agent such as Claude Code or Codex's Open Source CLI. -- A [Coder deployment](../install/index.md) with v2.21.0 or later -- A Coder [template](../admin/templates/index.md) 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 +![Coder Tasks UI](../images/guides/ai-agents/tasks-ui.png) -## Table of Contents - - +[Learn more about Coder Tasks](./tasks.md) to how to get started and best practices. diff --git a/docs/ai-coder/issue-tracker.md b/docs/ai-coder/issue-tracker.md deleted file mode 100644 index 76de457e18d61..0000000000000 --- a/docs/ai-coder/issue-tracker.md +++ /dev/null @@ -1,61 +0,0 @@ -# Create a Coder template for agents - -> [!NOTE] -> -> This functionality is in beta and is evolving rapidly. -> -> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment. -> Always review AI-generated content before using it in critical systems. -> -> 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/index.md) or [CLI](../reference/cli/index.md) 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) diff --git a/docs/ai-coder/mcp-server.md b/docs/ai-coder/mcp-server.md new file mode 100644 index 0000000000000..29d602030ab58 --- /dev/null +++ b/docs/ai-coder/mcp-server.md @@ -0,0 +1,33 @@ +# MCP Server + +Power users can configure Claude Desktop, Cursor, or other external agents to interact with Coder in order to: + +- List workspaces +- Create/start/stop workspaces +- Run commands on workspaces +- Check in on agent activity + +> [!NOTE] +> See our [toolsdk](https://pkg.go.dev/github.com/coder/coder/v2@v2.24.1/codersdk/toolsdk#pkg-variables) documentation for a full list of tools included in the MCP server + +In this model, any custom agent 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 +# First log in to Coder. +coder login + +# Configure your client with the Coder MCP +coder exp mcp configure claude-desktop # Configure Claude Desktop to interact with Coder +coder exp mcp configure cursor # Configure Cursor to interact with Coder +``` + +For other agents, run the MCP server with this command: + +```sh +coder exp mcp server +``` + +> [!NOTE] +> The MCP server is authenticated with the same identity as your Coder CLI and can perform any action on the user's behalf. Fine-grained permissions and a remote MCP server are in development. [Contact us](https://coder.com/contact) if this use case is important to you. diff --git a/docs/ai-coder/securing.md b/docs/ai-coder/security.md similarity index 57% rename from docs/ai-coder/securing.md rename to docs/ai-coder/security.md index af1c7825fdaa1..8d1e07ae1d329 100644 --- a/docs/ai-coder/securing.md +++ b/docs/ai-coder/security.md @@ -1,23 +1,13 @@ -> [!NOTE] -> -> This functionality is in early access and is evolving rapidly. -> -> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment. -> Always review AI-generated content before using it in critical systems. -> -> 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. +Most agents 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. +Coder templates to use those. ## Set up Firewalls and Proxies @@ -29,8 +19,7 @@ not access or upload sensitive information. 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 +This will likely involve editing your template for Agents to set different scopes or tokens from the standard one. Additional guidance and tooling is coming in future releases of Coder. @@ -42,7 +31,4 @@ 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) +- [Contact us for more information](https://coder.com/contact) and for early access to agent boundaries diff --git a/docs/ai-coder/tasks.md b/docs/ai-coder/tasks.md new file mode 100644 index 0000000000000..8e7d27f334dc1 --- /dev/null +++ b/docs/ai-coder/tasks.md @@ -0,0 +1,91 @@ +# Coder Tasks (Beta) + +Coder Tasks is an interface for running & managing coding agents such as Claude Code and Aider, powered by Coder workspaces. + +![Tasks UI](../images/guides/ai-agents/tasks-ui.png) + +Coder Tasks is best for cases where the IDE is secondary, such as prototyping or running long-running background jobs. However, tasks run inside full workspaces so developers can [connect via an IDE](../user-guides/workspace-access) to take a task to completion. + +> [!NOTE] +> Coder Tasks is free and open source. If you are a Coder Premium customer or want to run hundreds of tasks in the background, [contact us](https://coder.com/contact) for roadmap information and volume pricing. + +## Supported Agents (and Models) + +Any terminal-based agent that supports Model Context Protocol (MCP) can be integrated with Coder Tasks, including your own custom agents. + +Out of the box, agents like Claude Code, Aider, Goose, and Amazon Q are supported with built-in modules that can be added to a template. [See all agent modules in the Registry](https://registry.coder.com/modules?search=tag%3Aagent) + +Enterprise LLM Providers such as AWS Bedrock, GCP Vertex and proxies such as LiteLLM can be used as well in order to keep intellectual property private. Self-hosted models such as llama4 can also be configured with specific agents, such as Aider and Goose. + +## Architecture + +Each task runs inside its own Coder workspace for isolation purposes. Agents like Claude Code also run in the workspace, and can be pre-installed via a module in the Coder Template. Agents then communicate with your LLM provider, so no GPUs are directly required in your workspaces for inference. + +![High-Level Architecture](../images/guides/ai-agents/architecture-high-level.png) + +Coder's [built-in modules for agents](https://registry.coder.com/modules?search=tag%3Aagent) will pre-install the agent alongside [AgentAPI](https://github.com/coder/agentapi). AgentAPI is an open source project developed by Coder which improves status reporting and the Chat UI, regardless of which agent you use. + +## Getting Started with Tasks + +### Option 1) Import and Modify Our Example Template + +Our example template is the best way to experiment with Tasks with a [real world demo app](https://github.com/gothinkster/realworld). The application is running in the background and you can experiment with coding agents. + +![Tasks UI with realworld app](../images/guides/ai-agents/realworld-ui.png) + +Try prompts such as: + +- "rewrite the backend in go" +- "document the project structure" +- "change the primary color theme to purple" + +To import the template and begin configuring it, follow the [documentation in the Coder Registry](https://registry.coder.com/templates/coder-labs/tasks-docker) + +> [!NOTE] +> The Tasks tab will appear automatically after you add a Tasks-compatible template and refresh the page. + +### Option 2) Create or Duplicate Your Own Template + +A template becomes a Task template if it defines a `coder_ai_task` resource and a `coder_parameter` named `"AI Prompt"`. Coder analyzes template files during template version import to determine if these requirements are met. + +```hcl +data "coder_parameter" "ai_prompt" { + name = "AI Prompt" + type = "string" +} + +# Multiple coder_ai_tasks can be defined in a template +resource "coder_ai_task" "claude-code" { + # At most one coder ai task can be instantiated during a workspace build. + # Coder fails the build if it would instantiate more than 1. + count = data.coder_parameter.ai_prompt.value != "" ? 1 : 0 + + sidebar_app { + # which app to display in the sidebar on the task page + id = coder_app.claude-code.id + } +} +``` + +> [!NOTE] +> This definition is not final and may change while Tasks is in beta. After any changes, we guarantee backwards compatibility for one minor Coder version. After that, you may need to update your template to continue using it with Tasks. + +Because Tasks run unpredictable AI agents, often for background tasks, we recommend creating a separate template for Coder Tasks with limited permissions. You can always duplicate your existing template, then apply separate network policies/firewalls/permissions to the template. From there, follow the docs for one of our [built-in modules for agents](https://registry.coder.com/modules?search=tag%3Aagent) in order to add it to your template, configure your LLM provider. + +Alternatively, follow our guide for [custom agents](./custom-agents.md) + +## Customizing the Task UI + +The Task UI displays all workspace apps declared in a Task template. You can customize the app shown in the sidebar using the `sidebar_app.id` field on the `coder_ai_task` resource. + +If a workspace app has the special `"preview"` slug, a navbar will appear above it. This is intended for templates that let users preview a web app they’re working on. + +We plan to introduce more customization options in future releases. + +## Opting out of Tasks + +If you tried Tasks and decided you don't want to use it, you can hide the Tasks tab by starting `coder server` with the `CODER_HIDE_AI_TASKS=true` environment variable or the `--hide-ai-tasks` flag. + +## Next Steps + + diff --git a/docs/images/guides/ai-agents/architecture-high-level.png b/docs/images/guides/ai-agents/architecture-high-level.png new file mode 100644 index 0000000000000..0ca453906cdb4 Binary files /dev/null and b/docs/images/guides/ai-agents/architecture-high-level.png differ diff --git a/docs/images/guides/ai-agents/duplicate.png b/docs/images/guides/ai-agents/duplicate.png deleted file mode 100644 index 0122671424792..0000000000000 Binary files a/docs/images/guides/ai-agents/duplicate.png and /dev/null differ diff --git a/docs/images/guides/ai-agents/github-action.png b/docs/images/guides/ai-agents/github-action.png deleted file mode 100644 index 8ad695c137614..0000000000000 Binary files a/docs/images/guides/ai-agents/github-action.png and /dev/null differ diff --git a/docs/images/guides/ai-agents/github-pr.png b/docs/images/guides/ai-agents/github-pr.png deleted file mode 100644 index 3c4785e56a559..0000000000000 Binary files a/docs/images/guides/ai-agents/github-pr.png and /dev/null differ diff --git a/docs/images/guides/ai-agents/ide-integration.png b/docs/images/guides/ai-agents/ide-integration.png deleted file mode 100644 index 2ddd85c786e79..0000000000000 Binary files a/docs/images/guides/ai-agents/ide-integration.png and /dev/null differ diff --git a/docs/images/guides/ai-agents/landing.png b/docs/images/guides/ai-agents/landing.png deleted file mode 100644 index 40ac36383bc07..0000000000000 Binary files a/docs/images/guides/ai-agents/landing.png and /dev/null differ diff --git a/docs/images/guides/ai-agents/realworld-ui.png b/docs/images/guides/ai-agents/realworld-ui.png new file mode 100644 index 0000000000000..bd0c942e7cc19 Binary files /dev/null and b/docs/images/guides/ai-agents/realworld-ui.png differ diff --git a/docs/images/guides/ai-agents/tasks-ui.png b/docs/images/guides/ai-agents/tasks-ui.png new file mode 100644 index 0000000000000..a51e6d933d18d Binary files /dev/null and b/docs/images/guides/ai-agents/tasks-ui.png differ diff --git a/docs/images/guides/ai-agents/workspace-details.png b/docs/images/guides/ai-agents/workspace-details.png deleted file mode 100644 index 71e22d9604303..0000000000000 Binary files a/docs/images/guides/ai-agents/workspace-details.png and /dev/null differ diff --git a/docs/images/guides/ai-agents/workspace-page.png b/docs/images/guides/ai-agents/workspace-page.png new file mode 100644 index 0000000000000..0d9c09ac5c675 Binary files /dev/null and b/docs/images/guides/ai-agents/workspace-page.png differ diff --git a/docs/images/guides/ai-agents/workspaces-list.png b/docs/images/guides/ai-agents/workspaces-list.png deleted file mode 100644 index 32e07d0c41cf9..0000000000000 Binary files a/docs/images/guides/ai-agents/workspaces-list.png and /dev/null differ diff --git a/docs/manifest.json b/docs/manifest.json index 7deb94fdf56a9..9b85e634dce14 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -816,59 +816,40 @@ "description": "Learn how to run and integrate agentic AI coding agents like GPT-Code, OpenDevin, or SWE-Agent in Coder workspaces to boost developer productivity.", "path": "./ai-coder/index.md", "icon_path": "./images/icons/wand.svg", - "state": ["beta"], "children": [ { - "title": "Learn about coding agents", - "description": "Learn about the different agentic AI agents and their tradeoffs", - "path": "./ai-coder/agents.md" + "title": "Best Practices", + "description": "Best Practices running Coding Agents", + "path": "./ai-coder/best-practices.md" }, { - "title": "Create a Coder template for agents", - "description": "Create a purpose-built template for your agentic AI agents", - "path": "./ai-coder/create-template.md", - "state": ["beta"] - }, - { - "title": "Integrate with your issue tracker", - "description": "Assign tickets to agentic AI agents and interact via code reviews", - "path": "./ai-coder/issue-tracker.md", - "state": ["beta"] - }, - { - "title": "Model Context Protocols (MCP) and adding AI tools", - "description": "Improve results by adding tools to your agentic AI agents", - "path": "./ai-coder/best-practices.md", - "state": ["beta"] - }, - { - "title": "Supervise agents via Coder UI", - "description": "Interact with agentic agents via the Coder UI", - "path": "./ai-coder/coder-dashboard.md", - "state": ["beta"] - }, - { - "title": "Supervise agents via the IDE", - "description": "Interact with agentic agents via VS Code or Cursor", - "path": "./ai-coder/ide-integration.md", - "state": ["beta"] - }, - { - "title": "Programmatically manage agents", - "description": "Manage agentic agents via MCP, the Coder CLI, and/or REST API", - "path": "./ai-coder/headless.md", - "state": ["beta"] + "title": "In the IDE", + "description": "Run IDE agents with Coder", + "path": "./ai-coder/ide-agents.md" }, { - "title": "Securing agents in Coder", - "description": "Learn how to secure agentic agents with boundaries", - "path": "./ai-coder/securing.md", - "state": ["early access"] + "title": "Coder Tasks", + "description": "Run Coding Agents on your Own Infrastructure", + "path": "./ai-coder/tasks.md", + "state": ["beta"], + "children": [ + { + "title": "Custom Agents", + "description": "Run custom agents with Coder Tasks", + "path": "./ai-coder/custom-agents.md", + "state": ["beta"] + }, + { + "title": "Security \u0026 Boundaries", + "description": "Learn about security and boundaries when running AI coding agents in Coder", + "path": "./ai-coder/security.md" + } + ] }, { - "title": "Custom agents", - "description": "Learn how to use custom agentic agents with Coder", - "path": "./ai-coder/custom-agents.md", + "title": "MCP Server", + "description": "Connect to agents Coder with a MCP server", + "path": "./ai-coder/mcp-server.md", "state": ["beta"] } ] pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy