From 5612bb81cbe5241dd3a0ec1605d67aa1604e4b02 Mon Sep 17 00:00:00 2001 From: Matt Vollmer Date: Mon, 4 May 2026 13:00:39 -0400 Subject: [PATCH] docs(docs/ai-coder): replace Coder Tasks references with Coder Agents (#24929) Updates `docs/ai-coder/index.md`, `docs/ai-coder/best-practices.md`, and `docs/ai-coder/ai-governance.md` to point readers at Coder Agents and the AI Governance Add-On instead of Coder Tasks and Agent Firewall (CODAGT-157). ## Changes - `docs/ai-coder/index.md`: - Rename `## Agents with Coder Tasks` to `## Coder Agents`. Drop the Devin / ChatGPT Codex name-drops and the Tasks pitch. New copy points at `./agents/index.md`, names the agent loop in the control plane, and notes that workspaces can be completely network isolated. Image swapped from `tasks-ui.png` to `agents-hero-image.png` (the hero shot added in #24915). - Replace the `## Secure Your Workflows with Agent Firewall` section with `## Govern AI activity with the AI Governance Add-On`. The new section opens with adoption-first framing (visibility, guardrails, cost) and links to `./ai-governance.md`, with bulleted callouts for AI Gateway, Agent Firewall, and the expanded Agent Workspace Build allowance the add-on bundles. - `docs/ai-coder/best-practices.md`: - In the use-case table, swap `[Tasks](./tasks.md)` to `[Coder Agents](./agents/index.md)` for the developer-led-investigation and prototyping rows, and swap the "Tasks API *(in development)*" cell to `[Coder Agents API](./agents/chats-api.md)` for the background-jobs row. Retitle the Security section link from "securing agents with Coder Tasks" to "securing AI agents" since `security.md` does not actually mention Tasks. Re-ran `markdown-table-formatter` to repad column widths. - In `## Provide Agents with Proper Context`, add a paragraph describing how context is provided in Coder Agents (admin-configured system prompts, centrally registered MCP servers, and skills shipped from repos or templates under `.agents/skills/`), with a transition line clarifying that the existing Memory and Tools subsections cover BYO-agent patterns. - `docs/ai-coder/ai-governance.md`: drop the "Additional Tasks Use (via Agent Workspace Builds)" bullet from the intro feature list and the "Expanding the use of Coder Tasks for AI-driven background work" bullet from the audience list. The `## How Coder Tasks usage is measured` section and the rest of the Tasks-related prose on this page are intentionally left for a follow-up PR. ## Notes for the reviewer - The `[Coder Agents API](./agents/chats-api.md)` link in `best-practices.md` will need to be retargeted if #24830 (which replaces `agents/chats-api.md` with auto-generated `reference/api/chats.md`) lands first. - This is the first slice of the Tasks-references audit. Remaining files (`tasks-core-principles.md`, `tasks-lifecycle.md`, `tasks-migration.md`, `cli.md`, `github-to-tasks.md`, `agent-compatibility.md`, the rest of `ai-governance.md`, `custom-agents.md`, `ai-gateway/clients/claude-code.md`, `manifest.json`, `reference/api/tasks.md`, the `task*` CLI references, the ESR upgrade guide, `feature-stages.md`, `workspace-scheduling.md`, `shared-workspaces.md`) will land in follow-up PRs against the same Linear ticket. Open PRs #24831, #24833, and #24841 cover separate slices and do not touch any file in this PR. - Validation: `markdownlint-cli2`, `markdown-table-formatter`, `scripts/check_emdash.sh`, and `make pre-commit-light` all pass. PR generated with Coder Agents. --- docs/ai-coder/ai-governance.md | 4 --- docs/ai-coder/best-practices.md | 20 +++++++----- docs/ai-coder/index.md | 56 +++++++++++++++++++-------------- 3 files changed, 44 insertions(+), 36 deletions(-) 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.