diff --git a/docs/ai-coder/agents/architecture.md b/docs/ai-coder/agents/architecture.md index 8b12f98663..11501b0b54 100644 --- a/docs/ai-coder/agents/architecture.md +++ b/docs/ai-coder/agents/architecture.md @@ -180,6 +180,15 @@ configuration set by an administrator. |--------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | `web_search` | Searches the internet for up-to-date information. Available when web search is enabled for the configured Anthropic, OpenAI, or Google provider. | +### Workspace extension tools + +These tools are conditionally available based on the workspace contents. + +| Tool | What it does | +|-------------------|--------------------------------------------------------------------------------------------------------------------------------| +| `read_skill` | Reads the instructions for a workspace skill by name. Available when the workspace has skills discovered in `.agents/skills/`. | +| `read_skill_file` | Reads a supporting file from a skill's directory. | + ## What runs where Understanding the split between the control plane and the workspace is central diff --git a/docs/ai-coder/agents/index.md b/docs/ai-coder/agents/index.md index b59338e8a9..3b047208c7 100644 --- a/docs/ai-coder/agents/index.md +++ b/docs/ai-coder/agents/index.md @@ -232,35 +232,43 @@ model. Developers select from enabled models when starting a chat. The agent has access to a set of workspace tools that it uses to accomplish tasks: -| Tool | Description | -|--------------------|---------------------------------------------------------| -| `list_templates` | Browse available workspace templates | -| `read_template` | Get template details and configurable parameters | -| `create_workspace` | Create a workspace from a template | -| `start_workspace` | Start a stopped workspace for the current chat | -| `propose_plan` | Present a Markdown plan file for user review | -| `read_file` | Read file contents from the workspace | -| `write_file` | Write a file to the workspace | -| `edit_files` | Perform search-and-replace edits across files | -| `execute` | Run shell commands in the workspace | -| `process_output` | Retrieve output from a background process | -| `process_list` | List all tracked processes in the workspace | -| `process_signal` | Send a signal (terminate/kill) to a tracked process | -| `spawn_agent` | Delegate a task to a sub-agent running in parallel | -| `wait_agent` | Wait for a sub-agent to complete and collect its result | -| `message_agent` | Send a follow-up message to a running sub-agent | -| `close_agent` | Stop a running sub-agent | -| `web_search` | Search the internet (provider-native, when enabled) | +| Tool | Description | +|----------------------------|--------------------------------------------------------------------------| +| `list_templates` | Browse available workspace templates | +| `read_template` | Get template details and configurable parameters | +| `create_workspace` | Create a workspace from a template | +| `start_workspace` | Start a stopped workspace for the current chat | +| `propose_plan` | Present a Markdown plan file for user review | +| `read_file` | Read file contents from the workspace | +| `write_file` | Write a file to the workspace | +| `edit_files` | Perform search-and-replace edits across files | +| `execute` | Run shell commands in the workspace | +| `process_output` | Retrieve output from a background process | +| `process_list` | List all tracked processes in the workspace | +| `process_signal` | Send a signal (terminate/kill) to a tracked process | +| `spawn_agent` | Delegate a task to a sub-agent running in parallel | +| `wait_agent` | Wait for a sub-agent to complete and collect its result | +| `message_agent` | Send a follow-up message to a running sub-agent | +| `close_agent` | Stop a running sub-agent | +| `spawn_computer_use_agent` | Spawn a sub-agent with desktop interaction (screenshot, mouse, keyboard) | +| `read_skill` | Read the instructions for a workspace skill by name | +| `read_skill_file` | Read a supporting file from a skill's directory | +| `web_search` | Search the internet (provider-native, when enabled) | These tools connect to the workspace over the same secure connection used for web terminals and IDE access. No additional ports or services are required in the workspace. Platform tools (`list_templates`, `read_template`, `create_workspace`, -`start_workspace`, `propose_plan`) and orchestration tools (`spawn_agent`) -are only available to root chats. Sub-agents do -not have access to these tools and cannot create workspaces or spawn further -sub-agents. +`start_workspace`, `propose_plan`) and orchestration tools (`spawn_agent`, +`wait_agent`, `message_agent`, `close_agent`, `spawn_computer_use_agent`) +are only available to root chats. Sub-agents do not have access to these +tools and cannot create workspaces or spawn further sub-agents. + +`spawn_computer_use_agent` additionally requires an Anthropic provider and +the virtual desktop feature to be enabled by an administrator. +`read_skill` and `read_skill_file` are available when the workspace contains +skills in its `.agents/skills/` directory. ## Comparison to Coder Tasks diff --git a/docs/ai-coder/agents/models.md b/docs/ai-coder/agents/models.md index be5a3579fe..3ffaa7bc83 100644 --- a/docs/ai-coder/agents/models.md +++ b/docs/ai-coder/agents/models.md @@ -1,10 +1,13 @@ # Models Administrators configure LLM providers and models from the Coder dashboard. -These are deployment-wide settings — developers do not manage API keys or -provider configuration. They select from the set of models that an administrator +Providers, models, and API keys are deployment-wide settings managed by +platform teams. Developers select from the set of models that an administrator has enabled. +Optionally, administrators can allow developers to supply their own API keys +for specific providers. See [User API keys](#user-api-keys-byok) below. + ## Providers Each LLM provider has a type, an API key, and an optional base URL override. @@ -57,6 +60,38 @@ access to LLM providers. See [Architecture](./architecture.md#no-api-keys-in-workspaces) for details on this security model. +### Key policy + +Each provider has three policy flags that control how API keys are sourced: + +| Setting | Default | Description | +|-------------------------|---------|-----------------------------------------------------------------------------------------------------| +| Central API key | On | The provider uses a deployment-managed API key entered by an administrator. | +| Allow user API keys | Off | Developers may supply their own API key for this provider. | +| Central key as fallback | Off | When user keys are allowed, fall back to the central key if a developer has not set a personal key. | + +At least one credential source must be enabled. These settings appear in the +provider configuration form under **Key policy**. + +The interaction between these flags determines whether a provider is available +to a given developer: + +| Central key | User keys allowed | Fallback | Developer has key | Result | +|-------------|-------------------|----------|-------------------|----------------------| +| On | Off | — | — | Uses central key | +| Off | On | — | Yes | Uses developer's key | +| Off | On | — | No | Unavailable | +| On | On | Off | Yes | Uses developer's key | +| On | On | Off | No | Unavailable | +| On | On | On | Yes | Uses developer's key | +| On | On | On | No | Uses central key | + +When a developer's personal key is present, it always takes precedence over +the central key. When user keys are required and fallback is disabled, +the provider is unavailable to developers who have not saved a personal key — +even if a central key exists. This is intentional: it enforces that each +developer authenticates with their own credentials. + ## Models Each model belongs to a provider and has its own configuration for context limits, @@ -132,11 +167,11 @@ fields appear dynamically in the admin UI when you select a provider. #### OpenAI -| Option | Description | -|-----------------------|---------------------------------------------------------------------------------------------------| -| Reasoning Effort | How much effort the model spends reasoning (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`). | -| Max Completion Tokens | Cap on completion tokens for reasoning models. | -| Parallel Tool Calls | Whether the model can call multiple tools at once. | +| Option | Description | +|-----------------------|-------------------------------------------------------------------------------------------| +| Reasoning Effort | How much effort the model spends reasoning (`minimal`, `low`, `medium`, `high`, `xhigh`). | +| Max Completion Tokens | Cap on completion tokens for reasoning models. | +| Parallel Tool Calls | Whether the model can call multiple tools at once. | #### Google @@ -147,10 +182,10 @@ fields appear dynamically in the admin UI when you select a provider. #### OpenRouter -| Option | Description | -|-------------------|-------------------------------------------------------------------------------| -| Reasoning Enabled | Enable extended reasoning mode. | -| Reasoning Effort | Reasoning effort level (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`). | +| Option | Description | +|-------------------|---------------------------------------------------| +| Reasoning Enabled | Enable extended reasoning mode. | +| Reasoning Effort | Reasoning effort level (`low`, `medium`, `high`). | #### Vercel AI Gateway @@ -176,10 +211,49 @@ The model selector uses the following precedence to pre-select a model: 1. **Admin-designated default** — the model marked with the star icon. 1. **First available model** — if no default is set and no history exists. -Developers cannot add their own providers, models, or API keys. If no models -are configured, the chat interface displays a message directing developers to +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. +## User API keys (BYOK) + +When an administrator enables **Allow user API keys** on a provider, +developers can supply their own API key from the Agents settings page. + +### Managing personal API keys + +1. Navigate to the **Agents** page in the Coder dashboard. +1. Open **Settings** and select the **API Keys** tab. +1. Each provider that allows user keys is listed with a status indicator: + - **Key saved** — your personal key is active and will be used for requests. + - **Using shared key** — no personal key set, but the central deployment + key is available as a fallback. + - **No key** — you must add a personal key before you can use this provider. +1. Enter your API key and click **Save**. + +Personal API keys are encrypted at rest using the same database encryption +as deployment-managed keys. The dashboard never displays a saved key — only +whether one is set. + +### How key selection works + +When you start a chat, the control plane resolves which API key to use for +each provider: + +1. If you have a personal key for the provider, it is used. +1. If you do not have a personal key and central key fallback is enabled, + the deployment-managed key is used. +1. If you do not have a personal key and fallback is disabled, the provider + is unavailable to you. Models from that provider will not appear in the + model selector. + +### Removing a personal key + +Click **Remove** on the provider card in the API Keys settings tab. If +central key fallback is enabled, subsequent requests will use the shared +deployment key. If fallback is disabled, the provider becomes unavailable +until you add a new personal key. + ## Using an LLM proxy Organizations that route LLM traffic through a centralized proxy — such as diff --git a/docs/ai-coder/agents/chat-retention.md b/docs/ai-coder/agents/platform-controls/chat-retention.md similarity index 88% rename from docs/ai-coder/agents/chat-retention.md rename to docs/ai-coder/agents/platform-controls/chat-retention.md index a14c777d89..be30f46459 100644 --- a/docs/ai-coder/agents/chat-retention.md +++ b/docs/ai-coder/agents/platform-controls/chat-retention.md @@ -17,8 +17,8 @@ deleted. Both operations run in batches of 1,000 rows per cycle. ## Configuration -Navigate to **Deployment Settings** > **Agents** > **Behavior** to configure -the conversation retention period. The default is 30 days. Use the toggle to +Navigate to the **Agents** page, open **Settings**, and select the **Behavior** +tab to configure the conversation retention period. The default is 30 days. Use the toggle to disable retention entirely. The retention period is stored as the `agents_chat_retention_days` key in the @@ -37,8 +37,3 @@ The retention period is stored as the `agents_chat_retention_days` key in the If a user unarchives a conversation whose files were purged, stale file references are automatically cleaned up by FK cascades. The conversation remains usable but previously attached files are no longer available. - -## Related links - -- [Coder Agents](./index.md) -- [Data Retention](../../admin/setup/data-retention.md) diff --git a/docs/ai-coder/agents/platform-controls/index.md b/docs/ai-coder/agents/platform-controls/index.md index 4972f75104..fba1c8dc66 100644 --- a/docs/ai-coder/agents/platform-controls/index.md +++ b/docs/ai-coder/agents/platform-controls/index.md @@ -11,11 +11,12 @@ This means: - **All agent configuration is admin-level.** Providers, models, system prompts, and tool permissions are set by platform teams from the control plane. These are not user preferences — they are deployment-wide policies. -- **Developers never need to configure anything.** A developer just describes - the work they want done. They do not need to pick a provider, enter an API - key, or write a system prompt — the platform team has already set all of - that up. The goal is not to restrict developers, but to make configuration - unnecessary for a great experience. +- **Developers never need to configure anything by default.** A developer just + describes the work they want done. They do not need to pick a provider or + write a system prompt — the platform team has already set all of that up. + When a platform team enables user API keys for a provider, developers may + optionally supply their own key — but this is an opt-in policy decision, not + a requirement. - **Enforcement, not defaults.** Settings configured by administrators are enforced server-side. Developers cannot override them. This is a deliberate distinction — a setting that a user can change is a preference, not a policy. @@ -36,8 +37,12 @@ self-hosted models), and per-model parameters like context limits, thinking budgets, and reasoning effort. Developers select from the set of models an administrator has enabled. They -cannot add their own providers, supply their own API keys, or access models that -have not been explicitly configured. +cannot add their own providers or access models that have not been explicitly +configured. + +When an administrator enables user API keys on a provider, developers can +supply their own key from the Agents settings page. See +[User API keys (BYOK)](../models.md#user-api-keys-byok) for details. See [Models](../models.md) for setup instructions. @@ -84,6 +89,30 @@ 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_computer_use_agent` 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 provider to be configured (computer use is an Anthropic + capability). + +### 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). + ### Usage limits and analytics Administrators can set spend limits to cap LLM usage per user within a rolling @@ -93,10 +122,19 @@ breakdowns. See [Usage & Analytics](./usage-insights.md) for 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. + ## Where we are headed The controls above cover providers, models, system prompts, templates, MCP -servers, and usage limits. We are continuing to invest in platform controls +servers, usage limits, and data retention. We are continuing to invest in platform controls based on what we hear from customers deploying agents in regulated and enterprise environments. diff --git a/docs/manifest.json b/docs/manifest.json index b5334195fe..b140ce4d1c 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1250,6 +1250,12 @@ "description": "Spend limits and cost tracking for Coder Agents", "path": "./ai-coder/agents/platform-controls/usage-insights.md", "state": ["early access"] + }, + { + "title": "Data Retention", + "description": "Automatic cleanup of old conversation data", + "path": "./ai-coder/agents/platform-controls/chat-retention.md", + "state": ["early access"] } ] }, @@ -1264,12 +1270,6 @@ "description": "Programmatic access to Coder Agents via the experimental Chats API", "path": "./ai-coder/agents/chats-api.md", "state": ["early access"] - }, - { - "title": "Chat Data Retention", - "description": "Automatic cleanup of old chat data", - "path": "./ai-coder/agents/chat-retention.md", - "state": ["early access"] } ] }