diff --git a/docs/ai-coder/agents/architecture.md b/docs/ai-coder/agents/architecture.md index a06b666d4f..3dfa30cad0 100644 --- a/docs/ai-coder/agents/architecture.md +++ b/docs/ai-coder/agents/architecture.md @@ -2,142 +2,112 @@ title: Architecture --- -Coder's AI agent interacts with workspaces over the same -connection path as a developer's IDE, web terminal, and SSH session already -use. There is no sidecar process and no new network paths. If your developers -can already connect to their workspaces, the agent can too. +Coder's AI agent interacts with workspaces over the same connection path as a developer's IDE, web terminal, and SSH session already use. +There is no sidecar process and no new network paths. +If your developers can already connect to their workspaces, the agent can too. ## Architecture at a glance Three components are involved in every agent interaction: -1. **The control plane** runs the agent loop. It receives prompts, streams them - to the LLM provider, interprets tool calls, and dispatches them to - workspaces. -1. **The LLM provider** (Anthropic, OpenAI, Google, Azure, AWS Bedrock, or any - OpenAI-compatible endpoint) performs model inference. It never communicates - with the workspace directly. -1. **The workspace** is standard compute infrastructure. It runs shell commands, - reads and writes files, and executes processes — exactly what occurs when a - developer connects via their IDE. +1. **The control plane** runs the agent loop. + It receives prompts, streams them to the LLM provider, interprets tool calls, and dispatches them to workspaces. +1. **The LLM provider** (Anthropic, OpenAI, Google, Azure, AWS Bedrock, or any OpenAI-compatible endpoint) performs model inference. + It never communicates with the workspace directly. +1. **The workspace** is standard compute infrastructure. + It runs shell commands, reads and writes files, and executes processes (exactly what occurs when a developer connects via their IDE). Architecture diagram ## The same connection your IDE uses -This is the key architectural insight: the agent reaches into a workspace -over the same Tailnet tunnel that a developer's tools already use. +This is the key architectural insight: the agent reaches into a workspace over the same Tailnet tunnel that a developer's tools already use. -When a developer opens a web terminal in the Coder dashboard, connects via -VS Code Remote, or runs `coder ssh`, the traffic follows this path: +When a developer opens a web terminal in the Coder dashboard, connects via VS Code Remote, or runs `coder ssh`, the traffic follows this path: 1. The client connects to the control plane. 1. The control plane routes the connection through its internal Tailnet node. -1. The connection reaches the workspace daemon over a DERP relay or - direct peer-to-peer link. -1. The workspace daemon handles the request — spawning a shell, - forwarding a port, or serving a file. +1. The connection reaches the workspace daemon over a DERP relay or direct peer-to-peer link. +1. The workspace daemon handles the request (spawning a shell, forwarding a port, or serving a file). -When the agent executes a tool call — reading a file, running a command, -writing code — it follows the same tunnel: +When the agent executes a tool call (reading a file, running a command, writing code), it follows the same tunnel: 1. The agent loop in the control plane issues a tool call. 1. The control plane routes the call through its internal Tailnet node. -1. The call reaches the workspace daemon over the same DERP relay or - peer-to-peer link. -1. The workspace daemon handles the request via its HTTP API — reading a file, - starting a process, or writing content. +1. The call reaches the workspace daemon over the same DERP relay or peer-to-peer link. +1. The workspace daemon handles the request via its HTTP API (reading a file, starting a process, or writing content). -The underlying tunnel is identical. IDE connections use SSH, web terminals use -a WebSocket protocol, and the agent uses the workspace daemon's HTTP API — but -all three traverse the same Tailnet connection and rely on the same security -boundary. No additional ports or network paths are introduced. +The underlying tunnel is identical. +IDE connections use SSH, web terminals use a WebSocket protocol, and the agent uses the workspace daemon's HTTP API, but all three traverse the same Tailnet connection and rely on the same security boundary. +No additional ports or network paths are introduced. ### No inbound ports -The workspace daemon always dials _out_ to the control plane — never -the reverse. The control plane then uses that established tunnel to reach back -in. This means: +The workspace daemon always dials _out_ to the control plane, never the reverse. +The control plane then uses that established tunnel to reach back in. +This means: - The workspace needs no inbound ports or exposed services. - You can block all inbound traffic to the workspace. -- The only required outbound connection from the workspace is to the control - plane itself. +- The only required outbound connection from the workspace is to the control plane itself. -This is unchanged from how workspaces already operate in Coder. Enabling -Coder Agents does not change your workspace network requirements. +This is unchanged from how workspaces already operate in Coder. +Enabling Coder Agents does not change your workspace network requirements. ## The agent loop -When a user submits a prompt, the control plane processes it as a background -job: +When a user submits a prompt, the control plane processes it as a background job: 1. The prompt is saved to the database and the chat is marked `running`. 1. A chat worker in the control plane claims the chat and starts a turn. 1. The control plane streams the conversation to the configured LLM provider. 1. The model responds with text, reasoning, or tool calls. -1. If the response includes tool calls, the control plane executes them - (connecting to the workspace as needed) and returns the results to the model. -1. Steps 3–5 repeat until the model produces a final response with no further - tool calls. +1. If the response includes tool calls, the control plane executes them (connecting to the workspace as needed) and returns the results to the model. +1. Steps 3 through 5 repeat until the model produces a final response with no further tool calls. 1. The chat is marked `waiting` for the next user message. -This loop runs inside the control plane process. There is no separate service -to deploy — it is part of the same binary that serves the dashboard and API. +This loop runs inside the control plane process. +There is no separate service to deploy. +It is part of the same binary that serves the dashboard and API. ### Context compaction -As conversations grow, the agent automatically summarizes older context to stay -within the model's context window. When token usage exceeds a threshold, the -agent generates a compressed summary and inserts it as a new message. Earlier -messages remain in the database and are still visible to users, but are excluded -from the model's context window. This happens transparently and keeps -long-running sessions productive. +As conversations grow, the agent automatically summarizes older context to stay within the model's context window. +When token usage exceeds a threshold, the agent generates a compressed summary and inserts it as a new message. +Earlier messages remain in the database and are still visible to users, but are excluded from the model's context window. +This happens transparently and keeps long-running sessions productive. -You can also trigger a compaction on demand by sending `/compact` while the -agent is idle or in an error state, which clears the error. Manual compaction -runs the same summarization regardless of current token usage and is labeled -as manual in the conversation. +You can also trigger a compaction on demand by sending `/compact` while the agent is idle or in an error state, which clears the error. +Manual compaction runs the same summarization regardless of current token usage and is labeled as manual in the conversation. -To start over without a summary, send `/clear` while the agent is idle or in -an error state. The transcript stays visible, but the next message runs with -a fresh context, as if the conversation were new. A "Context cleared" marker -shows where the reset happened. +To start over without a summary, send `/clear` while the agent is idle or in an error state. +The transcript stays visible, but the next message runs with a fresh context, as if the conversation were new. +A "Context cleared" marker shows where the reset happened. ### Message queuing -Users can send follow-up messages while the agent is actively working. Messages -are queued in the database and delivered when the agent completes its current -turn — the full sequence of steps until the model stops calling tools. There is -no need to wait for a response before providing additional context or -redirecting the agent. +Users can send follow-up messages while the agent is actively working. +Messages are queued in the database and delivered when the agent completes its current turn (the full sequence of steps until the model stops calling tools). +There is no need to wait for a response before providing additional context or redirecting the agent. ## Tool execution -Tools are how the agent takes action. Each tool call from the LLM translates to -a concrete operation — either inside a workspace or within the control plane -itself. +Tools are how the agent takes action. +Each tool call from the LLM translates to a concrete operation, either inside a workspace or within the control plane itself. -The agent is restricted to the built-in tool set defined in this section, -plus any additional tools from workspace skills and MCP servers. Skills -provide structured instructions the agent loads on demand -(see [Extending Agents](./extending-agents.md)). MCP tools come from -admin-configured external servers -(see [MCP Servers](./platform-controls/mcp-servers.md)) and from workspace -`.mcp.json` files. The agent has no direct access to the Coder API beyond -what these tools expose and cannot execute arbitrary operations against the -control plane. +The agent is restricted to the built-in tool set defined in this section, plus any additional tools from workspace skills and MCP servers. +Skills provide structured instructions the agent loads on demand (see [Extending Agents](./extending-agents.md)). +MCP tools come from admin-configured external servers (see [MCP Servers](./platform-controls/mcp-servers.md)) and from workspace `.mcp.json` files. +The agent has no direct access to the Coder API beyond what these tools expose and cannot execute arbitrary operations against the control plane. ### Workspace connection lifecycle -The connection to a workspace is **lazy**. It is not established when a chat -starts — only when something needs to reach the workspace. This is typically -triggered by the first tool call that requires workspace access. Once -established, the connection is cached and reused for the duration of that chat -session. +The connection to a workspace is **lazy**. +It is not established when a chat starts, only when something needs to reach the workspace. +This is typically triggered by the first tool call that requires workspace access. +Once established, the connection is cached and reused for the duration of that chat session. -Chats that don't need workspace access (answering questions, planning an -approach, discussing architecture) never provision or connect to a workspace. +Chats that don't need workspace access (answering questions, planning an approach, discussing architecture) never provision or connect to a workspace. ### Workspace tools @@ -158,17 +128,16 @@ They traverse the same Tailnet tunnel used by web terminals and IDE connections. #### Windows workspace shell requirement Coder Agents run workspace commands through a POSIX-compatible shell (`sh`). -Windows workspaces must provide `sh` on `PATH`, for example from -[Git for Windows](https://gitforwindows.org/) (Git Bash), MSYS2, or WSL. -PowerShell alone cannot run the `execute` tool. After installing a -shell, restart the workspace to pick up the updated `PATH`. +Windows workspaces must provide `sh` on `PATH`, for example from [Git for Windows](https://gitforwindows.org/) (Git Bash), MSYS2, or WSL. +PowerShell alone cannot run the `execute` tool. +After installing a shell, restart the workspace to pick up the updated `PATH`. ### Platform tools -These tools run entirely within the control plane. They do not require a -workspace connection. Platform and orchestration tools are only available to -root chats — sub-agents spawned by `spawn_agent` do not have access to them -and cannot create workspaces or spawn further sub-agents. +These tools run entirely within the control plane. +They do not require a workspace connection. +Platform and orchestration tools are only available to root chats. +Sub-agents spawned by `spawn_agent` do not have access to them and cannot create workspaces or spawn further sub-agents. | Tool | What it does | |---------------------|---------------------------------------------------------------------------------------------------| @@ -180,19 +149,15 @@ and cannot create workspaces or spawn further sub-agents. | `propose_plan` | Presents a Markdown plan file from the workspace for user review before implementation. | | `ask_user_question` | Asks the user structured clarification questions during plan mode. | -`propose_plan` and `ask_user_question` are only exposed while plan mode is -active. In that mode, `write_file` and `edit_files` are restricted to the -chat-specific plan file, while `execute` and `process_output` remain available -for exploration such as cloning repositories, searching code, and running -inspection commands. Root plan-mode chats may also receive administrator-approved -external MCP tools. Workspace MCP tools remain unavailable in plan mode, and -plan-mode sub-agents still do not receive any MCP tools. Dynamic, -provider-native, and computer-use tools are not available. +`propose_plan` and `ask_user_question` are only exposed while plan mode is active. +In that mode, `write_file` and `edit_files` are restricted to the chat-specific plan file, while `execute` and `process_output` remain available for exploration such as cloning repositories, searching code, and running inspection commands. +Root plan-mode chats may also receive administrator-approved external MCP tools. +Workspace MCP tools remain unavailable in plan mode, and plan-mode sub-agents still do not receive any MCP tools. +Dynamic, provider-native, and computer-use tools are not available. ### Orchestration tools -These tools manage sub-agents — child chats that work on independent tasks in -parallel. +These tools manage sub-agents (child chats that work on independent tasks in parallel). | Tool | What it does | |---------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -206,9 +171,8 @@ parallel. ### Provider tools -These tools are executed server-side by the LLM provider, not by the control -plane or workspace. They are conditionally available based on the model -configuration set by an administrator. +These tools are executed server-side by the LLM provider, not by the control plane or workspace. +They are conditionally available based on the model configuration set by an administrator. | Tool | What it does | |--------------|--------------------------------------------------------------------------------------------------------------------------------------------------| @@ -233,8 +197,7 @@ This tool runs in the control plane and replaces the full MCP tool schemas with ## What runs where -Understanding the split between the control plane and the workspace is central -to the security model. +Understanding the split between the control plane and the workspace is central to the security model. | Responsibility | Where it runs | Details | |---------------------|---------------|---------------------------------------------------------------------------| @@ -249,60 +212,54 @@ to the security model. | Git operations | Workspace | Commits, pushes, and branch management happen inside the workspace. | | Build and test | Workspace | Compilation, test suites, and dev servers run on workspace compute. | -The workspace has **zero AI awareness**. There are no LLM API keys, no agent -processes, and no AI-specific software installed. If you inspect a workspace -created by the agent, it looks identical to one a developer created -manually. +The workspace has **zero AI awareness**. +There are no LLM API keys, no agent processes, and no AI-specific software installed. +If you inspect a workspace created by the agent, it looks identical to one a developer created manually. ## Chat state and persistence All chat data is stored in the control plane database, not in the workspace. -- **Chat metadata** — status, owner, associated workspace, timestamps, and - parent/child relationships for sub-agents. -- **Messages** — every message (user, assistant, tool calls, tool results) is - stored as a separate record with role, content, and token usage. -- **Compressed context** — when the agent compacts the conversation, summaries - are stored with a compression flag so the original context budget is - preserved. -- **Queued messages** — follow-up messages sent while the agent is working are - held in a queue and delivered in order. +- **Chat metadata**: + status, owner, associated workspace, timestamps, and parent/child relationships for sub-agents. +- **Messages**: + every message (user, assistant, tool calls, tool results) is stored as a separate record with role, content, and token usage. +- **Compressed context**: + when the agent compacts the conversation, summaries are stored with a compression flag so the original context budget is preserved. +- **Queued messages**: + follow-up messages sent while the agent is working are held in a queue and delivered in order. Because state lives in the database: - Chat history survives workspace stops, rebuilds, and deletions. - An administrator can inspect any chat for audit or debugging. -- The agent can resume work by targeting a new workspace and continuing from the - last git branch or checkpoint. +- The agent can resume work by targeting a new workspace and continuing from the last git branch or checkpoint. ## Security posture -The control plane architecture provides built-in security properties for AI -coding workflows. These are structural guarantees, not configuration options — -they hold by default for every agent session. +The control plane architecture provides built-in security properties for AI coding workflows. +These are structural guarantees, not configuration options. +They hold by default for every agent session. ### No API keys in workspaces -LLM provider credentials exist only in the control plane. The workspace never -sees them. There is nothing for a developer, a compromised dependency, or a -rogue process to exfiltrate. +LLM provider credentials exist only in the control plane. +The workspace never sees them. +There is nothing for a developer, a compromised dependency, or a rogue process to exfiltrate. ### Workspaces can be fully network-isolated -Because the workspace does not need to reach any LLM provider, you can restrict -its network access to only: +Because the workspace does not need to reach any LLM provider, you can restrict its network access to only: - The control plane (required for the workspace daemon to function). - Your git provider (for push/pull operations). -Everything else can be blocked. The AI functionality comes from the control -plane, not from the workspace's network. +Everything else can be blocked. +The AI functionality comes from the control plane, not from the workspace's network. > [!TIP] -> For sensitive environments, create dedicated templates for agent workloads -> with stricter egress rules than your standard developer templates. Because -> the AI comes from the control plane, these templates do not need any -> outbound access to LLM providers. +> For sensitive environments, create dedicated templates for agent workloads with stricter egress rules than your standard developer templates. +> Because the AI comes from the control plane, these templates do not need any outbound access to LLM providers. ### Centralized enforcement @@ -317,34 +274,28 @@ Refer to [Organization scope](./platform-controls/organizations.md) for the sett ### User identity on every action -Every action the agent takes — PRs opened, code committed, commands executed — -is tied to the user who submitted the prompt. There is no shared bot account or -anonymous identity. If a developer submits a prompt that results in a pull -request, that pull request is attributed to them via the git authentication -already configured in your Coder deployment. +Every action the agent takes (PRs opened, code committed, commands executed) is tied to the user who submitted the prompt. +There is no shared bot account or anonymous identity. +If a developer submits a prompt that results in a pull request, that pull request is attributed to them via the git authentication already configured in your Coder deployment. ### Permission boundaries -The agent operates with the exact same permissions as the user who submitted -the prompt. If a user cannot access a template, workspace, or API endpoint -through the Coder dashboard or CLI, the agent cannot access it either. There -is no privilege escalation. +The agent operates with the exact same permissions as the user who submitted the prompt. +If a user cannot access a template, workspace, or API endpoint through the Coder dashboard or CLI, the agent cannot access it either. +There is no privilege escalation. -This extends to workspace isolation: the agent can only interact with -workspaces owned by the user who started the chat. It cannot read files, -execute commands, or connect to workspaces belonging to other users. +This extends to workspace isolation: the agent can only interact with workspaces owned by the user who started the chat. +It cannot read files, execute commands, or connect to workspaces belonging to other users. -Template visibility follows the same rule. When the agent lists available -templates, it sees only the templates the user is authorized to access. -The agent cannot provision a workspace from a template the user does not -have permission to use. +Template visibility follows the same rule. +When the agent lists available templates, it sees only the templates the user is authorized to access. +The agent cannot provision a workspace from a template the user does not have permission to use. ## Scaling and resource impact -The control plane overhead for Coder Agents is minimal. The heavy computation -happens elsewhere: +The control plane overhead for Coder Agents is minimal. +The heavy computation happens elsewhere: - **LLM inference** runs on the external provider's infrastructure. - **File I/O, builds, and tests** run on workspace compute. -- **The control plane** primarily proxies streaming responses and dispatches - tool calls over existing network connections. +- **The control plane** primarily proxies streaming responses and dispatches tool calls over existing network connections. diff --git a/docs/ai-coder/agents/chat-search-syntax.md b/docs/ai-coder/agents/chat-search-syntax.md index e92579e566..99843ea88b 100644 --- a/docs/ai-coder/agents/chat-search-syntax.md +++ b/docs/ai-coder/agents/chat-search-syntax.md @@ -2,10 +2,9 @@ title: Conversation search syntax --- -The chat list endpoint accepts a `q` query parameter for filtering -conversations. All filters use `key:value` syntax. Bare search terms -are rejected; use `title:` for title filtering or `search:` for -full-text search. +The chat list endpoint accepts a `q` query parameter for filtering conversations. +All filters use `key:value` syntax. +Bare search terms are rejected; use `title:` for title filtering or `search:` for full-text search. ## Filters @@ -23,26 +22,21 @@ full-text search. | `source` | `created_by_me`, `shared_with_me` | Ownership scope. Default: `created_by_me`. Pass both values comma-separated to return owned and shared conversations. | | `search` | text | Full-text search across chat titles, PR titles, PR numbers, and message content. Quote multi-word values. | -Multiple filters in one query combine with AND logic. `search:` cannot -be combined with `title:`, `pr_title:`, or `pr:`. +Multiple filters in one query combine with AND logic. +`search:` cannot be combined with `title:`, `pr_title:`, or `pr:`. ## Full-text search `search:` uses token-based PostgreSQL full-text search: -- Case-insensitive whole-word matching with AND semantics. Quoted - phrases, `OR`, and `-` negation follow - [`websearch_to_tsquery`](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES) - rules. -- Message content matches English word stems (`refactor` matches - `refactoring`) and ignores English stopwords. Titles and PR titles - do not stem. +- Case-insensitive whole-word matching with AND semantics. + Quoted phrases, `OR`, and `-` negation follow [`websearch_to_tsquery`](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES) rules. +- Message content matches English word stems (`refactor` matches `refactoring`) and ignores English stopwords. + Titles and PR titles do not stem. - No fuzzy, semantic, or word-prefix matching. - Whole-number values also match PR numbers by prefix: `302` matches PR `30281`. -- A value with no searchable words (punctuation only) returns an empty - list; an empty value returns HTTP 400. -- Results use the standard chat list ordering (pinned first, then most - recently updated) and pagination, without match snippets. +- A value with no searchable words (punctuation only) returns an empty list; an empty value returns HTTP 400. +- Results use the standard chat list ordering (pinned first, then most recently updated) and pagination, without match snippets. - Message content becomes searchable shortly after it is written (background indexing, usually within 10 minutes). Titles and PR titles are searchable immediately. @@ -99,9 +93,11 @@ be combined with `title:`, `pr_title:`, or `pr:`. - `status:waiting` is an idle conversation, `status:running` is a turn in progress, and `status:interrupting` is a turn being stopped. - `status:requires_action` means the agent needs you before it can continue, and `status:error` means the turn failed. -- `title:`, `repo:`, and `pr_title:` use ILIKE matching. `%` and `_` act as wildcards. +- `title:`, `repo:`, and `pr_title:` use ILIKE matching. + `%` and `_` act as wildcards. - `pr_status:draft` means the PR is open **and** marked as a draft. `pr_status:open` means the PR is open and not a draft. - `pr_status:none` matches conversations with no pull request, including those whose linked PR was cleared. -- Conversations without a linked diff status are excluded when `pr`, `repo`, `pr_title`, or any `pr_status` value other than `none` is set. The `repo:` filter also matches chats tracking a branch with no PR. +- Conversations without a linked diff status are excluded when `pr`, `repo`, `pr_title`, or any `pr_status` value other than `none` is set. + The `repo:` filter also matches chats tracking a branch with no PR. - Unrecognized keys, bare terms, or combining `search:` with `title:`, `pr_title:`, or `pr:` return HTTP 400 with a validation error. diff --git a/docs/ai-coder/agents/chat-sharing.md b/docs/ai-coder/agents/chat-sharing.md index 2142374e06..4c120c264a 100644 --- a/docs/ai-coder/agents/chat-sharing.md +++ b/docs/ai-coder/agents/chat-sharing.md @@ -6,21 +6,29 @@ Chat sharing lets you give other users or groups read-only access to a Coder Age ## Share a chat -1. Open the chat you want to share on the **Agents** page. Only top-level chats can be shared; sub-agent chats inherit sharing from their parent. +1. Open the chat you want to share on the **Agents** page. + Only top-level chats can be shared; sub-agent chats inherit sharing from their parent. 1. Select the share icon in the chat top bar. 1. Select the **Search for user or group** field. 1. Search for and select a user or group. 1. Select **Add member** to grant **Read** access. 1. If you shared with a group, copy the chat URL from your browser and send it to the group members. -Coder does not create a separate share link. Users you share with directly receive a **Chat Shared** notification with a link to open the chat. Members who gain access only through a group are not notified. +Coder does not create a separate share link. +Users you share with directly receive a **Chat Shared** notification with a link to open the chat. +Members who gain access only through a group are not notified. ## Shared chat access -Viewers can open the chat from a direct link, view messages, stream live updates, and download chat attachments. Chats shared by other users can appear in the sidebar under **Shared with you** when they are in the chat list. Pinned shared chats appear under **Pinned**. Viewers reach sub-agent chats by following sub-agent links inside the parent chat or by opening a direct URL. +Viewers can open the chat from a direct link, view messages, stream live updates, and download chat attachments. +Chats shared by other users can appear in the sidebar under **Shared with you** when they are in the chat list. +Pinned shared chats appear under **Pinned**. +Viewers reach sub-agent chats by following sub-agent links inside the parent chat or by opening a direct URL. Viewers have read-only access: they cannot send or edit messages, regenerate the chat title, archive the chat, or change its sharing settings. ## Disable chat sharing -Administrators can disable chat sharing for a deployment with `--disable-chat-sharing`, `CODER_DISABLE_CHAT_SHARING`, or `disableChatSharing`. The flag also turns off chat project sharing. While it is set, existing shares are ignored, new shares are rejected, and only creators and administrators can access chats and chat projects. +Administrators can disable chat sharing for a deployment with `--disable-chat-sharing`, `CODER_DISABLE_CHAT_SHARING`, or `disableChatSharing`. +The flag also turns off chat project sharing. +While it is set, existing shares are ignored, new shares are rejected, and only creators and administrators can access chats and chat projects. diff --git a/docs/ai-coder/agents/extending-agents.md b/docs/ai-coder/agents/extending-agents.md index 4546e6f75b..3893121278 100644 --- a/docs/ai-coder/agents/extending-agents.md +++ b/docs/ai-coder/agents/extending-agents.md @@ -3,9 +3,7 @@ title: Extending agents --- Workspace templates can extend the agent with custom skills and MCP tools. -These mechanisms let platform teams provide repository-specific instructions, -domain expertise, and external tool integrations without modifying the agent -itself. +These mechanisms let platform teams provide repository-specific instructions, domain expertise, and external tool integrations without modifying the agent itself. ## How the workspace shares context with chats @@ -97,12 +95,9 @@ Two tools are registered when skills are present: | `read_skill` | `name` (string) | Returns the SKILL.md body, the absolute skill directory (workspace skills), and a list of supporting files | | `read_skill_file` | `name` (string), `path` (string) | Returns the content of a supporting file | -For workspace skills, `read_skill` also returns `dir`, the absolute path to -the skill directory in the workspace. The agent's `read_file` and `execute` -tools operate on that same workspace filesystem, so you can join `dir` with a -supporting file's relative path to read or run that file directly, for example -to execute a bundled `scripts/` helper. `read_skill_file` remains available as -a path-safe convenience for reading supporting files. +For workspace skills, `read_skill` also returns `dir`, the absolute path to the skill directory in the workspace. +The agent's `read_file` and `execute` tools operate on that same workspace filesystem, so you can join `dir` with a supporting file's relative path to read or run that file directly, for example to execute a bundled `scripts/` helper. +`read_skill_file` remains available as a path-safe convenience for reading supporting files. Supporting files are read over the workspace connection, so `read_skill_file` and the supporting-file list need a reachable workspace. The skill body comes from the pin and keeps working when the workspace is unreachable. @@ -124,8 +119,7 @@ The skill body comes from the pin and keeps working when the workspace is unreac ### SKILL.md format -Each `SKILL.md` starts with YAML frontmatter containing a `name` and an -optional `description`, followed by the full instructions in markdown: +Each `SKILL.md` starts with YAML frontmatter containing a `name` and an optional `description`, followed by the full instructions in markdown: ```md --- @@ -140,8 +134,7 @@ Instructions for the skill go here... ### Naming and size constraints -- Names must be kebab-case (`^[a-z0-9]+(-[a-z0-9]+)*$`) and match the - directory name exactly. +- Names must be kebab-case (`^[a-z0-9]+(-[a-z0-9]+)*$`) and match the directory name exactly. - `SKILL.md` has a maximum size of 64 KB. A larger file is reported with an oversize status and contributes no content to the chat. - Supporting files have a maximum size of 512 KB. @@ -151,9 +144,8 @@ A skill with its frontmatter missing, unparsable, not kebab-case, or not matchin ### Path safety -`read_skill_file` rejects absolute paths, paths containing `..`, and -references to hidden files. All paths are resolved relative to the skill -directory. +`read_skill_file` rejects absolute paths, paths containing `..`, and references to hidden files. +All paths are resolved relative to the skill directory. ## Personal skills @@ -161,10 +153,8 @@ Personal skills are user-owned skills that are available to all of your chats. They are not tied to a specific workspace. Manage them from the **Agents** page, under **Settings** > **Skills**, in the **Personal skills** section. -Personal skills use the same `SKILL.md` format as workspace skills: YAML -frontmatter with a kebab-case `name`, an optional `description`, and a -markdown body. This keeps content portable between personal skills and -workspace skills. +Personal skills use the same `SKILL.md` format as workspace skills: YAML frontmatter with a kebab-case `name`, an optional `description`, and a markdown body. +This keeps content portable between personal skills and workspace skills. ```md --- @@ -177,15 +167,14 @@ description: "Personal review guidance" Instructions for the skill go here... ``` -Each personal skill is stored as a single `SKILL.md` file containing -frontmatter and body content. Supporting files are not supported. Each -`SKILL.md` file can be up to 64 KB, and each user can create up to 100 personal skills. +Each personal skill is stored as a single `SKILL.md` file containing frontmatter and body content. +Supporting files are not supported. +Each `SKILL.md` file can be up to 64 KB, and each user can create up to 100 personal skills. Personal skills are stored in Coder, not in the workspace, so they are not part of a workspace context snapshot and do not depend on a pin or a refresh. -If you need richer skills with supporting files or multiple files, use -workspace skills instead. Store them in the repo under -`.agents/skills//`, or load them from a workspace. +If you need richer skills with supporting files or multiple files, use workspace skills instead. +Store them in the repo under `.agents/skills//`, or load them from a workspace. ## Organization skills @@ -292,18 +281,15 @@ The `read_skill` result returns the skill body without the frontmatter, so it do ## Workspace MCP tools -Workspace templates can expose custom -[MCP](https://modelcontextprotocol.io/introduction) tools by placing a -`.mcp.json` file in the workspace working directory. +Workspace templates can expose custom [MCP](https://modelcontextprotocol.io/introduction) tools by placing a `.mcp.json` file in the workspace working directory. The agent connects to these servers, reports their tools in the context snapshot it pushes, and chats register those tools alongside their built-in tools. To declare an MCP server inline on one chat through the API instead, refer to [Inline MCP servers](./platform-controls/mcp-servers.md#inline-mcp-servers-experimental). ### Configuration -Define MCP servers in `.mcp.json` at the workspace root. Each entry under -`mcpServers` describes a server. The transport type is inferred from -whether `command` or `url` is present, or you can set it explicitly with -`type`: +Define MCP servers in `.mcp.json` at the workspace root. +Each entry under `mcpServers` describes a server. +The transport type is inferred from whether `command` or `url` is present, or you can set it explicitly with `type`: ```json { @@ -321,11 +307,13 @@ whether `command` or `url` is present, or you can set it explicitly with } ``` -**Stdio transport**: set `command`, and optionally `args` and `env`. The -agent spawns the process in the workspace. +**Stdio transport**: +set `command`, and optionally `args` and `env`. +The agent spawns the process in the workspace. -**HTTP transport**: set `url`, and optionally `headers`. The agent connects -to the HTTP endpoint from the workspace. +**HTTP transport**: +set `url`, and optionally `headers`. +The agent connects to the HTTP endpoint from the workspace. ### How discovery works @@ -346,10 +334,11 @@ Every workspace MCP tool call is proxied back through the workspace agent, so a ### Tool naming -Tool names are prefixed with the server name as `serverName__toolName` to -avoid collisions between servers and with built-in tools. +Tool names are prefixed with the server name as `serverName__toolName` to avoid collisions between servers and with built-in tools. ### Timeouts -- **Server connect**: 30 seconds per server. -- **Tool calls**: 60 seconds per invocation. +- **Server connect**: + 30 seconds per server. +- **Tool calls**: + 60 seconds per invocation. diff --git a/docs/ai-coder/agents/getting-started.md b/docs/ai-coder/agents/getting-started.md index 67d08b6cd2..76ae36c252 100644 --- a/docs/ai-coder/agents/getting-started.md +++ b/docs/ai-coder/agents/getting-started.md @@ -2,22 +2,19 @@ title: Getting started --- -This guide walks platform teams and administrators through setting up Coder -Agents, preparing your deployment, and running your first Coder Agent. +This guide walks platform teams and administrators through setting up Coder Agents, preparing your deployment, and running your first Coder Agent. ## Prerequisites Before you begin, confirm the following: - **Coder deployment** running the latest release. -- **LLM provider credentials** — an API key for at least one - [supported provider](./models.md) (Anthropic, OpenAI, Google, Azure OpenAI, - AWS Bedrock, OpenAI Compatible, OpenRouter, or Vercel AI Gateway). -- **Network access** from the control plane to your LLM provider. Workspaces - do not need LLM access — only the control plane does. -- **At least one template** with a - [descriptive name and description](./platform-controls/template-optimization.md) - for the agent to select when provisioning workspaces. +- **LLM provider credentials**: + an API key for at least one [supported provider](./models.md) (Anthropic, OpenAI, Google, Azure OpenAI, AWS Bedrock, OpenAI Compatible, OpenRouter, or Vercel AI Gateway). +- **Network access** from the control plane to your LLM provider. + Workspaces do not need LLM access. + Only the control plane does. +- **At least one template** with a [descriptive name and description](./platform-controls/template-optimization.md) for the agent to select when provisioning workspaces. - **Admin access** to the Coder deployment for configuring providers. - **Access to configure models** in each organization where you configure models. The **Organization Admin** role and the **Owner** role include this access. @@ -42,8 +39,7 @@ Before you begin, confirm the following: To configure Coder Agents: 1. Navigate to **Admin settings** > **AI** and select **Providers**. -1. Add or update a provider with its credentials and upstream endpoint, then - save it. +1. Add or update a provider with its credentials and upstream endpoint, then save it. 1. Navigate to **Admin settings** > **AI** > **Models**. 1. Select the correct organization. Coder shows the organization picker when you can access more than 1 organization. @@ -56,12 +52,10 @@ Each organization has its own model list and its own default model. Repeat the model steps in every organization that uses Coder Agents. Refer to [Organization scope](./platform-controls/organizations.md) for the settings that stay deployment-wide. -Detailed instructions for each provider and model option are in the -[Models](./models.md) documentation. +Detailed instructions for each provider and model option are in the [Models](./models.md) documentation. > [!TIP] -> Start with a single frontier model to validate your setup before adding -> additional providers. +> Start with a single frontier model to validate your setup before adding additional providers. ## Step 2: Start your first Coder Agent @@ -105,8 +99,8 @@ Keep the following behavior in mind: ## Optimize your templates The agent selects templates based on their **name, description, and README**. -It does not read Terraform. Clear, specific descriptions are the most important -factor in whether the agent picks the right template. +It does not read Terraform. +Clear, specific descriptions are the most important factor in whether the agent picks the right template. Update your template descriptions to include: @@ -114,14 +108,9 @@ Update your template descriptions to include: - Which repository or service it is for, if applicable. - What type of work it supports (backend, frontend, data pipeline, etc.). -When 128 characters is not enough, put the most important routing context near -the top of the template's -[`README.md`](./platform-controls/template-optimization.md#put-routing-context-near-the-top-of-the-readme). -The chat agent's template listing includes a bounded README excerpt (roughly the -first 1,000 characters), and template detail includes the README (up to roughly -8,000 characters). Both are reduced to plain text: frontmatter is stripped, -link text is kept while link URLs are dropped, images and badges are dropped -entirely, and code blocks and tables are preserved as text. +When 128 characters is not enough, put the most important routing context near the top of the template's [`README.md`](./platform-controls/template-optimization.md#put-routing-context-near-the-top-of-the-readme). +The chat agent's template listing includes a bounded README excerpt (roughly the first 1,000 characters), and template detail includes the README (up to roughly 8,000 characters). +Both are reduced to plain text: frontmatter is stripped, link text is kept while link URLs are dropped, images and badges are dropped entirely, and code blocks and tables are preserved as text. **Good examples:** @@ -139,9 +128,7 @@ entirely, and code blocks and tables are preserved as text. | Dev environment | Too generic to distinguish from other templates | | Default | Tells the agent nothing | -See [Template Optimization](./platform-controls/template-optimization.md) for -the full guide, including dedicated agent templates, network boundaries, -credential scoping, and pre-installing dependencies. +See [Template Optimization](./platform-controls/template-optimization.md) for the full guide, including dedicated agent templates, network boundaries, credential scoping, and pre-installing dependencies. ## Things to know before you start @@ -153,20 +140,17 @@ As always, you should review [release notes](https://github.com/coder/coder/rele ### Use HTTPS for push notifications -Coder Agents use browser push notifications to alert you when a task -completes or needs attention. Most browsers require a secure (HTTPS) -origin for the [Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) -to work. If your access URL uses plain HTTP, -push notifications may not function. +Coder Agents use browser push notifications to alert you when a task completes or needs attention. +Most browsers require a secure (HTTPS) origin for the [Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) to work. +If your access URL uses plain HTTP, push notifications may not function. -This does not affect agents themselves — only the browser notification -delivery. If you terminate TLS at a reverse proxy, ensure the -[access URL](../../admin/setup/index.md) is configured with an `https://` scheme. +This does not affect agents themselves, only the browser notification delivery. +If you terminate TLS at a reverse proxy, ensure the [access URL](../../admin/setup/index.md) is configured with an `https://` scheme. ### Set a deployment-wide system prompt -Administrators can set a system prompt that applies to all Coder Agents across the -deployment. Use this to encode organizational conventions: +Administrators can set a system prompt that applies to all Coder Agents across the deployment. +Use this to encode organizational conventions: - Coding standards and style guidelines. - Commit message formats. @@ -174,8 +158,7 @@ deployment. Use this to encode organizational conventions: - Required review processes before merging. - Any guardrails specific to your environment. -Configure the system prompt from **Admin settings** > **AI** > **Coder Agents** > **Instructions** -or via the API at `PUT /api/v2/chats/config/system-prompt`. +Configure the system prompt from **Admin settings** > **AI** > **Coder Agents** > **Instructions** or via the API at `PUT /api/v2/chats/config/system-prompt`. In a deployment with several organizations, organization administrators can also add organization instructions under **Admin settings** > **AI** > **Coder Agents** > **Instructions**. Coder adds them after the deployment system prompt for new chats in that organization. @@ -183,27 +166,27 @@ Refer to [Platform Controls](./platform-controls/index.md#system-prompt) for det ### Understand the security model -The agent runs in the control plane, not inside workspaces. This means: +The agent runs in the control plane, not inside workspaces. +This means: -- **No LLM API keys in workspaces.** Credentials stay in the control plane. -- **No agent software in workspaces.** No supply chain risk from - third-party agent tools. -- **User identity is always attached.** Every action is tied to the user - who submitted the prompt — no shared bot accounts. -- **No privilege escalation.** The agent has exactly the same permissions - as the prompting user. +- **No LLM API keys in workspaces.** + Credentials stay in the control plane. +- **No agent software in workspaces.** + No supply chain risk from third-party agent tools. +- **User identity is always attached.** + Every action is tied to the user who submitted the prompt, with no shared bot accounts. +- **No privilege escalation.** + The agent has exactly the same permissions as the prompting user. -Agent workspaces inherit the same network access as any manually created -workspace. If your templates don't restrict egress, the agent has full -internet access from the workspace. Consider -[creating dedicated agent templates](./platform-controls/template-optimization.md#create-dedicated-agent-templates) -with tighter network policies. +Agent workspaces inherit the same network access as any manually created workspace. +If your templates don't restrict egress, the agent has full internet access from the workspace. +Consider [creating dedicated agent templates](./platform-controls/template-optimization.md#create-dedicated-agent-templates) with tighter network policies. ### Plan for LLM costs -Every conversation turn sends tokens to your LLM provider. Long-running tasks, -sub-agent delegation, and complex multi-step work can consume significant -token volume. Consider: +Every conversation turn sends tokens to your LLM provider. +Long-running tasks, sub-agent delegation, and complex multi-step work can consume significant token volume. +Consider: - Starting with a single model to establish a cost baseline. - Capping spend with [AI Gateway budgets](./platform-controls/spend-management.md). @@ -223,12 +206,12 @@ Refer to [Concurrent agents](./platform-controls/index.md#concurrent-agents) for Identify 3–5 developers and a few concrete use cases for the initial rollout. Good starting points: -- **Low-risk, high-visibility tasks** — generating unit tests, writing inline - documentation, small refactors. -- **Investigation and triage** — exploring unfamiliar code, triaging bugs, - understanding legacy systems. -- **Prototyping** — building proof-of-concept implementations, simple - dashboards, internal tools. +- **Low-risk, high-visibility tasks**: + generating unit tests, writing inline documentation, small refactors. +- **Investigation and triage**: + exploring unfamiliar code, triaging bugs, understanding legacy systems. +- **Prototyping**: + building proof-of-concept implementations, simple dashboards, internal tools. To limit Coder Agents to the pilot group, see [Control who can use Coder Agents](#control-who-can-use-coder-agents). @@ -265,10 +248,8 @@ Stream updates in real time by connecting to the WebSocket endpoint: GET /api/v2/chats/{chat}/stream ``` -For service-to-service automation, use -[API keys](../../admin/users/sessions-tokens.md) -rather than developer session tokens. Keep automation credentials -narrowly scoped. +For service-to-service automation, use [API keys](../../admin/users/sessions-tokens.md) rather than developer session tokens. +Keep automation credentials narrowly scoped. ### Link to a new chat with a prompt @@ -291,10 +272,8 @@ URLs end up in browser history and server logs. ### Add workspace context with AGENTS.md -Create an `AGENTS.md` file in the home directory (`~/.coder/AGENTS.md`) or -the workspace agent's working directory to provide persistent context to the -agent. This file is automatically read and included in the system prompt -for every conversation with a Coder Agent that uses that workspace. +Create an `AGENTS.md` file in the home directory (`~/.coder/AGENTS.md`) or the workspace agent's working directory to provide persistent context to the agent. +This file is automatically read and included in the system prompt for every conversation with a Coder Agent that uses that workspace. Use it for: @@ -305,12 +284,9 @@ Use it for: ### Consider prebuilt workspaces for faster startup -Workspace provisioning is the main source of latency when the agent starts a -task. If your templates take more than a minute to provision, consider -configuring -[prebuilt workspaces](../../admin/templates/extending-templates/prebuilt-workspaces.md) -to maintain a pool of ready-to-use workspaces. The agent gets assigned an -already-running workspace instead of provisioning from scratch. +Workspace provisioning is the main source of latency when the agent starts a task. +If your templates take more than a minute to provision, consider configuring [prebuilt workspaces](../../admin/templates/extending-templates/prebuilt-workspaces.md) to maintain a pool of ready-to-use workspaces. +The agent gets assigned an already-running workspace instead of provisioning from scratch. @@ -321,20 +297,19 @@ For deployment-specific problems, such as provider configuration or performance Good reports include: -- **What you tried**: the prompt, the template, and the model. -- **What happened**: the agent's behavior, any errors, and unexpected results. -- **What you expected**: the outcome you were looking for. -- **Context**: screenshots, `chat_id` values, or links to the Agents page help - the team investigate quickly. +- **What you tried**: + the prompt, the template, and the model. +- **What happened**: + the agent's behavior, any errors, and unexpected results. +- **What you expected**: + the outcome you were looking for. +- **Context**: + screenshots, `chat_id` values, or links to the Agents page help the team investigate quickly. ## Next steps -- [Architecture](./architecture.md) — how the control plane, LLM providers, - and workspaces interact. +- [Architecture](./architecture.md): how the control plane, LLM providers, and workspaces interact. - [Models](./models.md) — configure additional providers and models. -- [Platform Controls](./platform-controls/index.md) — system prompts, - template routing, and admin-level configuration. -- [Template Optimization](./platform-controls/template-optimization.md) — - create agent-friendly templates with network boundaries and scoped - credentials. +- [Platform Controls](./platform-controls/index.md): system prompts, template routing, and admin-level configuration. +- [Template Optimization](./platform-controls/template-optimization.md): create agent-friendly templates with network boundaries and scoped credentials. - [Chats API](../../reference/api/chats.md): build programmatic integrations. diff --git a/docs/ai-coder/agents/index.md b/docs/ai-coder/agents/index.md index de688451b9..1b5c4ef110 100644 --- a/docs/ai-coder/agents/index.md +++ b/docs/ai-coder/agents/index.md @@ -2,12 +2,13 @@ title: Coder Agents --- -Coder Agents is a chat interface and API for delegating development work and research to coding agents in your Coder deployment. Developers describe the work they want done, and Coder Agents handles selecting a template, provisioning a workspace, and executing the task. +Coder Agents is a chat interface and API for delegating development work and research to coding agents in your Coder deployment. +Developers describe the work they want done, and Coder Agents handles selecting a template, provisioning a workspace, and executing the task. -Coder Agents includes its own self-hosted AI coding -agent that runs the agent loop directly within the Coder control plane. +Coder Agents includes its own self-hosted AI coding agent that runs the agent loop directly within the Coder control plane. -No specialized software, API keys, or network access is required inside your workspace. The only requirement is network access between the control plane and external LLM providers. +No specialized software, API keys, or network access is required inside your workspace. +The only requirement is network access between the control plane and external LLM providers.