diff --git a/docs/ai-coder/agents/extending-agents.md b/docs/ai-coder/agents/extending-agents.md new file mode 100644 index 0000000000..6ce6fc097c --- /dev/null +++ b/docs/ai-coder/agents/extending-agents.md @@ -0,0 +1,130 @@ +# 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. + +## Skills + +Skills are structured, reusable instruction sets that the agent loads on +demand. They live in the workspace filesystem and are discovered +automatically when a chat attaches to a workspace. + +### How skills work + +Place skill directories under `.agents/skills/` relative to the workspace +working directory. Each directory contains a required `SKILL.md` file and +any supporting files the skill needs. + +On the first turn of a workspace-attached chat, the agent scans +`.agents/skills/` and builds an `` block in its system +prompt listing each skill's name and description. Only frontmatter is read +during discovery — the full skill content is loaded lazily when the agent +calls a tool. + +Two tools are registered when skills are present: + +| Tool | Parameters | Description | +|-------------------|----------------------------------|----------------------------------------------------------| +| `read_skill` | `name` (string) | Returns the SKILL.md body and a list of supporting files | +| `read_skill_file` | `name` (string), `path` (string) | Returns the content of a supporting file | + +### Directory structure + +```text +.agents/skills/ +├── deep-review/ +│ ├── SKILL.md +│ └── roles/ +│ ├── security-reviewer.md +│ └── concurrency-reviewer.md +├── pull-requests/ +│ └── SKILL.md +└── refine-plan/ + └── SKILL.md +``` + +### SKILL.md format + +Each `SKILL.md` starts with YAML frontmatter containing a `name` and an +optional `description`, followed by the full instructions in markdown: + +```markdown +--- +name: deep-review +description: "Multi-reviewer code review with domain-specific reviewers" +--- + +# Deep Review + +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. +- `SKILL.md` has a maximum size of 64 KB. +- Supporting files have a maximum size of 512 KB. Files exceeding the limit + are silently truncated. + +### Path safety + +`read_skill_file` rejects absolute paths, paths containing `..`, and +references to hidden files. All paths are resolved relative to the skill +directory. + +## 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. The agent discovers +these tools automatically when it connects to a workspace and registers +them alongside its built-in tools. + +### 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`: + +```json +{ + "mcpServers": { + "github": { + "command": "github-mcp-server", + "args": ["--token", "..."] + }, + "my-api": { + "type": "http", + "url": "http://localhost:8080/mcp", + "headers": { "Authorization": "Bearer ..." } + } + } +} +``` + +**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. + +### How discovery works + +The agent reads `.mcp.json` via the workspace agent connection on each chat +turn. Discovery uses a 5-second timeout. Servers that fail to +respond are skipped — partial success is acceptable. Empty results are not +cached because the MCP servers may still be starting. + +### Tool naming + +Tool names are prefixed with the server name as `serverName__toolName` to +avoid collisions between servers and with built-in tools. + +### Timeouts + +- **Discovery**: 5-second timeout. +- **Tool calls**: 60 seconds per invocation. diff --git a/docs/ai-coder/agents/platform-controls/index.md b/docs/ai-coder/agents/platform-controls/index.md index e3d4867acc..4972f75104 100644 --- a/docs/ai-coder/agents/platform-controls/index.md +++ b/docs/ai-coder/agents/platform-controls/index.md @@ -74,24 +74,31 @@ discoverable descriptions, restricting template visibility, configuring network boundaries, scoping credentials, and designing template parameters for agent use. +### MCP servers + +Administrators can register external MCP (Model Context Protocol) servers that +provide additional tools for agent chat sessions. This includes configuring +authentication, controlling which tools are exposed via allow/deny lists, and +setting availability policies that determine whether a server is mandatory, +opt-out, or opt-in for each chat. + +See [MCP Servers](./mcp-servers.md) for configuration details. + +### Usage limits and analytics + +Administrators can set spend limits to cap LLM usage per user within a rolling +time period, with per-user and per-group overrides. The cost tracking dashboard +provides visibility into per-user spending, token consumption, and per-model +breakdowns. + +See [Usage & Analytics](./usage-insights.md) for details. + ## Where we are headed -Coder Agents is in its early stages. The controls above — providers, models, -and system prompt — are what is available today. We are actively building -toward a broader set of platform controls based on what we are hearing from -customers deploying agents in regulated and enterprise environments. - -The areas we are investing in include: - -### Usage controls and analytics - -We plan to give platform teams visibility into how agents are being used across -the organization: token consumption per user, cost per PR, merge rates by model, -and average time from prompt to merged pull request. - -The goal is to let platform teams make data-driven decisions — like switching -the default model when analytics show one model produces higher merge rates — -rather than relying on anecdotal feedback from individual developers. +The controls above cover providers, models, system prompts, templates, MCP +servers, and usage limits. We are continuing to invest in platform controls +based on what we hear from customers deploying agents in regulated and +enterprise environments. ### Infrastructure-level enforcement @@ -107,13 +114,6 @@ Examples of what this looks like: providers. You can create templates that only permit access to your git provider and nothing else. -### Tool customization - -The agent ships with a standard set of tools (file read/write, shell execution, -sub-agents). We intend to let platform teams customize the available tool set — -adding organization-specific tools or restricting default ones — without -modifying agent source code. - ## Why we take this approach The common pattern in the industry today is that each developer installs and diff --git a/docs/ai-coder/agents/platform-controls/mcp-servers.md b/docs/ai-coder/agents/platform-controls/mcp-servers.md new file mode 100644 index 0000000000..0a00e38f85 --- /dev/null +++ b/docs/ai-coder/agents/platform-controls/mcp-servers.md @@ -0,0 +1,125 @@ +# MCP Servers + +Administrators can register external MCP servers that provide additional tools +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**. + +## Add an MCP server + +1. Navigate to **Agents** > **Settings** > **MCP Servers**. +1. Click **Add**. +1. Fill in the configuration fields described below. +1. Click **Save**. + +### Identity + +| Field | Required | Description | +|----------------|----------|---------------------------------------------------------------| +| `display_name` | Yes | Human-readable name shown to users in chat. | +| `slug` | Yes | URL-safe unique identifier, auto-generated from display name. | +| `description` | No | Brief summary of what the server provides. | +| `icon_url` | No | Emoji or image URL displayed alongside the server name. | + +### Connection + +| Field | Required | Description | +|-------------|----------|-------------------------------------------------| +| `url` | Yes | The MCP server endpoint URL. | +| `transport` | Yes | Transport protocol. `streamable_http` or `sse`. | + +### Availability + +| Field | Required | Description | +|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------| +| `enabled` | No | Master toggle. Disabled servers are hidden from non-admin users. | +| `availability` | Yes | Controls how the server appears in chat sessions. See [Availability policies](#availability-policies). | +| `model_intent` | No | When enabled, requires the model to describe each tool call's purpose in natural language, shown as a status label in the UI. | + +#### Availability policies + +| Policy | Behavior | +|---------------|--------------------------------------------------------| +| `force_on` | Always injected into every chat. Users cannot opt out. | +| `default_on` | Pre-selected in new chats. Users can opt out. | +| `default_off` | Available in the server list but users must opt in. | + +## Authentication + +Each MCP server uses one of four authentication modes. When you change the +auth type, fields from the previous type are automatically cleared. + +Secrets are never returned in API responses — boolean flags indicate whether +a value is set. + +### None + +No credentials are sent. Use this for servers that do not require +authentication. + +### OAuth2 + +Per-user authorization. The administrator configures the OAuth2 provider, and +each user independently completes the authorization flow. + +**Manual configuration** — provide all three fields together: + +| Field | Description | +|--------------------|-----------------------------| +| `oauth2_client_id` | OAuth2 client ID. | +| `oauth2_auth_url` | Authorization endpoint URL. | +| `oauth2_token_url` | Token endpoint URL. | + +Optional fields: + +| Field | Description | +|------------------------|---------------------------------| +| `oauth2_client_secret` | OAuth2 client secret. | +| `oauth2_scopes` | Space-separated list of scopes. | + +**Auto-discovery** — leave `oauth2_client_id`, `oauth2_auth_url`, and +`oauth2_token_url` empty. The server attempts discovery in this order: + +1. RFC 9728 — Protected Resource Metadata +1. RFC 8414 — Authorization Server Metadata +1. RFC 7591 — Dynamic Client Registration + +Users connect through a popup that redirects through the OAuth2 provider. +Tokens are stored per-user and refreshed automatically. Users can disconnect +via the UI or API to remove stored tokens. + +### API key + +A static key sent as a header on every request. + +| Field | Required | Description | +|------------------|----------|--------------------------------------| +| `api_key_header` | Yes | Header name (e.g., `Authorization`). | +| `api_key_value` | Yes | Secret value sent in the header. | + +### Custom headers + +Arbitrary key-value header pairs sent on every request. At least one header +is required when this mode is selected. + +## Tool governance + +Control which tools from a server are available in chat: + +| Field | Description | +|-------------------|---------------------------------------------------------------------------------------| +| `tool_allow_list` | If non-empty, only the listed tool names are exposed. An empty list allows all tools. | +| `tool_deny_list` | Listed tool names are always blocked, even if they appear in the allow list. | + +## Permissions + +| Action | Required role | +|-------------------------------|---------------------------| +| Create, update, or delete | Admin (deployment config) | +| View enabled servers | Any authenticated user | +| OAuth2 connect and disconnect | Any authenticated user | + +Non-admin users only see enabled servers. Sensitive fields such as API keys +and client secrets are redacted in API responses. diff --git a/docs/ai-coder/agents/platform-controls/usage-insights.md b/docs/ai-coder/agents/platform-controls/usage-insights.md new file mode 100644 index 0000000000..4d65a2d644 --- /dev/null +++ b/docs/ai-coder/agents/platform-controls/usage-insights.md @@ -0,0 +1,85 @@ +# Usage and Analytics + +Coder provides two admin-only views for monitoring and controlling agent +spend: usage limits and cost tracking. + +## Usage limits + +Navigate to **Agents** > **Settings** > **Limits**. + +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 +processing each chat message. + +### Configuration + +- **Enable/disable toggle** — master on/off for the entire limit system. +- **Period** — `day`, `week`, or `month`. Periods are UTC-aligned: midnight + UTC for daily, Monday start for weekly, first of the month for monthly. +- **Default limit** — deployment-wide default in dollars. Applies to all + users who do not have a more specific override. Leave unset for no limit. +- **Per-user overrides** — set a custom dollar limit for an individual user. + Takes highest priority. +- **Per-group overrides** — set a limit for a group. When a user belongs to + multiple groups, the lowest group limit applies. + +### Priority hierarchy + +The system resolves a user's effective limit in this order: + +1. Individual user override (highest priority) +1. Minimum group limit across all of the user's groups +1. Global default limit +1. No limit (if limits are disabled or no value is configured) + +### Enforcement + +- Checked before each chat message is processed. +- When current spend meets or exceeds the limit, the chat returns a + **409 Conflict** response and the message is blocked. +- Fail-open: if the limit query itself fails, the message is allowed + through. +- Brief overage is possible when concurrent messages are in flight, because + cost is determined only after the LLM returns. + +### User-facing status + +Users can view their own spend status, including whether a limit is active, +their effective limit, current spend, and when the current period resets. + +> [!NOTE] +> The admin configuration page shows the count of models without pricing +> data. Models missing pricing cannot be tracked accurately against limits. + +## Cost tracking + +Navigate to **Agents** > **Settings** > **Usage**. + +This view shows deployment-wide LLM chat costs with per-user drill-down. + +### Top-level view + +A per-user rollup table with the following columns: + +| Column | Description | +|--------------------|-------------------------------------| +| Total cost | Aggregate dollar spend for the user | +| Messages | Number of chat messages sent | +| Chats | Number of distinct chat sessions | +| Input tokens | Total input tokens consumed | +| Output tokens | Total output tokens consumed | +| Cache read tokens | Tokens served from cache | +| Cache write tokens | Tokens written to cache | + +The table supports date range filtering (default: last 30 days), search by +name or username, and pagination. + +### Per-user detail view + +Select a user to see: + +- **Summary cards** — total cost, token breakdowns, and message counts. +- **Usage limit progress** — if a limit is active, a color-coded progress + bar shows current spend relative to the limit. +- **Per-model breakdown** — table of costs and token usage by model. +- **Per-chat breakdown** — table of costs and token usage by chat session. diff --git a/docs/manifest.json b/docs/manifest.json index caff527b12..50255cae56 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1238,9 +1238,27 @@ "description": "Best practices for creating templates that are discoverable and useful to Coder Agents", "path": "./ai-coder/agents/platform-controls/template-optimization.md", "state": ["early access"] + }, + { + "title": "MCP Servers", + "description": "Configure external MCP servers that provide additional tools for agent chat sessions", + "path": "./ai-coder/agents/platform-controls/mcp-servers.md", + "state": ["early access"] + }, + { + "title": "Usage \u0026 Analytics", + "description": "Spend limits and cost tracking for Coder Agents", + "path": "./ai-coder/agents/platform-controls/usage-insights.md", + "state": ["early access"] } ] }, + { + "title": "Extending Agents", + "description": "Add custom skills and MCP tools to agent workspaces", + "path": "./ai-coder/agents/extending-agents.md", + "state": ["early access"] + }, { "title": "Chats API", "description": "Programmatic access to Coder Agents via the experimental Chats API",