mirror of
https://github.com/coder/coder.git
synced 2026-09-21 20:51:01 +08:00
docs: close Coder Agents coverage gaps and align nav references (#24971)
Closes coverage gaps in `docs/ai-coder/agents/` and aligns nav references with the current UI (post #24574 Behavior split, post #24644 Insights removal). **Content fixes:** - Replace site-wide `coder users edit-roles` flow with org-scoped `agents-access` role (per migration `000475`). CLI examples now preserve existing org roles since `edit-roles` overwrites the full set. - Correct computer-use claim: supports Anthropic *and* OpenAI providers, configured under the Virtual desktop experiment. - New `platform-controls/experiments.md` covering Virtual desktop, Advisor, and Chat debug logging (each as: what, how to enable, API). Includes the Debug tab in the chat right panel. - Trim `models.md` "Model overrides" to essentials: two layers (admin subagent, user personal), contexts table, resolution order, API pointer. - Remove retired `platform-controls/pr-insights.md` (page + manifest + cross-links). **Nav cleanup:** - Admin-only tabs use the full `Agents > Settings > Manage Agents > <Tab>` path; user-side tabs keep `Agents > Settings > <Tab>`. - Replace stale "Behavior" references with Instructions / Lifecycle / Experiments to match the current sidebar. - Replace references to the removed top-bar Admin dialog with the Settings sidebar. <details> <summary>Decision log</summary> - Experimental features were originally drafted as a standalone Advisor page plus inline sections in `platform-controls/index.md`. Consolidated into one `experiments.md` since no individual feature warrants a full page yet and parallel short sections are easier to scan. - Reviewer feedback on early drafts: drop the inline experiments list from `index.md` (avoid drift), drop the "users created before this role was introduced" note (handled transparently by migration `000475`), specify the full nav path for per-model pricing, link the `type=computer_use` row in `architecture.md` to the Experiments page. - CLI bulk-grant script previously called `edit-roles <user> agents-access`. That replaces the user's full org role set, so the script would silently strip `organization-admin`, `organization-template-admin`, etc. Rewrote to read each user's current roles, append `agents-access`, dedupe, and write the union back. </details> PR generated with Coder Agents.
This commit is contained in:
Matt Vollmer
@@ -173,13 +173,13 @@ provider-native, and computer-use tools are not available.
|
||||
These tools manage sub-agents — child chats that work on independent tasks in
|
||||
parallel.
|
||||
|
||||
| Tool | What it does |
|
||||
|---------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `spawn_agent` (`type=general` or `explore`) | Delegates a task to a sub-agent with its own context window. |
|
||||
| `wait_agent` | Waits for a sub-agent to finish and collects its result. |
|
||||
| `message_agent` | Sends a follow-up message to a running sub-agent. |
|
||||
| `close_agent` | Stops a running sub-agent. |
|
||||
| `spawn_agent` (`type=computer_use`) | Spawns a sub-agent with desktop interaction capabilities (screenshot, mouse, keyboard). Requires an Anthropic or OpenAI provider and the desktop feature to be enabled by an administrator. |
|
||||
| Tool | What it does |
|
||||
|---------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `spawn_agent` (`type=general` or `explore`) | Delegates a task to a sub-agent with its own context window. |
|
||||
| `wait_agent` | Waits for a sub-agent to finish and collects its result. |
|
||||
| `message_agent` | Sends a follow-up message to a running sub-agent. |
|
||||
| `close_agent` | Stops a running sub-agent. |
|
||||
| `spawn_agent` (`type=computer_use`) | Spawns a sub-agent with desktop interaction capabilities (screenshot, mouse, keyboard). Requires an administrator-configured computer-use provider (Anthropic or OpenAI) and the [virtual desktop experiment](./platform-controls/experiments.md#virtual-desktop) to be enabled. |
|
||||
|
||||
### Provider tools
|
||||
|
||||
|
||||
@@ -22,22 +22,23 @@ Before you begin, confirm the following:
|
||||
for the agent to select when provisioning workspaces.
|
||||
- **Admin access** to the Coder deployment for configuring providers.
|
||||
- **Coder Agents User role** assigned to each user who needs to interact with Coder Agents.
|
||||
Owners can assign this from **Admin** > **Users**. See
|
||||
[Grant Coder Agents User](#step-2-grant-coder-agents-user) below.
|
||||
This role is granted **per organization**. Owners and organization admins can
|
||||
assign it from **Admin settings** > **Organizations** > _[your organization]_ >
|
||||
**Members**. See [Grant Coder Agents User](#step-2-grant-coder-agents-user)
|
||||
below.
|
||||
|
||||
## Step 1: Configure an LLM provider and model
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Configuring providers, models, and system prompts requires the
|
||||
> **Owner** role (Coder administrator). Non-admin users cannot access the
|
||||
> Admin panel or modify deployment-level Agents configuration.
|
||||
> admin Settings panel or modify deployment-level Agents configuration.
|
||||
|
||||
To configure Coder Agents:
|
||||
|
||||
1. Navigate to the **Agents** page in the Coder dashboard.
|
||||
1. Click **Admin** to open the configuration dialog.
|
||||
1. Under the **Providers** tab, select a provider, enter your API key, and
|
||||
save.
|
||||
1. Open **Settings** > **Manage Agents** and select the **Providers** tab.
|
||||
Pick a provider, enter your API key, and save.
|
||||
1. Switch to the **Models** tab, click **Add**, and configure at least one
|
||||
model with its identifier, display name, and context limit.
|
||||
1. Click the **star icon** next to a model to set it as the default.
|
||||
@@ -51,37 +52,62 @@ Detailed instructions for each provider and model option are in the
|
||||
|
||||
## Step 2: Grant Coder Agents User
|
||||
|
||||
The **Coder Agents User** role controls which users can interact with Coder Agents.
|
||||
Members do not have Coder Agents User by default.
|
||||
The **Coder Agents User** role controls which users can interact with Coder
|
||||
Agents. The role is assigned **per organization**, so a user must be granted
|
||||
it in each organization where they need access. Members do not have it by
|
||||
default.
|
||||
|
||||
Owners always have full access and do not need the role. Repeat the following steps for each user who needs access.
|
||||
|
||||
> [!NOTE]
|
||||
> Users who created conversations before this role was introduced are
|
||||
> automatically granted the role during upgrade.
|
||||
Owners always have full access and do not need the role. Repeat the following
|
||||
steps for each user who needs access in each organization.
|
||||
|
||||
**Dashboard (individual):**
|
||||
|
||||
1. Go to **Admin** > **Users** in the Coder dashboard.
|
||||
1. Click the roles icon next to the user you want to grant access to.
|
||||
1. Enable the **Coder Agents User** role and save.
|
||||
1. Open **Admin settings** > **Organizations** in the Coder dashboard, then
|
||||
select the organization where you want to grant access.
|
||||
1. The **Members** tab opens by default. Find the user in the table.
|
||||
1. Click the **Roles** cell for that user to open the role editor.
|
||||
1. Toggle on **Coder Agents User** and save.
|
||||
|
||||
**CLI (bulk):**
|
||||
> [!TIP]
|
||||
> If your deployment has multiple organizations, repeat this for each
|
||||
> organization where the user needs access.
|
||||
|
||||
You can also grant the role via CLI. For example, to grant the role to
|
||||
all active users at once:
|
||||
**CLI (bulk, per organization):**
|
||||
|
||||
Granting the role via CLI is org-scoped. The `edit-roles` command **replaces**
|
||||
the member's full set of org roles, so include every role you want them to
|
||||
keep. To grant `agents-access` to a single user while preserving their
|
||||
existing org roles:
|
||||
|
||||
```sh
|
||||
coder users list -o json \
|
||||
| jq -r '.[].username' \
|
||||
| while read u; do
|
||||
coder users edit-roles "$u" \
|
||||
--roles "$(coder users show "$u" -o json \
|
||||
| jq -r '[.roles[].name, "agents-access"] | unique | join(",")')" \
|
||||
--yes
|
||||
ORG="my-org"
|
||||
USER="alice"
|
||||
ROLES=$(coder organizations members list -O "$ORG" -o json \
|
||||
| jq -r --arg user "$USER" \
|
||||
'.[] | select(.username == $user) | [.roles[].name, "agents-access"]
|
||||
| unique | join(" ")')
|
||||
# shellcheck disable=SC2086
|
||||
coder organizations members edit-roles "$USER" -O "$ORG" $ROLES
|
||||
```
|
||||
|
||||
To grant the role to every member of an organization while preserving their
|
||||
existing roles:
|
||||
|
||||
```sh
|
||||
ORG="my-org"
|
||||
coder organizations members list -O "$ORG" -o json \
|
||||
| jq -c '.[] | {user_id, roles: [.roles[].name]}' \
|
||||
| while read -r row; do
|
||||
user_id=$(echo "$row" | jq -r '.user_id')
|
||||
roles=$(echo "$row" | jq -r '(.roles + ["agents-access"]) | unique | join(" ")')
|
||||
# shellcheck disable=SC2086
|
||||
coder organizations members edit-roles "$user_id" -O "$ORG" $roles
|
||||
done
|
||||
```
|
||||
|
||||
You can also set the organization with the `CODER_ORGANIZATION` environment
|
||||
variable instead of `-O`.
|
||||
|
||||
## Step 3: Start your first Coder Agent
|
||||
|
||||
1. Go to the **Agents** page in the Coder dashboard.
|
||||
@@ -158,7 +184,8 @@ deployment. Use this to encode organizational conventions:
|
||||
- Required review processes before merging.
|
||||
- Any guardrails specific to your environment.
|
||||
|
||||
Configure the system prompt from the **Admin** dialog on the Agents page
|
||||
Configure the system prompt from **Agents** > **Settings** >
|
||||
**Manage Agents** > **Instructions**
|
||||
or via the API at `PUT /api/experimental/chats/config/system-prompt`.
|
||||
See [Platform Controls](./platform-controls/index.md) for details.
|
||||
|
||||
@@ -187,8 +214,8 @@ sub-agent delegation, and complex multi-step work can consume significant
|
||||
token volume. Consider:
|
||||
|
||||
- Starting with a single model to establish a cost baseline.
|
||||
- Setting per-model token pricing in the admin panel (Input Price, Output
|
||||
Price) to track spend.
|
||||
- Setting per-model token pricing under **Agents** > **Settings** >
|
||||
**Manage Agents** > **Models** (Input Price, Output Price) to track spend.
|
||||
- Monitoring provider dashboards for usage trends during the evaluation.
|
||||
|
||||
### Pilot with a small group
|
||||
|
||||
@@ -220,9 +220,9 @@ enterprise LLM proxies, self-hosted model endpoints, and internal gateways.
|
||||
Administrators can configure multiple providers simultaneously and set a default
|
||||
model. Developers select from enabled models when starting a chat.
|
||||
|
||||
<img src="../../images/guides/ai-agents/llm-providers.png" alt="Screenshot of the provider/model configuration admin panel">
|
||||
<img src="../../images/guides/ai-agents/llm-providers.png" alt="Screenshot of the provider/model configuration in the Agents settings">
|
||||
|
||||
<small>The model configuration panel in the Coder dashboard.</small>
|
||||
<small>The model configuration in the Agents settings panel.</small>
|
||||
|
||||
## Built-in tools
|
||||
|
||||
|
||||
@@ -32,15 +32,14 @@ models, internal gateways, or third-party proxies like LiteLLM.
|
||||
### Add a provider
|
||||
|
||||
1. Navigate to the **Agents** page in the Coder dashboard.
|
||||
1. Click **Admin** in the top bar to open the configuration dialog.
|
||||
1. Select the **Providers** tab.
|
||||
1. Open **Settings** > **Manage Agents** and select the **Providers** tab.
|
||||
1. Click the provider you want to configure.
|
||||
1. Enter the **API key** for the provider, if required.
|
||||
1. Optionally set a **Base URL** to override the default endpoint. This is
|
||||
useful for enterprise proxies, regional endpoints, or self-hosted models.
|
||||
1. Click **Save**.
|
||||
|
||||
<img src="../../images/guides/ai-agents/models-providers.png" alt="Screenshot of the providers list in the admin dialog">
|
||||
<img src="../../images/guides/ai-agents/models-providers.png" alt="Screenshot of the providers list in the Agents settings">
|
||||
|
||||
<small>The providers list shows all supported providers and their configuration
|
||||
status.</small>
|
||||
@@ -130,7 +129,7 @@ generation parameters, and provider-specific options.
|
||||
|
||||
### Add a model
|
||||
|
||||
1. Open the **Admin** dialog and select the **Models** tab.
|
||||
1. Open **Settings** > **Manage Agents** and select the **Models** tab.
|
||||
1. Click **Add** and select the provider for the new model.
|
||||
1. Enter the **Model Identifier** — the exact model string your provider
|
||||
expects (e.g., `claude-opus-4-6`, `gpt-5.3-codex`).
|
||||
@@ -141,7 +140,7 @@ generation parameters, and provider-specific options.
|
||||
1. Configure any provider-specific options (see below).
|
||||
1. Click **Save**.
|
||||
|
||||
<img src="../../images/guides/ai-agents/models-list.png" alt="Screenshot of the models list in the admin dialog">
|
||||
<img src="../../images/guides/ai-agents/models-list.png" alt="Screenshot of the models list in the Agents settings">
|
||||
|
||||
<small>The models list shows all configured models grouped by provider.</small>
|
||||
|
||||
@@ -247,6 +246,42 @@ Developers cannot add their own providers or models. If no models are
|
||||
configured, the chat interface displays a message directing developers to
|
||||
contact an administrator.
|
||||
|
||||
## Model overrides
|
||||
|
||||
Beyond the chat-level model picker, Coder Agents supports two override
|
||||
layers:
|
||||
|
||||
- **Subagent overrides** (admin, deployment-wide): Pin specific subagent
|
||||
contexts to a particular model. Configure them at **Agents** >
|
||||
**Settings** > **Manage Agents** > **Agents**.
|
||||
- **Personal overrides** (per user, opt-in by admin): Let users override
|
||||
the model for their own root chats and delegated subagents. Admins
|
||||
enable the toggle on the same admin page; once on, each user sees an
|
||||
**Agents** tab in their personal **Agents** > **Settings**.
|
||||
|
||||
The configurable contexts:
|
||||
|
||||
| Context | Layer | Applies to |
|
||||
|----------------------|--------------|--------------------------------------------------------------------------------|
|
||||
| **General** | Admin + user | Write-capable subagents (`spawn_agent` with `type=general` or `computer_use`). |
|
||||
| **Explore** | Admin + user | Read-only subagents (`spawn_agent` with `type=explore`). |
|
||||
| **Title generation** | Admin only | Automatic title generation for new chats. |
|
||||
| **Root** | User only | The user's own root chats. |
|
||||
|
||||
Resolution order, evaluated per chat or subagent:
|
||||
|
||||
1. Personal override (when the admin gate is on and a model is set).
|
||||
1. Admin subagent override.
|
||||
1. The chat's selected model (or the deployment default for new chats).
|
||||
|
||||
If a referenced model is later disabled or deleted, that layer is skipped
|
||||
and resolution falls through to the next.
|
||||
|
||||
> [!NOTE]
|
||||
> Both override layers are experimental and may change between releases.
|
||||
> The same values are available through the experimental chat
|
||||
> configuration API under `/api/experimental/chats/config/`.
|
||||
|
||||
## User API keys (BYOK)
|
||||
|
||||
When an administrator enables **Allow user API keys** on a provider,
|
||||
|
||||
@@ -0,0 +1,102 @@
|
||||
# Experiments
|
||||
|
||||
The **Experiments** tab under **Agents** > **Settings** > **Manage Agents**
|
||||
is where administrators opt in to features that are still iterating. The
|
||||
behavior, configuration surface, and APIs documented here may change between
|
||||
releases without notice.
|
||||
|
||||
> [!NOTE]
|
||||
> Everything in this page is experimental. Pin a release before broad rollout
|
||||
> and review the release notes before upgrading.
|
||||
|
||||
## Virtual desktop
|
||||
|
||||
Lets agents drive a graphical desktop inside the workspace through
|
||||
`spawn_agent` with `type=computer_use` (screenshots, mouse, keyboard).
|
||||
|
||||
To enable, toggle **Virtual Desktop** on, then choose a **Computer use
|
||||
provider** (Anthropic or OpenAI). It also requires:
|
||||
|
||||
- The [portabledesktop](https://registry.coder.com/modules/coder/portabledesktop)
|
||||
module installed in the workspace template.
|
||||
- An API key for the selected provider configured under the **Providers**
|
||||
tab.
|
||||
|
||||
The Anthropic and OpenAI computer-use models are fixed by Coder per provider
|
||||
and are not selectable from this UI. Anthropic is the default when no
|
||||
provider is set.
|
||||
|
||||
## Advisor
|
||||
|
||||
Lets a root agent pause its current turn and request strategic guidance from
|
||||
a separate, single-step model call. The advisor sees recent conversation
|
||||
context, runs without any tools, and returns concise advice for the parent
|
||||
agent rather than the end user. While active, it is the only tool the parent
|
||||
can call for that turn.
|
||||
|
||||
Useful for planning ambiguity, architectural tradeoffs, debugging strategy
|
||||
after repeated failures, or risk reduction before a destructive operation.
|
||||
|
||||
| Field | Default | Notes |
|
||||
|-------------------|----------------------|-------------------------------------------------------------------------------------------------------------------------|
|
||||
| Advisor (toggle) | Off | Master switch. When off, the advisor tool is not attached to new chats. |
|
||||
| Max uses per run | `0` (unlimited) | Caps how many times an agent can call the advisor in a single chat run. Must be a non-negative integer. |
|
||||
| Max output tokens | `0` (server default) | Caps the advisor model's response length. `0` uses the server default of 16,384 tokens. Must be a non-negative integer. |
|
||||
| Reasoning effort | Use chat model | One of unset, `low`, `medium`, or `high`. Unset delegates to the underlying model's default. |
|
||||
| Advisor model | Use chat model | Optional dedicated chat model config for the advisor. When unset, the advisor reuses the parent chat's model. |
|
||||
|
||||
The advisor is not available in plan mode or to subagents. Failed advisor
|
||||
invocations refund the per-run budget, and advisor calls are not metered
|
||||
against the parent chat's usage limit.
|
||||
|
||||
The same configuration is available at:
|
||||
|
||||
- `GET /api/experimental/chats/config/advisor`
|
||||
- `PUT /api/experimental/chats/config/advisor`
|
||||
|
||||
## Chat debug logging
|
||||
|
||||
Records a detailed trace of each chat turn for troubleshooting: the
|
||||
normalized request sent to the LLM provider, the full response, token usage,
|
||||
retry attempts, and errors.
|
||||
|
||||
Off by default. Three layers control whether it runs for a given chat:
|
||||
|
||||
1. **Deployment override.** Setting `CODER_CHAT_DEBUG_LOGGING_ENABLED=true`
|
||||
(or `--chat-debug-logging-enabled` at server start) forces debug logging
|
||||
on for every chat. The runtime admin and user toggles become read-only.
|
||||
1. **Runtime admin gate.** With the deployment override unset, the
|
||||
*Let users record chat debug logs* toggle decides whether users can opt
|
||||
in. Configure it at
|
||||
`GET/PUT /api/experimental/chats/config/debug-logging`.
|
||||
1. **Per-user toggle.** Users with the admin gate enabled can turn debug
|
||||
logging on for their own chats from **Agents** > **Settings** > **General**
|
||||
under *Record debug logs for my chats*. The endpoint
|
||||
`PUT /api/experimental/chats/config/user-debug-logging` returns
|
||||
`409 Conflict` if the deployment override is active and `403 Forbidden`
|
||||
if the admin has not enabled user opt-in.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Debug logs may contain sensitive content from prompts, responses, tool
|
||||
> calls, and errors. Treat them with the same care as conversation history.
|
||||
> Only the chat owner (or a user with read access to the chat) can fetch a
|
||||
> chat's debug runs through the API. Administrators do not get blanket
|
||||
> access to all users' debug data.
|
||||
|
||||
When debug logging is active for a chat, a **Debug** tab appears in the
|
||||
right panel of the Agents page (alongside Git, Terminal, and Desktop) for
|
||||
that chat's owner. The tab lists recent debug runs and lets you expand a run
|
||||
into its per-step request, response, token usage, retry attempts, errors,
|
||||
and policy metadata.
|
||||
|
||||
The same data is available through the experimental API:
|
||||
|
||||
- `GET /api/experimental/chats/{chat}/runs` lists the most recent runs for a
|
||||
chat (up to 100, newest first).
|
||||
- `GET /api/experimental/chats/{chat}/runs/{debugRun}` returns a single run
|
||||
with all of its steps, including normalized request and response bodies.
|
||||
|
||||
Debug runs are stored alongside the chat and are removed when the parent
|
||||
conversation is deleted (manually, by retention, or by chat purge). See
|
||||
[Data Retention](./chat-retention.md) for the conversation retention
|
||||
controls.
|
||||
@@ -2,9 +2,9 @@
|
||||
|
||||
Coder Agents leverages your existing
|
||||
[external authentication](../../../admin/external-auth/index.md) configuration
|
||||
to power the in-chat diff viewer and [PR Insights](./pr-insights.md).
|
||||
to power the in-chat diff viewer.
|
||||
Self-hosted GitHub Enterprise deployments require one additional setting
|
||||
(`API_BASE_URL`) for these features to work.
|
||||
(`API_BASE_URL`) for this feature to work.
|
||||
|
||||
> [!NOTE]
|
||||
> Only `github` type external auth providers are supported today.
|
||||
@@ -30,8 +30,8 @@ CODER_EXTERNAL_AUTH_0_REGEX=github\.example\.com
|
||||
|
||||
Without `API_BASE_URL`, Coder defaults to `https://api.github.com`. Clone
|
||||
and push still work (they use `AUTH_URL` and `TOKEN_URL` directly), but
|
||||
the diff viewer and PR Insights silently fail because Coder builds its
|
||||
URL-matching patterns from the API base URL.
|
||||
the diff viewer silently fails because Coder builds its URL-matching
|
||||
patterns from the API base URL.
|
||||
|
||||
> [!NOTE]
|
||||
> If you have both a `github.com` and a GHE external auth config, only the
|
||||
@@ -39,10 +39,10 @@ URL-matching patterns from the API base URL.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Diffs or PR data not appearing on GHE
|
||||
### Diffs not appearing on GHE
|
||||
|
||||
Add `API_BASE_URL` to your GHE external auth config and restart Coder.
|
||||
Data should appear within a couple of minutes.
|
||||
Diffs should appear within a couple of minutes.
|
||||
|
||||
### Users not seeing diffs
|
||||
|
||||
|
||||
@@ -49,11 +49,12 @@ See [Models](../models.md) for setup instructions.
|
||||
### System prompt
|
||||
|
||||
Administrators can set a system prompt that applies to all agent sessions. This
|
||||
is useful for establishing organizational conventions — coding standards,
|
||||
is useful for establishing organizational conventions: coding standards,
|
||||
commit message formats, preferred libraries, or repository-specific context.
|
||||
|
||||
The system prompt configuration is only accessible to administrators in the
|
||||
dashboard. Developers do not see or interact with it.
|
||||
This setting is available under **Agents** > **Settings** >
|
||||
**Manage Agents** > **Instructions** and is only accessible to
|
||||
administrators. Developers do not see or interact with it.
|
||||
|
||||
### Plan mode instructions
|
||||
|
||||
@@ -62,8 +63,8 @@ enters plan mode. These instructions supplement the built-in planning behavior
|
||||
and are useful for organization-specific planning requirements such as required
|
||||
plan sections, approval checkpoints, or review workflows.
|
||||
|
||||
This setting is available under **Agents** > **Settings** > **Behavior**.
|
||||
Developers do not edit it directly.
|
||||
This setting is available under **Agents** > **Settings** >
|
||||
**Manage Agents** > **Instructions**. Developers do not edit it directly.
|
||||
|
||||
The same value is exposed over the experimental chat configuration API:
|
||||
|
||||
@@ -81,13 +82,14 @@ Python backend services in the payments repo" — platform teams can guide the
|
||||
agent toward the correct infrastructure without requiring developers to
|
||||
understand template selection at all.
|
||||
|
||||
Administrators can also restrict which templates are available to agents using
|
||||
the template allowlist in **Agents** > **Settings** > **Templates**. When the
|
||||
allowlist is configured, the agent can only see and provision workspaces from
|
||||
the selected templates. When the allowlist is empty, all templates are
|
||||
available. This is separate from what developers see when manually creating
|
||||
workspaces, so you can apply stricter policies to agent-created workspaces
|
||||
without affecting the manual workspace experience.
|
||||
Administrators can also restrict which templates are available to agents
|
||||
using the template allowlist at **Agents** > **Settings** >
|
||||
**Manage Agents** > **Templates**. When the allowlist is configured, the
|
||||
agent can only see and provision workspaces from the selected templates.
|
||||
When the allowlist is empty, all templates are available. This is separate
|
||||
from what developers see when manually creating workspaces, so you can apply
|
||||
stricter policies to agent-created workspaces without affecting the manual
|
||||
workspace experience.
|
||||
|
||||
See [Template Optimization](./template-optimization.md) for best practices on writing
|
||||
discoverable descriptions, restricting template visibility, configuring network
|
||||
@@ -104,31 +106,16 @@ opt-out, or opt-in for each chat.
|
||||
|
||||
See [MCP Servers](./mcp-servers.md) for configuration details.
|
||||
|
||||
### Virtual desktop
|
||||
|
||||
Administrators can enable a virtual desktop within agent workspaces.
|
||||
When enabled, agents can use `spawn_agent` with
|
||||
`type=computer_use` to interact with a
|
||||
desktop environment using screenshots, mouse, and keyboard input.
|
||||
|
||||
This setting is available under **Agents** > **Settings** > **Behavior**.
|
||||
It requires:
|
||||
|
||||
- The [portabledesktop](https://registry.coder.com/modules/coder/portabledesktop)
|
||||
module to be installed in the workspace template.
|
||||
- An Anthropic or OpenAI provider to be configured. Administrators select
|
||||
which provider agents use under the **Computer use provider** dropdown
|
||||
next to the virtual desktop toggle. Anthropic is the default.
|
||||
|
||||
### Workspace autostop fallback
|
||||
|
||||
Administrators can set a default autostop timer for agent-created workspaces
|
||||
that do not define one in their template. Template-defined autostop rules always
|
||||
take precedence. Active conversations extend the stop time automatically.
|
||||
|
||||
This setting is available under **Agents** > **Settings** > **Behavior**.
|
||||
The maximum configurable value is 30 days. When disabled, workspaces follow
|
||||
their template's autostop rules (or none, if the template does not define any).
|
||||
This setting is available under **Agents** > **Settings** >
|
||||
**Manage Agents** > **Lifecycle**. The maximum configurable value is 30
|
||||
days. When disabled, workspaces follow their template's autostop rules (or
|
||||
none, if the template does not define any).
|
||||
|
||||
### Spend management
|
||||
|
||||
@@ -142,27 +129,30 @@ See [Spend Management](./usage-insights.md) for details.
|
||||
### Git providers
|
||||
|
||||
Coder Agents leverages your existing
|
||||
[external authentication](../../../admin/external-auth/index.md) configuration to
|
||||
power the in-chat diff viewer and PR Insights. Self-hosted GitHub Enterprise
|
||||
deployments require additional configuration for these features.
|
||||
[external authentication](../../../admin/external-auth/index.md) configuration
|
||||
to power the in-chat diff viewer. Self-hosted GitHub Enterprise deployments
|
||||
require additional configuration for this feature.
|
||||
|
||||
See [Git Providers](./git-providers.md) for details.
|
||||
|
||||
### PR Insights
|
||||
|
||||
PR Insights tracks pull requests created by Coder Agents and surfaces
|
||||
analytics on PR activity, merge rates, and cost efficiency.
|
||||
|
||||
See [PR Insights](./pr-insights.md) for requirements and dashboard details.
|
||||
|
||||
### Data retention
|
||||
|
||||
Administrators can configure a retention period for archived conversations.
|
||||
When enabled, archived conversations and orphaned files older than the
|
||||
retention period are automatically purged. The default is 30 days.
|
||||
|
||||
This setting is available under **Agents** > **Settings** > **Behavior**.
|
||||
See [Data Retention](./chat-retention.md) for details.
|
||||
This setting is available under **Agents** > **Settings** >
|
||||
**Manage Agents** > **Lifecycle**. See [Data Retention](./chat-retention.md)
|
||||
for details.
|
||||
|
||||
### Experiments
|
||||
|
||||
Administrators can opt in to experimental features under **Agents** >
|
||||
**Settings** > **Manage Agents** > **Experiments**. Behavior, configuration
|
||||
surface, and APIs may change between releases.
|
||||
|
||||
See [Experiments](./experiments.md) for the current list of experiments, how
|
||||
to enable them, and the relevant API endpoints.
|
||||
|
||||
## Where we are headed
|
||||
|
||||
|
||||
@@ -5,11 +5,12 @@ for agent chat sessions. Configured servers are injected into or offered to
|
||||
users during chat depending on the availability policy.
|
||||
|
||||
This is an admin-only feature accessible at **Agents** > **Settings** >
|
||||
**MCP Servers**.
|
||||
**Manage Agents** > **MCP Servers**.
|
||||
|
||||
## Add an MCP server
|
||||
|
||||
1. Navigate to **Agents** > **Settings** > **MCP Servers**.
|
||||
1. Navigate to **Agents** > **Settings** > **Manage Agents** >
|
||||
**MCP Servers**.
|
||||
1. Click **Add**.
|
||||
1. Fill in the configuration fields described below.
|
||||
1. Click **Save**.
|
||||
|
||||
@@ -1,61 +0,0 @@
|
||||
# PR Insights
|
||||
|
||||
PR Insights tracks pull requests created by Coder Agents and surfaces
|
||||
analytics on PR activity, merge rates, and cost efficiency. The dashboard
|
||||
(under **Agents** > **Insights** > **PR Insights**) shows merge rates,
|
||||
cost per merged PR, per-model breakdowns, and individual PR status.
|
||||
|
||||
## How it works
|
||||
|
||||
A background worker monitors active agent chats for git activity. When an
|
||||
agent pushes a branch or creates a pull request, the worker resolves the git
|
||||
remote origin against configured external auth providers.
|
||||
|
||||
The worker uses the matched provider's API to fetch PR metadata: status, diff
|
||||
stats, review state, and merge outcome.
|
||||
|
||||
> [!NOTE]
|
||||
> Only `github` type external auth providers are supported for PR Insights
|
||||
> today.
|
||||
|
||||
## Requirements
|
||||
|
||||
For PR data to appear in analytics, all of the following must be true:
|
||||
|
||||
1. **External auth is configured for your git host** — The external auth
|
||||
config must have `type` set to `github` with a regex matching your
|
||||
repository URLs. See
|
||||
[External Authentication](../../../admin/external-auth/index.md).
|
||||
|
||||
1. **Users have linked their external auth** — The user who ran the agent
|
||||
task must have authenticated with the relevant external auth provider.
|
||||
Without a linked token, the worker cannot fetch PR data and retries on a
|
||||
backoff schedule.
|
||||
|
||||
1. **The agent reported a git reference** — The agent must push to a branch
|
||||
with a configured remote origin. If no branch or remote origin is
|
||||
reported, the worker skips the chat.
|
||||
|
||||
For self-hosted GitHub Enterprise deployments, additional configuration is
|
||||
required. See [Git Providers](./git-providers.md#github-enterprise-configuration).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### PRs not appearing
|
||||
|
||||
Verify the user has linked their external auth. Check Coder logs for gitsync
|
||||
warnings like `no provider for origin` or token resolution errors. For GitHub
|
||||
Enterprise, confirm that `API_BASE_URL` is set — see
|
||||
[Git Providers](./git-providers.md#troubleshooting).
|
||||
|
||||
### Only github.com PRs appear
|
||||
|
||||
If you have multiple external auth configs (e.g., `github.com` + GHE),
|
||||
ensure the GHE config has `API_BASE_URL` set. The `github.com` config works
|
||||
without it because the default is already correct.
|
||||
|
||||
### PR data delayed
|
||||
|
||||
The background worker polls on a ~10 second interval. New PRs typically
|
||||
appear within a couple of minutes. If a token refresh fails, the worker
|
||||
backs off for 10 minutes before retrying.
|
||||
@@ -20,7 +20,7 @@ template allowlist.
|
||||
|
||||
To configure the allowlist:
|
||||
|
||||
1. Navigate to **Agents** > **Settings** > **Templates**.
|
||||
1. Navigate to **Agents** > **Settings** > **Manage Agents** > **Templates**.
|
||||
2. Select the templates you want agents to be able to use.
|
||||
3. Click **Save**.
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ spend: usage limits and cost tracking.
|
||||
|
||||
## Usage limits
|
||||
|
||||
Navigate to **Agents** > **Settings** > **Spend**.
|
||||
Navigate to **Agents** > **Settings** > **Manage Agents** > **Spend**.
|
||||
|
||||
Usage limits cap how much each user can spend on LLM usage within a rolling
|
||||
time period. When enabled, the system checks the user's current spend before
|
||||
@@ -53,7 +53,7 @@ their effective limit, current spend, and when the current period resets.
|
||||
|
||||
## Cost tracking
|
||||
|
||||
Navigate to **Agents** > **Settings** > **Spend**.
|
||||
Navigate to **Agents** > **Settings** > **Manage Agents** > **Spend**.
|
||||
|
||||
This view shows deployment-wide LLM chat costs with per-user drill-down.
|
||||
|
||||
|
||||
@@ -69,8 +69,8 @@ variables (e.g. `ANTHROPIC_API_KEY`). With Coder Agents, credentials are
|
||||
configured once in the control plane:
|
||||
|
||||
1. Navigate to the **Agents** page in the Coder dashboard.
|
||||
1. Click **Admin** > **Providers**, select a provider, enter your API key,
|
||||
and save.
|
||||
1. Open **Settings** > **Manage Agents** > **Providers**, pick a provider,
|
||||
enter your API key, and save.
|
||||
1. Under **Models**, add at least one model and set it as the default.
|
||||
|
||||
You no longer pass API keys in template variables or workspace environment. See https://coder.com/docs/ai-coder/agents/getting-started for more information.
|
||||
|
||||
+7
-7
@@ -1259,16 +1259,10 @@
|
||||
},
|
||||
{
|
||||
"title": "Git Providers",
|
||||
"description": "Git provider configuration for the diff viewer and PR Insights",
|
||||
"description": "Git provider configuration for the in-chat diff viewer",
|
||||
"path": "./ai-coder/agents/platform-controls/git-providers.md",
|
||||
"state": ["beta"]
|
||||
},
|
||||
{
|
||||
"title": "PR Insights",
|
||||
"description": "Pull request analytics for Coder Agents",
|
||||
"path": "./ai-coder/agents/platform-controls/pr-insights.md",
|
||||
"state": ["beta"]
|
||||
},
|
||||
{
|
||||
"title": "Data Retention",
|
||||
"description": "Automatic cleanup of old conversation data",
|
||||
@@ -1280,6 +1274,12 @@
|
||||
"description": "Automatic archiving of inactive conversations",
|
||||
"path": "./ai-coder/agents/platform-controls/chat-auto-archive.md",
|
||||
"state": ["beta"]
|
||||
},
|
||||
{
|
||||
"title": "Experiments",
|
||||
"description": "Experimental Coder Agents features admins can opt in to: virtual desktop, advisor, and chat debug logging",
|
||||
"path": "./ai-coder/agents/platform-controls/experiments.md",
|
||||
"state": ["beta"]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user