From e189f73cc041e4d015577eb2fcf94e622f158b05 Mon Sep 17 00:00:00 2001 From: Matt Vollmer Date: Tue, 5 May 2026 12:40:03 -0400 Subject: [PATCH] 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 > ` path; user-side tabs keep `Agents > Settings > `. - 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.
Decision log - 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 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.
PR generated with Coder Agents. --- docs/ai-coder/agents/architecture.md | 14 +-- docs/ai-coder/agents/getting-started.md | 85 ++++++++++----- docs/ai-coder/agents/index.md | 4 +- docs/ai-coder/agents/models.md | 45 +++++++- .../agents/platform-controls/experiments.md | 102 ++++++++++++++++++ .../agents/platform-controls/git-providers.md | 12 +-- .../agents/platform-controls/index.md | 76 ++++++------- .../agents/platform-controls/mcp-servers.md | 5 +- .../agents/platform-controls/pr-insights.md | 61 ----------- .../template-optimization.md | 2 +- .../platform-controls/usage-insights.md | 4 +- .../agents/tasks-to-chats-migration.md | 4 +- docs/manifest.json | 14 +-- 13 files changed, 261 insertions(+), 167 deletions(-) create mode 100644 docs/ai-coder/agents/platform-controls/experiments.md delete mode 100644 docs/ai-coder/agents/platform-controls/pr-insights.md diff --git a/docs/ai-coder/agents/architecture.md b/docs/ai-coder/agents/architecture.md index f2d65730f9..9d8c8e6ecf 100644 --- a/docs/ai-coder/agents/architecture.md +++ b/docs/ai-coder/agents/architecture.md @@ -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 diff --git a/docs/ai-coder/agents/getting-started.md b/docs/ai-coder/agents/getting-started.md index cd0a967234..e797b83883 100644 --- a/docs/ai-coder/agents/getting-started.md +++ b/docs/ai-coder/agents/getting-started.md @@ -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 diff --git a/docs/ai-coder/agents/index.md b/docs/ai-coder/agents/index.md index aa1bb2e6f4..886e7c7835 100644 --- a/docs/ai-coder/agents/index.md +++ b/docs/ai-coder/agents/index.md @@ -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. -Screenshot of the provider/model configuration admin panel +Screenshot of the provider/model configuration in the Agents settings -The model configuration panel in the Coder dashboard. +The model configuration in the Agents settings panel. ## Built-in tools diff --git a/docs/ai-coder/agents/models.md b/docs/ai-coder/agents/models.md index 2036f0b068..65bf35c695 100644 --- a/docs/ai-coder/agents/models.md +++ b/docs/ai-coder/agents/models.md @@ -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**. -Screenshot of the providers list in the admin dialog +Screenshot of the providers list in the Agents settings The providers list shows all supported providers and their configuration status. @@ -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**. -Screenshot of the models list in the admin dialog +Screenshot of the models list in the Agents settings The models list shows all configured models grouped by provider. @@ -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, diff --git a/docs/ai-coder/agents/platform-controls/experiments.md b/docs/ai-coder/agents/platform-controls/experiments.md new file mode 100644 index 0000000000..5c01312508 --- /dev/null +++ b/docs/ai-coder/agents/platform-controls/experiments.md @@ -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. diff --git a/docs/ai-coder/agents/platform-controls/git-providers.md b/docs/ai-coder/agents/platform-controls/git-providers.md index 6a7aef7212..65ea46f988 100644 --- a/docs/ai-coder/agents/platform-controls/git-providers.md +++ b/docs/ai-coder/agents/platform-controls/git-providers.md @@ -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 diff --git a/docs/ai-coder/agents/platform-controls/index.md b/docs/ai-coder/agents/platform-controls/index.md index f188c9f6ec..5911d66a83 100644 --- a/docs/ai-coder/agents/platform-controls/index.md +++ b/docs/ai-coder/agents/platform-controls/index.md @@ -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 diff --git a/docs/ai-coder/agents/platform-controls/mcp-servers.md b/docs/ai-coder/agents/platform-controls/mcp-servers.md index 7deefcb6a9..86e751625d 100644 --- a/docs/ai-coder/agents/platform-controls/mcp-servers.md +++ b/docs/ai-coder/agents/platform-controls/mcp-servers.md @@ -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**. diff --git a/docs/ai-coder/agents/platform-controls/pr-insights.md b/docs/ai-coder/agents/platform-controls/pr-insights.md deleted file mode 100644 index 9436569ed0..0000000000 --- a/docs/ai-coder/agents/platform-controls/pr-insights.md +++ /dev/null @@ -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. diff --git a/docs/ai-coder/agents/platform-controls/template-optimization.md b/docs/ai-coder/agents/platform-controls/template-optimization.md index 4e428f4744..350a5cf436 100644 --- a/docs/ai-coder/agents/platform-controls/template-optimization.md +++ b/docs/ai-coder/agents/platform-controls/template-optimization.md @@ -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**. diff --git a/docs/ai-coder/agents/platform-controls/usage-insights.md b/docs/ai-coder/agents/platform-controls/usage-insights.md index 7d56800e01..b6b2d1e5db 100644 --- a/docs/ai-coder/agents/platform-controls/usage-insights.md +++ b/docs/ai-coder/agents/platform-controls/usage-insights.md @@ -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. diff --git a/docs/ai-coder/agents/tasks-to-chats-migration.md b/docs/ai-coder/agents/tasks-to-chats-migration.md index ab78bf2d90..a00b1ef12b 100644 --- a/docs/ai-coder/agents/tasks-to-chats-migration.md +++ b/docs/ai-coder/agents/tasks-to-chats-migration.md @@ -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. diff --git a/docs/manifest.json b/docs/manifest.json index 5a7f00ae60..ae1c6d01c3 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -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"] } ] },