diff --git a/docs/ai-coder/ai-governance.md b/docs/ai-coder/ai-governance.md index 329c2e6887..8a0074c010 100644 --- a/docs/ai-coder/ai-governance.md +++ b/docs/ai-coder/ai-governance.md @@ -14,9 +14,6 @@ that help organizations safely roll out AI tooling at scale: MCP server management, and policy enforcement - [Agent Firewall](./agent-firewall/index.md): Process-level firewalls for agents, restricting which domains can be accessed by AI agents -- [Additional Tasks Use (via Agent Workspace Builds)](#how-coder-tasks-usage-is-measured): - Additional allowance of Agent Workspace Builds for continued use of Coder - Tasks. ## Who should use the AI Governance Add-On @@ -30,7 +27,6 @@ It's a good fit if you're: - Looking to centrally observe, audit, and govern AI activity in Coder Workspaces - Managing AI workflows against sensitive or regulated codebases -- Expanding the use of Coder Tasks for AI-driven background work If you already use other AI Governance tools, such as third-party LLM gateways or vendor-managed policies, you can continue using them. Coder Workspaces can diff --git a/docs/ai-coder/best-practices.md b/docs/ai-coder/best-practices.md index b96c76a808..8cfebeda81 100644 --- a/docs/ai-coder/best-practices.md +++ b/docs/ai-coder/best-practices.md @@ -8,18 +8,22 @@ To successfully implement AI coding agents, identify 3-5 practical use cases whe Below are common scenarios where AI coding agents provide the most impact, along with the right tools for each use case: -| 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) | +| 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 | [Coder Agents](./agents/index.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 | [Coder Agents](./agents/index.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 | [Coder Agents API](./agents/chats-api.md) | +| **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) | ## Provide Agents with Proper Context While LLMs are trained on general knowledge, it's important to provide additional context to help agents understand your codebase and organization. +For [Coder Agents](./agents/index.md), context comes from a few complementary places. Platform admins configure a [system prompt](./agents/platform-controls/index.md) that applies to every chat and register [MCP servers](./agents/platform-controls/mcp-servers.md) once for the whole deployment. Repos and workspace templates can ship reusable [skills](./agents/extending-agents.md) under `.agents/skills/`, which the agent discovers automatically when it attaches to the workspace. Developers don't need to manage memory files or wire up tools themselves. + +The rest of this section covers patterns for agents you run yourself inside a workspace, such as Claude Code or Codex. + ### Memory 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. @@ -46,7 +50,7 @@ In internal testing, we have seen significant improvements in agent performance 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) +[Learn more about securing AI agents](./security.md) ## Keep it Simple diff --git a/docs/ai-coder/index.md b/docs/ai-coder/index.md index 4e2423c2ff..cc00bb3495 100644 --- a/docs/ai-coder/index.md +++ b/docs/ai-coder/index.md @@ -14,35 +14,43 @@ for agents such as GitHub Copilot and Roo Code. These agents work well inside existing Coder workspaces as they can simply be enabled via an extension or are built-into the editor. -## Agents with Coder Tasks +## Coder Agents -In cases where the IDE is secondary, such as prototyping 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. +In cases where the IDE is secondary, such as prototyping, research, or +long-running background jobs, [Coder Agents](./agents/index.md) is the +recommended way to delegate development work to coding agents in your Coder +deployment. -[Coder Tasks](./tasks.md) is an 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. +Coder Agents is a native AI coding agent built into Coder. The agent loop runs +in the Coder control plane on your infrastructure rather than inside the +workspace, so workspaces can be completely network isolated. Developers +interact with agents through the web UI, the CLI (`coder agents`), or the +REST API. -![Coder Tasks UI](../images/guides/ai-agents/tasks-ui.png) +![Coder Agents chat interface with git diff sidebar](../images/agents-hero-image.png) -[Learn more about Coder Tasks](./tasks.md) for best practices and how to get -started. +[Learn more about Coder Agents](./agents/index.md) for architecture details, +supported LLM providers, and how to get started. -## Secure Your Workflows with Agent Firewall +## Govern AI activity with the AI Governance Add-On -AI agents can be powerful teammates, but must be treated as untrusted and -unpredictable interns as opposed to tools. Without the right controls, they can -go rogue. +AI coding tools are quickly becoming core to how engineering teams ship +software. As adoption grows, platform teams want a clear picture of how AI is +being used, consistent guardrails across teams, and predictable cost controls +so they can confidently scale AI tooling to the whole organization. -[Agent Firewall](./agent-firewall/index.md) is a new tool that offers -process-level safeguards that detect and prevent destructive actions. Unlike -traditional mitigation methods like firewalls, service meshes, and RBAC systems, -Agent Firewall is an agent-aware, centralized control point that can either be -embedded in the same secure Coder Workspaces that enterprises already trust, or -used through an open source CLI. +The [AI Governance Add-On](./ai-governance.md) is a per-user license that adds +observability, management, and policy controls for AI tooling across your +Coder deployment. It includes: -To learn more about features, implementation details, and how to get started, -check out the [Agent Firewall documentation](./agent-firewall/index.md). +- [AI Gateway](./ai-gateway/index.md) for centralized authentication, audit + trails of prompts and tool invocations, and policy enforcement against + upstream LLM providers. +- [Agent Firewall](./agent-firewall/index.md) for process-level network and + command policies that restrict what agents can reach and do inside a + workspace. +- Expanded Agent Workspace Build allowances for teams running AI-driven + background work at scale. + +[Learn more about the AI Governance Add-On](./ai-governance.md) for use cases, +entitlements, and how to enable it in your deployment.