diff --git a/_vendor/github.com/docker/docker-agent/docs/concepts/models/index.md b/_vendor/github.com/docker/docker-agent/docs/concepts/models/index.md index 85fb24725375..033461818767 100644 --- a/_vendor/github.com/docker/docker-agent/docs/concepts/models/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/concepts/models/index.md @@ -3,6 +3,7 @@ title: "Models" description: "Models are the AI brains behind your agents. docker-agent supports multiple providers and flexible configuration." keywords: docker agent, ai agents, concepts, models weight: 20 +canonical: https://docs.docker.com/ai/docker-agent/concepts/models/ --- _Models are the AI brains behind your agents. docker-agent supports multiple providers and flexible configuration._ @@ -79,6 +80,7 @@ for details. | Mistral | `mistral` | Mistral models | `MISTRAL_API_KEY` | | xAI | `xai` | Grok models | `XAI_API_KEY` | | Nebius | `nebius` | Open-source and specialised models | `NEBIUS_API_KEY` | +| NVIDIA NIM | `nvidia` | Nemotron, Llama, Qwen, DeepSeek (open models) | `NVIDIA_API_KEY` | | MiniMax | `minimax` | MiniMax models | `MINIMAX_API_KEY` | | Baseten | `baseten` | DeepSeek, Kimi, GLM, Llama models | `BASETEN_API_KEY` | | OVHcloud | `ovhcloud` | Qwen, Llama, Mistral, DeepSeek (EU-hosted) | `OVH_AI_ENDPOINTS_ACCESS_TOKEN` | @@ -97,6 +99,7 @@ for details. | Azure OpenAI | `azure` | gpt-4o, gpt-5 on Azure | `AZURE_API_KEY` + `base_url` | | Ollama | `ollama` | Any local Ollama model | None (local; optional `base_url`) | | GitHub Copilot | `github-copilot` | Copilot-hosted OpenAI/Anthropic | `GITHUB_TOKEN` (PAT with `copilot`) | +| ChatGPT (OpenAI account) | `chatgpt` | gpt-5 family via ChatGPT subscription | None (sign in via `docker agent setup`) | See the [Model Providers](../../providers/overview/index.md) section for detailed configuration guides. @@ -122,11 +125,22 @@ Control how much the model "thinks" before responding: | Provider | Format | Values | Default | | ---------- | ---------- | ------------------------------------------------------------------- | -------------------------------- | -| OpenAI | string | `minimal`, `low`, `medium`, `high`, `xhigh` | `medium` (always-reasoning models only) | +| OpenAI | string | `minimal`, `low`, `medium`, `high`, `xhigh`, `max` | `medium` (always-reasoning models only) | | Anthropic | int or str | 1024–32768 tokens, or `adaptive`, `adaptive/`, effort level | off | | Gemini 2.5 | int | 0 (off), -1 (dynamic), or token count | -1 (dynamic) | | Gemini 3 | string | `minimal`, `low`, `medium`, `high` | varies | -| All | string/int | `none` or `0` to disable | — | +| All | string/int | `none` or `0` clears docker-agent's local config | — | + +`none` and `0` are not universal API-level disable switches. On genuine OpenAI +gpt-5.6+ endpoints (Sol/Terra/Luna), `none` is a real `reasoning_effort` value +that docker-agent sends as-is and the model does not reason. On older OpenAI +models, `none`/`0` only clear the local `thinking_budget` — omitting the field +has the same effect — and the model falls back to the API's own default effort +(still reasoning internally for always-reasoning models like the o-series). +Providers with a true optional-thinking switch (Gemini 2.5, Claude, local +models) are fully disabled by `none`/`0`. See the +[Thinking / Reasoning guide](../../guides/thinking/index.md#disabling-thinking) +for the full per-provider breakdown. ```yaml models: @@ -137,8 +151,8 @@ models: fast-responder: provider: openai - model: gpt-5 - thinking_budget: none # disable thinking + model: gpt-5.6 + thinking_budget: none # real API-level disable on gpt-5.6+ ``` > [!NOTE] diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/agents/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/agents/index.md index f5550c08201f..631c5d516b43 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/agents/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/agents/index.md @@ -4,10 +4,13 @@ description: "Complete reference for defining agents in your YAML configuration. keywords: docker agent, ai agents, configuration, yaml, agent configuration linkTitle: "Agent Config" weight: 30 +canonical: https://docs.docker.com/ai/docker-agent/configuration/agents/ --- _Complete reference for defining agents in your YAML configuration._ +A configuration must define at least one agent under `agents`. + ## Full Schema @@ -33,7 +36,10 @@ agents: max_iterations: int # Optional: max tool-calling loops max_consecutive_tool_calls: int # Optional: max identical consecutive tool calls max_old_tool_call_tokens: int # Optional: token budget for old tool call content (disabled unless positive) + max_tool_result_tokens: int # Optional: per-tool-result token cap with middle-out truncation (disabled unless positive) num_history_items: int # Optional: limit conversation history + session_compaction: boolean # Optional: disable automatic session compaction (default: true) + compaction_threshold: float # Optional: context-window fraction that triggers auto-compaction (0–1, default: 0.9) use_toolsets: [list] # Optional: names of top-level toolsets to merge into this agent readonly: boolean # Optional: restrict all toolsets to read-only tools only skills: boolean | [list] # Optional: enable skill discovery (true/false or list of names and/or sources) @@ -94,7 +100,10 @@ agents: | `max_iterations` | int | ✗ | Maximum number of tool-calling loops. Default: unlimited (0). Set this to prevent infinite loops. | | `max_consecutive_tool_calls` | int | ✗ | Maximum consecutive identical tool calls before the agent is terminated, preventing degenerate loops. Default: `5`. | | `max_old_tool_call_tokens` | int | ✗ | Maximum number of tokens to keep from old tool call arguments and results. Older tool calls beyond this budget have their content replaced with a placeholder, saving context space. Tokens are approximated as `len/4`. Truncation is disabled by default; set a positive value to enable it. Set to `-1` to disable truncation (unlimited). | +| `max_tool_result_tokens` | int | ✗ | Maximum number of tokens to keep from each tool result when it is added to the session. Oversized results are truncated middle-out: the head and tail are kept and the removed middle is replaced with a truncation marker. Textual documents attached to the result share the same budget. Tokens are approximated as `len/4`. The cap is disabled by default; set a positive value to enable it. `0` and `-1` both leave tool results unbounded. | | `num_history_items` | int | ✗ | Limit the number of conversation history messages sent to the model. Useful for managing context window size with long conversations. Default: unlimited (all messages sent). | +| `session_compaction` | boolean | ✗ | When `false`, disables automatic session compaction for this agent: neither the proactive threshold trigger nor the post-overflow auto-recovery runs. The manual `/compact` command remains available. Default: `true`. | +| `compaction_threshold` | float | ✗ | Fraction of the model's context window at which proactive auto-compaction triggers. Must be greater than `0` and at most `1`. A `compaction_threshold` set on the agent's model takes precedence. Default: `0.9`. See [Compaction Threshold](../models/index.md#delegating-session-compaction). | | `skills` | bool/array | ✗ | Enable automatic skill discovery. `true` loads all discovered local skills, `false` disables them. A list can mix skill sources (`local` or `https://…` URLs) and skill names to include — see [Skills](../../features/skills/index.md). | | `commands` | object | ✗ | Named prompts that can be run with `docker agent run config.yaml /command_name`. Can be simple strings or objects with `instruction` and/or `agent` fields for agent switching, or a `url` field to open a link in the browser (TUI only). See [Named Commands](#named-commands) below. | | `use_commands` | list of string | ✗ | Names of top-level `commands` groups to merge into this agent. Inline `commands` entries take precedence on name conflicts. Default: `[]`. | diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/hooks/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/hooks/index.md index b1bf7b005f0b..cc652e01c81d 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/hooks/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/hooks/index.md @@ -3,6 +3,7 @@ title: "Hooks" description: "Run shell commands at various points during agent execution for deterministic control over behavior." keywords: docker agent, ai agents, configuration, yaml, hooks weight: 60 +canonical: https://docs.docker.com/ai/docker-agent/configuration/hooks/ --- _Run shell commands at various points during agent execution for deterministic control over behavior._ @@ -56,7 +57,7 @@ docker-agent dispatches the following hook events: | `on_max_iterations` | When the runtime reaches its configured `max_iterations` limit | No | | `on_agent_switch` | When the runtime moves the active agent (transfer_task, handoff, return) | No | | `on_session_resume` | When the user explicitly approves continuation past `max_iterations` | No | -| `on_tool_approval_decision` | After the runtime's approval chain (yolo / permissions / readonly / ask) resolves | No | +| `on_tool_approval_decision` | After the runtime's approval chain (permissions / yolo / readonly / ask) resolves | No | | `worktree_create` | After `docker agent run --worktree` creates a git worktree, before the session | Yes | > [!NOTE] @@ -66,6 +67,8 @@ docker-agent dispatches the following hook events: ## Configuration +You can configure hooks directly in an agent YAML file under the agent's `hooks:` block: + ```yaml agents: root: @@ -114,6 +117,65 @@ agents: command: "./scripts/alert.sh" ``` +Each event takes a list of hooks. A single hook can also be written directly +as a mapping, without the list dash: + +```yaml +stop: + type: command + command: "./scripts/log-response.sh" +``` + +## Global (user-level) hooks + +Global hooks let you apply the same hook configuration to every agent you run. Define them in your user config file at `~/.config/cagent/config.yaml` under `settings.hooks`: + +```yaml +# ~/.config/cagent/config.yaml +settings: + hooks: + session_start: + - type: command + command: "~/.config/cagent/hooks/session-start.sh" + pre_compact: + - type: command + command: "~/.config/cagent/hooks/pre-compact.sh" + pre_tool_use: + - matcher: "shell" + hooks: + - type: command + command: "~/.config/cagent/hooks/check-shell.sh" +``` + +Global hooks use the same schema as agent-level hooks and are additive. If an event is configured in multiple places, all matching hooks run in this order: + +1. Agent-config hooks from the agent YAML +2. Global hooks from `settings.hooks` +3. Hook drop-ins from `/hooks.d/` (lexicographic file order) +4. CLI hooks from `--hook-*` flags + +Global hooks cannot be suppressed by an individual agent. Use them for user-wide audit logging, personal guardrails, notifications, and setup/cleanup behavior that should apply everywhere. + +### Hook drop-in files (`hooks.d`) + +External tools that integrate with docker-agent (terminal emulators, IDEs, audit or observability sidecars) shouldn't have to rewrite your `config.yaml` to install a hook. Instead, docker-agent also loads every `*.yaml` / `*.yml` file from the `hooks.d` directory next to your user config (default: `~/.config/cagent/hooks.d/`). Each file is a standalone hooks block with the same schema as the content of `settings.hooks`: + +```yaml +# ~/.config/cagent/hooks.d/50-mytool.yaml +session_start: + - type: command + command: mytool notify --event session-start +stop: + - type: command + command: mytool notify --event stop +``` + +- Files are loaded in lexicographic order and merged additively after `settings.hooks` (use numeric prefixes like `10-`, `50-` to control ordering). +- A malformed file is skipped with a logged warning; a broken drop-in never breaks a run. +- Installing an integration means writing one self-contained file; uninstalling means deleting it. No shared-file edits, no conflicts between tools. + +The config directory can be relocated with the `--config-dir` flag or the `DOCKER_AGENT_CONFIG_DIR` (legacy `CAGENT_CONFIG_DIR`) environment variable, which external tools can use to locate `hooks.d` under non-default config dirs. + ## Built-in Hooks In addition to shell `command` hooks, docker-agent ships a small library of **built-in hooks** — in-process Go functions that run without spawning a subprocess. They're invoked with `type: builtin`, where `command` is the builtin's registered name and `args` are passed through as the builtin's parameters. @@ -155,7 +217,7 @@ Built-ins are typically zero-config and faster than equivalent shell hooks becau | `snapshot` | `session_start`, `turn_start`, `turn_end`, `pre_tool_use`, `post_tool_use`, `session_end` | _none_ | Records filesystem snapshots in a shadow git repo under the docker-agent data directory. No-op outside git repos; respects the source repo's ignore rules and skips newly-added files larger than 2 MiB. | | `redact_secrets` | `pre_tool_use`, `before_llm_call`, `tool_response_transform` | _none_ | Scrubs detected secrets (API keys, tokens, private keys, …) out of tool call arguments, outgoing chat content, and tool output. The same builtin handles all three events and dispatches on the event name. Auto-registered on all three events by `redact_secrets: true` on the agent — see [`examples/redact_secrets_hooks.yaml`](https://github.com/docker/docker-agent/blob/main/examples/redact_secrets_hooks.yaml) for the manual wiring. | | `limit_large_tool_results` | `tool_response_transform`, `session_end` | _none_ | **Always-on safety hook** — automatically injected by the runtime, no configuration required. When a tool result from the `filesystem`, `shell`, `mcp`, or `a2a` categories exceeds 2,000 lines or 50 KiB, the full payload is written to a per-session temp file and replaced in the conversation with a notice plus a bounded tail (last 2,000 lines, up to 50 KiB). The `session_end` leg deletes the temp directory. Internal toolsets (`memory`, `plan`, `tasks`, `think`, …) are not affected. | -| `safer_shell` | `pre_tool_use` (with `preempt_yolo: true`) | _none_ | Classifies shell commands against an embedded taxonomy. Destructive matches (rm -rf, docker volume rm, mkfs, …) get an Ask verdict with `blast_radius` / `category` metadata; known-safe reads (ls, git status, docker ps, …) flow through silently; everything else asks with `blast_radius=unknown`. Filters by tool name internally (no-op for non-shell calls). Registered with `preempt_yolo: true` so the entry fires before `Decide()` / `--yolo`. Auto-registered by `safer: true` on a shell toolset — see [`examples/shell_safer.yaml`](https://github.com/docker/docker-agent/blob/main/examples/shell_safer.yaml). | +| `safer_shell` | `pre_tool_use` (with `preempt_yolo: true`) | `[""]` (optional pin) | Classifies shell commands against an embedded taxonomy. Verdict adapts to the session's `SafetyPolicy`. `unsafe`: silent. `safer`: destructive matches Ask with `blast_radius`/`category` metadata; safe and unknown flow through silently. `safe-auto`: safe matches auto-Allow with `blast_radius=safe`; destructive and unknown Ask. `strict` (default): safe, destructive, and unknown all Ask with `blast_radius` metadata (safe/low/medium/high/unknown). Filters by tool name internally (no-op for non-shell calls). Auto-registered by `safer: true` on a shell toolset — see [`examples/shell_safer.yaml`](https://github.com/docker/docker-agent/blob/main/examples/shell_safer.yaml). | | `unload` | `on_agent_switch` | _none_ | POSTs `{"model": ""}` to each of the previous agent's DMR model endpoints (`/_unload` by default, overridable per-model via `unload_api`) to free the GPU/RAM the just-departing model was holding. Pure HTTP — reads the model snapshot the runtime ships on `on_agent_switch` and depends on no provider-specific runtime state. Non-DMR providers (OpenAI, Anthropic, …) are silently skipped, so cross-provider chains are safe. Errors are logged and swallowed; agent switching never blocks on a slow or unreachable engine (each call has a 10 s timeout). See [`examples/unload_on_switch.yaml`](https://github.com/docker/docker-agent/blob/main/examples/unload_on_switch.yaml). | > [!NOTE] @@ -284,11 +346,11 @@ Notes: - `prompt` is also populated for `user_followup_submit`, carrying the text of the dequeued follow-up message (a user message queued for end-of-turn processing via the FollowUp API / queue, as opposed to mid-turn steering). - `stop_response` carries the model's final assistant text for `stop`, `after_llm_call`, and `subagent_stop`. `last_user_message` carries the latest user message at dispatch time. - `model_id` is populated for `after_llm_call` (and `before_llm_call`) in the canonical `/` form (e.g. `anthropic/claude-sonnet-4-5`). For harness agents, `model_id` is the harness label (e.g. `claude-code`) rather than a canonical model name — see [Coding Harnesses](../../features/harnesses/index.md). -- `usage` and `cost` are populated for `after_llm_call` only. `usage` is the per-call token usage object (`input_tokens`, `output_tokens`, `cached_input_tokens`, `cached_write_tokens`, and `reasoning_tokens` — the last is itself omitted for non-reasoning models); the whole object is absent when the provider reported no usage. `cost` is the USD price of that one model response. For a **native model call** it is the price computed from `usage` and the model's pricing table, and equals the cost the session records for the turn: it is **absent** when the response is unpriced (no pricing data on file, or no usage) and an explicit `0` for a priced call that was free — so a present `cost` is authoritative and an absent one means "unpriced", with no need to cross-check `usage`. (For harness agents the meaning differs — see the next note.) A cost ledger can therefore record per-call spend from the payload alone, without subscribing to the runtime event channel. +- `usage` and `cost` are populated for `after_llm_call` only. `usage` is the per-call token usage object (`input_tokens`, `output_tokens`, `cached_input_tokens`, `cached_write_tokens`, and `reasoning_tokens` — the last is itself omitted for non-reasoning models); the whole object is absent when the provider reported no usage. `cost` is the USD price of that one model response. For a **native model call** it is the price computed from `usage` and the model's pricing table, and equals the cost the session records for the turn: it is **absent** when the response is unpriced (no pricing data on file, or no usage) and an explicit `0` for a priced call that was free — so a present `cost` is authoritative and an absent one means "unpriced", with no need to cross-check `usage`. Models the catalogue does not price (custom endpoints, local models) can be priced explicitly with the model-level [`cost`](../models/index.md#custom-token-pricing) config. (For harness agents the meaning differs — see the next note.) A cost ledger can therefore record per-call spend from the payload alone, without subscribing to the runtime event channel. - For [harness agents](../../features/harnesses/index.md), `cost` is the harness's own reported total for the call rather than a computed price, and is present only when the harness reported a non-zero cost (some harnesses, e.g. `codex`, report token counts but no cost — those turns carry `usage` with `cost` absent, even though the recorded message stores `0`). - `after_llm_call` fires for **every** model call, including calls made inside sub-sessions (transferred tasks, background agents, skills). For those, `session_id` is the sub-session's id. Summing `cost` across `after_llm_call` events therefore captures **all** spend, including sub-sessions (and even sub-sessions that error before their cost is persisted). Do **not** add a separately-queried session cost total on top: the runtime's own total already recurses into and includes completed sub-session spend, so combining the two double-counts. Pick one source — the summed hook costs — as the authoritative ledger. - `context_limit` is `0` when the model definition is unavailable (treat `0` as "unknown", not as a real limit). -- `approval_decision` is one of `allow`, `deny`, `canceled`. `approval_source` is a stable classifier of which step decided (e.g. `yolo`, `session_permissions_allow`, `session_permissions_deny`, `team_permissions_allow`, `team_permissions_deny`, `pre_tool_use_hook_allow`, `pre_tool_use_hook_deny`, `readonly_hint`, `user_approved`, `user_approved_session`, `user_approved_tool`, `user_rejected`, `context_canceled`). +- `approval_decision` is one of `allow`, `deny`, `canceled`. `approval_source` is a stable classifier of which step decided (e.g. `yolo`, `session_permissions_allow`, `session_permissions_deny`, `team_permissions_allow`, `team_permissions_deny`, `pre_tool_use_hook_allow`, `pre_tool_use_hook_deny`, `readonly_hint`, `user_approved`, `user_approved_session`, `user_approved_safe`, `user_approved_tool`, `user_rejected`, `context_canceled`). ## Hook Output @@ -444,7 +506,7 @@ hooks: `pre_tool_use` is fail-closed for safety: a failed pre-tool hook blocks the tool call regardless of `on_error`. -`working_dir` and `env` apply to `command` and `builtin` hooks. For `builtin` hooks, `working_dir` is resolved with the same logic as `command` hooks (absolute path wins; relative paths join onto the executor directory). For `model` hooks, both fields are accepted by the schema but have no effect: model hooks render a prompt template and call the LLM API directly — no subprocess is spawned and no file I/O is performed, so working directory and environment variables have no applicable semantics. +`working_dir` and `env` apply to `command` and `builtin` hooks. For `builtin` hooks, `working_dir` is resolved with the same logic as `command` hooks (absolute path wins; relative paths join onto the executor directory). `working_dir` accepts `~`, `$VAR`, `${VAR}` and `${env.VAR}`; `env` values expand only the plain `${env.VAR}` form (resolved from the OS process environment), keeping any other `$` literal (see [Variable Expansion in Config Fields](../overview/index.md#variable-expansion-in-config-fields)). A `working_dir` that expands to an empty string (e.g. an unset variable) falls back to the executor's directory with a warning. For `model` hooks, both fields are accepted by the schema but have no effect: model hooks render a prompt template and call the LLM API directly — no subprocess is spawned and no file I/O is performed, so working directory and environment variables have no applicable semantics. > [!WARNING] > **Performance** @@ -651,7 +713,7 @@ At every transfer the runtime ships a snapshot of the previous agent's model end ### Tool-Approval-Decision: who-approved-what audit trail -`on_tool_approval_decision` fires after the runtime's tool-approval chain (yolo / permissions / readonly / pre_tool_use hooks / interactive prompt) has resolved a verdict for a tool call. `approval_decision` is `allow`, `deny`, or `canceled`; `approval_source` is a stable classifier of which step produced the verdict. Observational only — it gives audit pipelines a single, structured "who approved what" record without re-implementing the chain. +`on_tool_approval_decision` fires after the runtime's tool-approval chain (permissions / yolo / readonly / pre_tool_use hooks / interactive prompt) has resolved a verdict for a tool call. `approval_decision` is `allow`, `deny`, or `canceled`; `approval_source` is a stable classifier of which step produced the verdict. Observational only — it gives audit pipelines a single, structured "who approved what" record without re-implementing the chain. ### Worktree-Create: prepare an isolated checkout @@ -879,4 +941,4 @@ $ docker agent run agentcatalog/coder \ > [!NOTE] > **Merging behavior** > -> CLI hooks are **appended** to any hooks already defined in the agent's YAML config. They don't replace existing hooks. Pre/post-tool-use hooks added via CLI match all tools (equivalent to `matcher: "*"`). +> Agent-config, global, drop-in, and CLI hooks are additive. For each event, hooks run in this order: agent-config hooks first, then global hooks from `settings.hooks`, then [hook drop-ins](#hook-drop-in-files-hooksd) from `hooks.d/`, then CLI hooks. No source replaces another, and individual agents cannot opt out of global hooks. diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/models/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/models/index.md index 086a0562c581..503359cf4dce 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/models/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/models/index.md @@ -4,6 +4,7 @@ description: "Complete reference for defining models with providers, parameters, keywords: docker agent, ai agents, configuration, yaml, model configuration linkTitle: "Model Config" weight: 40 +canonical: https://docs.docker.com/ai/docker-agent/configuration/models/ --- _Complete reference for defining models with providers, parameters, and reasoning settings._ @@ -17,7 +18,7 @@ models: first_available: [list] # Optional: candidate model refs, tried in order by available credentials. # Mutually exclusive with other model settings. provider: string # Required unless using first_available. One of: openai, anthropic, google, amazon-bedrock, - # dmr, mistral, xai, nebius, minimax, baseten, ovhcloud, groq, fireworks, deepseek, cerebras, together, huggingface, moonshot, vercel, cloudflare-workers-ai, cloudflare-ai-gateway, requesty, openrouter, + # dmr, mistral, xai, nebius, nvidia, minimax, baseten, ovhcloud, groq, fireworks, deepseek, cerebras, together, huggingface, moonshot, vercel, cloudflare-workers-ai, cloudflare-ai-gateway, requesty, openrouter, # azure, ollama, github-copilot, or a named provider defined # under the top-level `providers:` section. model: string # Required: model identifier @@ -36,11 +37,17 @@ models: capabilities: # Optional: override attachment capabilities image: boolean # Optional: whether the model accepts image attachments pdf: boolean # Optional: whether the model accepts PDF attachments + cost: # Optional: explicit token pricing (USD per 1M tokens) + input: float # Optional: price per 1M input tokens + output: float # Optional: price per 1M output tokens + cache_read: float # Optional: price per 1M cached input tokens + cache_write: float # Optional: price per 1M cache-write tokens provider_opts: # Optional: provider-specific options key: value title_model: string # Optional: model used for session-title generation compaction_model: string # Optional: model used for session-compaction (summary generation) - bypass_models_gateway: boolean # Optional: skip the models gateway for this model + compaction_threshold: float # Optional: context-window fraction that triggers auto-compaction (0–1, default: 0.9) + bypass_models_gateway: boolean # Optional: skip the models gateway for this model (implied by a custom base_url) ``` ## Properties Reference @@ -48,7 +55,7 @@ models: | Property | Type | Required | Description | | --------------------- | ---------- | -------- | ------------------------------------------------------------------------------------- | | `first_available` | array | ✗ | Candidate model references tried in order; selects the first whose credentials are configured. Mutually exclusive with other model settings. | -| `provider` | string | ✓/✗ | Required for regular model definitions; omitted for `first_available` selectors. Provider: `openai`, `anthropic`, `google`, `amazon-bedrock`, `dmr`, `mistral`, `xai`, `nebius`, `minimax`, `baseten`, `ovhcloud`, `groq`, `fireworks`, `deepseek`, `cerebras`, `together`, `huggingface`, `moonshot`, `vercel`, `cloudflare-workers-ai`, `cloudflare-ai-gateway`, `requesty`, `openrouter`, `azure`, `ollama`, `github-copilot`, or any [named provider](../../providers/custom/index.md). | +| `provider` | string | ✓/✗ | Required for regular model definitions; omitted for `first_available` selectors. Provider: `openai`, `anthropic`, `google`, `amazon-bedrock`, `dmr`, `mistral`, `xai`, `nebius`, `nvidia`, `minimax`, `baseten`, `ovhcloud`, `groq`, `fireworks`, `deepseek`, `cerebras`, `together`, `huggingface`, `moonshot`, `vercel`, `cloudflare-workers-ai`, `cloudflare-ai-gateway`, `requesty`, `openrouter`, `azure`, `ollama`, `github-copilot`, `chatgpt`, or any [named provider](../../providers/custom/index.md). | | `model` | string | ✓/✗ | Required for regular model definitions; omitted for `first_available` selectors. Model name (e.g., `gpt-4o`, `claude-sonnet-4-5`, `gemini-3.5-flash`) | | `temperature` | float | ✗ | Sampling randomness. Range is provider-dependent — typically `0.0–2.0` (Anthropic caps at `1.0`). `0.0` is deterministic. | | `max_tokens` | int | ✗ | Maximum response length in tokens | @@ -63,10 +70,12 @@ models: | `track_usage` | boolean | ✗ | Track and report token usage for this model | | `routing` | array | ✗ | Rule-based routing to different models. See [Model Routing](../routing/index.md). | | `capabilities` | object | ✗ | Override attachment capabilities for this model. See [Attachment Capability Overrides](#attachment-capability-overrides). | +| `cost` | object | ✗ | Explicit token pricing in USD per 1M tokens, overriding the built-in catalogue. See [Custom Token Pricing](#custom-token-pricing). | | `provider_opts` | object | ✗ | Provider-specific options (see provider pages) | | `title_model` | string | ✗ | Model used for session-title generation. Can be a named model from the `models:` section or an inline `provider/model` string. When omitted, the agent's primary model generates titles. Cannot be combined with `first_available`. | | `compaction_model` | string | ✗ | Model used for session compaction (summary generation). Can be a named model or an inline `provider/model` string. When omitted, the primary model compacts. Cannot be combined with `first_available`. See [Delegating Session Compaction](#delegating-session-compaction). | -| `bypass_models_gateway` | boolean | ✗ | When `true`, this model connects directly to its provider even when a models gateway (`--models-gateway` / `CAGENT_MODELS_GATEWAY`) is configured. See [Gateway Bypass](#gateway-bypass). | +| `compaction_threshold` | float | ✗ | Fraction of the context window at which proactive auto-compaction triggers for agents running this model. Must be greater than `0` and at most `1`. Takes precedence over the agent-level `compaction_threshold`. Cannot be combined with `first_available`. Default: `0.9`. | +| `bypass_models_gateway` | boolean | ✗ | When `true`, this model connects directly to its provider even when a models gateway (`--models-gateway` / `CAGENT_MODELS_GATEWAY`) is configured. Implied by a custom `base_url`. See [Gateway Bypass](#gateway-bypass). | ## Attachment Capability Overrides @@ -108,6 +117,53 @@ conservative text-only fallback). See [`examples/capability-overrides.yaml`](https://github.com/docker/docker-agent/blob/main/examples/capability-overrides.yaml) for a complete example. +## Custom Token Pricing + +docker-agent prices each model call from the [models.dev](https://models.dev/) +catalogue. Models the catalogue does not know — custom OpenAI-compatible +providers, local models, private deployments — are "unpriced": every call is +recorded at $0 despite consuming tokens, with only a log warning. + +Declare `cost` to price a model explicitly, in **USD per one million tokens**. +When set, it takes precedence over the catalogue and makes an uncatalogued +model priced: + +```yaml +models: + internal-gpt: + provider: internal-llm + model: gpt-4o + cost: + input: 1.25 # USD per 1M input tokens + output: 5.00 # USD per 1M output tokens + cache_read: 0.125 # USD per 1M cached input tokens + cache_write: 1.5625 # USD per 1M cache-write tokens + + # Also works for catalogued models, e.g. a negotiated enterprise discount: + discounted-sonnet: + provider: anthropic + model: claude-sonnet-4-5 + cost: + input: 2.4 + output: 12.0 +``` + +| Field | Type | Description | +| ------------------ | ----- | --------------------------------------- | +| `cost.input` | float | USD price per 1M input tokens | +| `cost.output` | float | USD price per 1M output tokens | +| `cost.cache_read` | float | USD price per 1M cached input tokens | +| `cost.cache_write` | float | USD price per 1M cache-write tokens | + +The declared prices feed per-turn cost computation, session cost tracking, the +`/model` picker, and the [`after_llm_call` hook](../hooks/index.md)'s `cost` +field. Prices must not be negative; omitted fields default to `0`. An all-zero +table means "priced, free" — distinct from omitting `cost` entirely +(unpriced). Cannot be combined with `first_available` (set it on the candidate +models instead). + +See [`examples/custom-pricing.yaml`](https://github.com/docker/docker-agent/blob/main/examples/custom-pricing.yaml) for a complete example. + ## Delegating Session-Title Generation The `title_model` field lets a heavyweight primary model hand off the cheap @@ -152,18 +208,39 @@ call can always ingest the full conversation. Pair the primary with a compaction model whose window is at least as large to keep the proactive trigger aligned with the primary's window. +By default the proactive trigger fires when the estimated token usage crosses +**90%** of the context window. The `compaction_threshold` field tunes that +fraction (greater than `0`, at most `1`): lower values compact earlier and +keep requests smaller, higher values compact later and keep more verbatim +history. It can be set on the model (as above, taking precedence) or on the +agent, and automatic compaction can be disabled entirely per agent with +`session_compaction: false` — see [Agent Config](../agents/index.md#properties-reference). + +```yaml +models: + primary: + provider: anthropic + model: claude-sonnet-4-5 + compaction_model: fast + # Compact at 80% of the window instead of the default 90%. + compaction_threshold: 0.8 +``` + > [!WARNING] > **Constraint** > > `compaction_model` cannot be combined with `first_available` model selection — the combination is rejected at validation time. -See [`examples/compaction_model.yaml`](https://github.com/docker/docker-agent/blob/main/examples/compaction_model.yaml) for a complete example. +See [`examples/compaction_model.yaml`](https://github.com/docker/docker-agent/blob/main/examples/compaction_model.yaml) +and [`examples/compaction_threshold.yaml`](https://github.com/docker/docker-agent/blob/main/examples/compaction_threshold.yaml) +for complete examples. ## Gateway Bypass When a models gateway (`--models-gateway` / `CAGENT_MODELS_GATEWAY`) is configured, -all models route through it by default. Set `bypass_models_gateway: true` on a -specific model to make it connect directly to its provider instead: +models without a custom `base_url` route through it by default. Set +`bypass_models_gateway: true` on a specific model to make it connect directly +to its provider instead: ```yaml models: @@ -255,8 +332,8 @@ Uses effort levels as strings: models: gpt: provider: openai - model: gpt-5 - thinking_budget: low # minimal | low | medium | high | xhigh + model: gpt-5.6 + thinking_budget: low # none | minimal | low | medium | high | xhigh | max (xhigh needs gpt-5.2+; none/max need gpt-5.6+; minimal dropped on gpt-5.6+) ``` ### Anthropic @@ -302,13 +379,23 @@ models: ### Disabling Thinking -Works for all providers: - ```yaml thinking_budget: none # or 0 ``` -Models that always reason (OpenAI o-series, gpt-5, Gemini 3) fall back to the API default and still reason internally. +`none` and `0` both clear docker-agent's local thinking configuration (omitting `thinking_budget` has the same effect); neither is guaranteed to reach the API as a real "off" switch: + +- **OpenAI gpt-5.6+** (Sol/Terra/Luna) is the only case with a genuine API-level `none` reasoning effort: docker-agent sends it as-is and the model does not reason. +- **Older OpenAI reasoning models** (o-series, gpt-5 through gpt-5.5) have no such switch: `none`/`0` just clear the local config, and the model falls back to the API's own default effort and still reasons internally. Same for other always-reasoning models (Gemini 3). +- Providers with a true optional-thinking switch (Gemini 2.5, Claude, local models) are fully disabled by `none`/`0`. + +```yaml +models: + fast-responder: + provider: openai + model: gpt-5.6 + thinking_budget: none # real API-level disable on gpt-5.6+ +``` See the [Thinking / Reasoning guide](../../guides/thinking/index.md) for per-provider details, including AWS Bedrock and Docker Model Runner. @@ -400,7 +487,7 @@ See the [Anthropic provider page](../../providers/anthropic/index.md#thinking-di ## Custom HTTP Headers For OpenAI-compatible providers (`openai`, `github-copilot`, `mistral`, `xai`, -`nebius`, `minimax`, `baseten`, `ovhcloud`, `groq`, `fireworks`, `deepseek`, `cerebras`, `together`, `huggingface`, `moonshot`, `vercel`, `cloudflare-workers-ai`, `cloudflare-ai-gateway`, `requesty`, `openrouter`, `ollama`, and any custom provider using the OpenAI API), +`nebius`, `nvidia`, `minimax`, `baseten`, `ovhcloud`, `groq`, `fireworks`, `deepseek`, `cerebras`, `together`, `huggingface`, `moonshot`, `vercel`, `cloudflare-workers-ai`, `cloudflare-ai-gateway`, `requesty`, `openrouter`, `ollama`, and any custom provider using the OpenAI API), `provider_opts.http_headers` adds arbitrary HTTP headers to every outgoing request: diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/overview/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/overview/index.md index 104e7f01306c..7380c080c4ac 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/overview/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/overview/index.md @@ -4,6 +4,7 @@ description: "docker-agent uses YAML or HCL configuration files to define agents keywords: docker agent, ai agents, configuration, yaml, configuration overview linkTitle: "Overview" weight: 10 +canonical: https://docs.docker.com/ai/docker-agent/configuration/overview/ aliases: - /ai/docker-agent/reference/config/ --- @@ -18,7 +19,7 @@ A docker-agent config has these main sections: ```bash # 1. Version — configuration schema version (optional but recommended) -version: 10 +version: 12 # 2. Metadata — optional agent metadata for distribution metadata: @@ -33,7 +34,7 @@ models: model: claude-sonnet-4-5 max_tokens: 64000 -# 4. Agents — define AI agents with their behavior +# 4. Agents — define AI agents with their behavior (at least one is required) agents: root: model: claude @@ -212,6 +213,8 @@ Applies to: - `agents..toolsets[*].working_dir` (MCP, LSP) - `agents..toolsets[*].path` (memory, tasks) - `agents..toolsets[*].env` values (MCP, shell, script, LSP) +- `agents..toolsets[*].shell..working_dir` (script tools) +- `agents..hooks.*.working_dir` - The `~` prefix is also accepted in any path-like field documented as such. ```yaml @@ -227,6 +230,21 @@ agents: Unlike the JS-templated fields above, these accept only a plain variable reference: richer JS expressions (e.g. `${env.VAR || 'default'}`) are **not** evaluated here, and the legacy `$VAR` / `${VAR}` forms keep working for backward compatibility. +Hook and script-tool `env` values expand only the plain `${env.VAR}` form, resolved against the **OS process environment** (dotenv/secret-provider values are not consulted); a bare `$VAR` or `${VAR}` is passed through **literally**, so values that legitimately contain `$` (passwords, templates) are never mangled: + +```yaml +agents: + root: + hooks: + session_start: + - type: command + command: ./notify.sh + working_dir: "~/scripts" # ~, $VAR, ${VAR}, ${env.VAR} all work + env: + API_TOKEN: "${env.NOTIFY_TOKEN}" # expanded + PASSWORD: "pa$$word" # kept literal +``` + Model definitions follow the same rule. The `models..model` and `models..base_url` fields are expanded when the provider is built, accepting both `${env.VAR}` and `${VAR}`. This is useful when the model id or endpoint is injected by the environment (for example a Docker Compose / DMR setup that exports the model reference as a variable): ```yaml @@ -248,10 +266,11 @@ models: | `commands.*` | ✓ | ✗ | ✗ | | `headers`, `remote.headers`, `api_config.headers` | ✓ | ✗ | ✗ | | `models.*.model`, `models.*.base_url` | ✓ | ✓ | ✗ | -| `working_dir`, `path` | ✓ | ✓ | ✓ | -| `env` values | ✓ | ✓ | ✗ | +| `working_dir`, `path` (toolset, script tool, hook) | ✓ | ✓ | ✓ | +| `env` values (toolset) | ✓ | ✓ | ✗ | +| `env` values (hook, script tool) | ✓ | literal | ✗ | -The `~` prefix is meaningful only in path-like fields (`working_dir`, `path`). +The `~` prefix is meaningful only in path-like fields (`working_dir`, `path`). In hook and script-tool `env` values, "literal" means a bare `$X` / `${X}` is passed to the process unchanged — only `${env.X}` is substituted there, so values containing `$` survive intact. Prefer `${env.X}` everywhere. The bare `$X` / `${X}` and `~` forms are accepted only in path and `env` value fields, where they remain supported for backward compatibility. @@ -275,10 +294,10 @@ For YAML editor autocompletion and validation, use the [Docker Agent JSON Schema ## Config Versioning -docker-agent configs are versioned. The current version is `10`. Add the version at the top of your config: +docker-agent configs are versioned. The current version is `12`. Add the version at the top of your config: ```yaml -version: 10 +version: 12 agents: root: @@ -288,6 +307,14 @@ agents: When you load an older config, docker-agent automatically migrates it to the latest schema. It's recommended to include the version to ensure consistent behavior. +If you use a config key that requires a newer schema version, Docker Agent will fail with a strict-parse error and include a hint like: + +```text +hint: this key is supported by config version 12; update the top-level 'version' field (currently 11) +``` + +Bump the `version` field as directed to enable the new key. + ## Metadata Section Optional metadata for agent distribution via OCI registries: diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/sandbox/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/sandbox/index.md index fa7dcf4b9712..3e1bca42691c 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/sandbox/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/sandbox/index.md @@ -3,6 +3,7 @@ title: "Sandbox Mode" description: "Run agents in an isolated Docker sandbox VM for enhanced security." keywords: docker agent, ai agents, configuration, yaml, sandbox mode weight: 80 +canonical: https://docs.docker.com/ai/docker-agent/configuration/sandbox/ --- _Run agents in an isolated Docker sandbox VM for enhanced security._ @@ -165,6 +166,12 @@ docker agent run --sandbox agent.yaml 6. All tools (shell, filesystem, background jobs, etc.) run inside the VM. 7. When the session ends, docker-agent exits but does not stop or remove the sandbox VM; both the VM and the kit are kept around so subsequent runs from the same workspace can reuse them. A fresh sandbox is created only when the mount set has changed. +### What the default template includes + +The default template (`docker/sandbox-templates:docker-agent`) ships with: + +- **`docker-mcp`** CLI plugin — installed at `~/.docker/cli-plugins/docker-mcp`, available out of the box so agents can invoke `docker mcp` commands inside the sandbox without any additional setup. + ## Auto-Kit The sandbox VM has its own filesystem and `$HOME` — none of the host's `~/.agents/skills/`, `~/.claude/skills/`, project-level `.agents/skills/`, or prompt files like `AGENTS.md` and `CLAUDE.md` are visible inside it. To bridge that gap, docker-agent automatically builds a **kit**: a self-contained directory staged on the host before the sandbox starts and bind-mounted read-only into the VM at the same path. @@ -175,7 +182,7 @@ The kit is built whenever `--sandbox` is used with an agent reference. It is opt For the agent referenced on the command line, the kit collects: -- **Local [skills](../../features/skills/index.md)** — every `SKILL.md` discovered on the host (global `~/.codex/skills/`, `~/.claude/skills/`, `~/.agents/skills/`, plus project `.claude/skills/` and `.agents/skills/`) is copied under `/skills//`. The in-sandbox skills loader reads from the kit instead of the (non-existent) host `$HOME`. +- **Local [skills](../../features/skills/index.md)** — every `SKILL.md` discovered on the host (global `~/.codex/skills/`, `~/.claude/skills/`, `~/.agents/skills/`, plus project `.claude/skills/`, `.github/skills/` and `.agents/skills/`) is copied under `/skills//`. The in-sandbox skills loader reads from the kit instead of the (non-existent) host `$HOME`. - **Prompt files** — every file referenced via the agent's `add_prompt_files` (`AGENTS.md`, `CLAUDE.md`, …) is collected. Files that already live under the working directory are left alone (the live workspace mount surfaces them); files outside it (e.g. an `AGENTS.md` in `$HOME`) are copied under `/prompt_files/`. - **A manifest** — `/manifest.json` records what was staged. The on-disk copy is sanitised so it cannot be used to map the host filesystem from inside the sandbox. diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/tools/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/tools/index.md index db3e16aaea9a..c84f65b0ba2f 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/tools/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/tools/index.md @@ -4,6 +4,7 @@ description: "Complete reference for configuring built-in tools, MCP tools, and keywords: docker agent, ai agents, configuration, yaml, tool configuration linkTitle: "Tool Config" weight: 50 +canonical: https://docs.docker.com/ai/docker-agent/configuration/tools/ aliases: - /ai/docker-agent/reference/toolsets/ --- @@ -17,7 +18,9 @@ Built-in tools are included with docker-agent and require no external dependenci | Type | Description | Page | | --- | --- | --- | | `filesystem` | Read, write, list, search, navigate | [Filesystem](../../tools/filesystem/index.md) | -| `shell` | Execute shell commands (sync + background jobs) | [Shell](../../tools/shell/index.md) | +| `shell` | Execute shell commands synchronously | [Shell](../../tools/shell/index.md) | +| `background_jobs` | Run and manage long-running shell commands | [Background Jobs](../../tools/background-jobs/index.md) | +| `scheduler` | Schedule instructions to run at a time or on a recurring interval | [Scheduler](../../tools/scheduler/index.md) | | `think` | Reasoning scratchpad | [Think](../../tools/think/index.md) | | `plan` | Shared persistent scratchpad for multi-agent collaboration | [Plan](../../tools/plan/index.md) | | `session_plan` | Per-session markdown plan for the draft-review-execute workflow | [Session Plan](../../tools/session_plan/index.md) | @@ -46,6 +49,7 @@ Built-in tools are included with docker-agent and require no external dependenci toolsets: - type: filesystem - type: shell + - type: background_jobs - type: think - type: todo - type: memory @@ -126,9 +130,9 @@ toolsets: | Property | Type | Description | | ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | -| `remote.url` | string | Base URL of the MCP server | +| `remote.url` | string | URL of the MCP server. Accepts `https://`, `http://`, and `unix://` (Unix domain socket) schemes. | | `remote.transport_type` | string | `streamable` or `sse` | -| `remote.headers` | object | HTTP headers (typically for auth) | +| `remote.headers` | object | HTTP headers sent on every request. Values support `${env.VAR}` and `${headers.NAME}` placeholders, resolved per request. `${env.VAR}` reads an environment variable; `${headers.NAME}` forwards a header from the caller's incoming request (useful when docker-agent runs as an API server). | | `allow_private_ips` | boolean | Permit remote MCP OAuth helper requests to dial non-public IP addresses. Use only for trusted internal servers. | ## Auto-Installing Tools diff --git a/_vendor/github.com/docker/docker-agent/docs/features/api-server/index.md b/_vendor/github.com/docker/docker-agent/docs/features/api-server/index.md index f5da934988e9..a7e452c74414 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/api-server/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/api-server/index.md @@ -3,6 +3,7 @@ title: "API Server" description: "Expose your agents via an HTTP API for programmatic access, web frontends, and integrations." keywords: docker agent, ai agents, features, api server weight: 80 +canonical: https://docs.docker.com/ai/docker-agent/features/api-server/ --- _Expose your agents via an HTTP API for programmatic access, web frontends, and integrations._ @@ -50,6 +51,8 @@ All endpoints are under the `/api` prefix. | `PATCH` | `/api/sessions/:id/title` | Update session title | | `PATCH` | `/api/sessions/:id/permissions` | Update session permissions | | `POST` | `/api/sessions/:id/fork` | Fork a session at a user message — creates a new session with messages `[0, message_index)` of the parent (see [Session Forking](#session-forking)) | +| `POST` | `/api/sessions/:id/messages` | Append a message directly to a session's history (bypasses the model). Returns `409 Conflict` while the session has an active run (see [Agent Execution](#agent-execution)). | +| `PATCH` | `/api/sessions/:id/messages/:msg_id` | Update an existing message by ID. Returns `409 Conflict` while the session has an active run. | | `POST` | `/api/sessions/:id/resume` | Resume a paused session (after tool confirmation) | | `POST` | `/api/sessions/:id/tools/toggle` | Toggle auto-approve (YOLO) mode | | `POST` | `/api/sessions/:id/elicitation` | Respond to an MCP tool elicitation request | @@ -182,7 +185,7 @@ docker agent serve api | [flags] | `-s, --session-db` | `session.db` | Path to the SQLite session database | | `--pull-interval` | `0` (disabled) | Auto-pull OCI reference every N minutes | | `--fake` | (none) | Replay AI responses from cassette file (testing) | -| `--record` | (none) | Record AI API interactions to cassette file | +| `--record` | (none) | Record AI API interactions to cassette file. Routes through `--models-gateway` when one is configured. | | `--mcp-oauth-redirect-uri` | (none) | Public HTTPS URL advertised as the OAuth `redirect_uri` for unmanaged MCP OAuth flows. When set, docker-agent drives PKCE and code exchange in-process and sends the full authorize URL to the client via elicitation. See [Remote MCP](../remote-mcp/index.md) for details. | > [!TIP] diff --git a/_vendor/github.com/docker/docker-agent/docs/features/board/index.md b/_vendor/github.com/docker/docker-agent/docs/features/board/index.md new file mode 100644 index 000000000000..176966a7e59c --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/features/board/index.md @@ -0,0 +1,97 @@ +--- +title: "Kanban Board" +description: "Orchestrate multiple agents from a Kanban TUI: each card runs an agent in a tmux session on an isolated git worktree." +keywords: docker agent, ai agents, features, board, kanban, orchestration +linkTitle: "Kanban Board" +weight: 15 +canonical: https://docs.docker.com/ai/docker-agent/features/board/ +--- + +_Board is a Kanban TUI for orchestrating agents. Each card launches an agent +in a tmux session on an isolated git worktree, and moving a card forward +through the pipeline sends the destination column's prompt to its agent._ + +## Launching the board + +```bash +$ docker agent board +``` + +Requirements: `tmux` and `git` must be installed. + +## How it works + +- **Cards run agents.** Creating a card (`n`) launches `docker agent run` in + a dedicated tmux session, working in a fresh git worktree branched from the + project's upstream default branch. The card's title, running/idle status, + and failures are mirrored live from the agent's control plane. +- **Startup phases.** While an agent is coming up its card moves through three + intermediate statuses before reaching **running**: `starting` (tmux session + created, process booting, no worktree yet) → `loading` (worktree present; + agent loading config, models, and tools) → `attaching` (control-plane socket + bound; board waiting for the first snapshot). +- **Columns are a pipeline.** The default pipeline is + Dev → Review → Push → Done, and it's fully customizable: manage columns + from the board (`c`) or in the config file. Moving a card forward (`]`) + sends the destination column's prompt to the card's agent; moving it back + (`[`) sends nothing. +- **Attach anytime.** Press `enter` (or double-click a card) to attach your + terminal to the agent's session and interact with it directly; `ctrl+q` + detaches and returns to the board. +- **Everything is recoverable.** Quitting the board leaves agents running in + tmux; restarting it reattaches to them. If an agent process dies, the board + relaunches it and resumes the same conversation and worktree. An agent that + keeps crashing at startup turns its card red instead of relaunching + forever: attach to it (`enter`) to read the error output, then move the + card forward to relaunch it, or delete it. + +## Key bindings + +| Key | Action | +| ------------- | --------------------------------------------------- | +| `n` | Create a card (project + prompt) | +| `enter` | Attach to the card's agent (`ctrl+q` detaches) | +| `d` | View the card's worktree diff | +| `o` | Open the card's worktree in `$DOCKER_AGENT_BOARD_EDITOR` (`code`) | +| `s` | Open an interactive shell in the card's worktree | +| `[` / `]` | Move the card back / forward | +| `1`-`9` | Move the card to column N | +| `x` | Delete the card, its session, worktree, and branch | +| `p` | Manage projects (add, edit, reorder, remove) | +| `c` | Manage columns (add, edit, reorder, remove) | +| `e` | Edit the selected column's prompt | +| `←↓↑→` `hjkl` | Navigate | +| mouse | Click selects, double-click attaches, drag moves, wheel scrolls | +| `?` | Help | +| `q` | Quit (agents keep running) | + +## Configuration + +Everything is configured in the global config file +(`~/.config/cagent/config.yaml`) or through the TUI itself (`p` for projects, +`c` for columns, `e` for column prompts): + +```yaml +board: + projects: + - name: my-app + path: /Users/me/src/my-app + agent: coder # any agent ref; defaults to the built-in agent + columns: + - id: dev + name: Dev + emoji: 🔨 + - id: review + name: Review + emoji: 🔍 + prompt: Review the local changes and fix any issues you find. + - id: done + name: Done + emoji: ✅ +``` + +Omitting `columns` keeps the default pipeline. Column `id`s identify a +column across renames (cards remember the column they are in by id); when +omitted, the id is derived from the column's name. When a card enters a +column with a `prompt`, that prompt is delivered to the card's agent as its +next message. diff --git a/_vendor/github.com/docker/docker-agent/docs/features/cli/index.md b/_vendor/github.com/docker/docker-agent/docs/features/cli/index.md index 66e6954ed830..1105a3ec1fac 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/cli/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/cli/index.md @@ -3,6 +3,7 @@ title: "CLI Reference" description: "Complete reference for all docker-agent command-line commands and flags." keywords: docker agent, ai agents, features, cli reference weight: 30 +canonical: https://docs.docker.com/ai/docker-agent/features/cli/ aliases: - /ai/docker-agent/reference/cli/ --- @@ -27,10 +28,10 @@ $ docker agent run [config] [message...] [flags] | Flag | Description | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `-a, --agent ` | Run a specific agent from the config | -| `--yolo` | Auto-approve all tool calls | +| `--yolo` | Auto-approve tool calls (unless explicitly denied) | | `--model ` | Override model(s). Use `provider/model` for all agents, or `agent=provider/model` for specific agents. Comma-separate multiple overrides. | | `--session ` | Resume a previous session. Supports relative refs (`-1` = last, `-2` = second to last). An explicit ID that does not exist yet is created with that ID, so a supervisor can own the session ID upfront and reuse it across runs. | -| `-s, --session-db ` | Path to the SQLite session database (default: `~/.cagent/session.db`) | +| `-s, --session-db ` | Path to the SQLite session database (default: `/session.db`, so `~/.cagent/session.db` unless `--data-dir` is set) | | `--session-read-only` | Open the TUI in read-only mode: conversation history is displayed but no new messages can be sent to the LLM. Cannot be used with `--exec`. | | `--prompt-file ` | Include file contents as additional system context (repeatable) | | `--attach ` | Attach an image file to the initial message | @@ -41,7 +42,7 @@ $ docker agent run [config] [message...] [flags] | `--app-name ` | Override the application name label shown in the TUI (status bar, window title, "/exit" notifications). | | `--sidebar` | Control sidebar visibility. Set to `--sidebar=false` to hide the sidebar and disable the Ctrl+B toggle (default: `true`). | | `--disable-commands ` | Hide and disable specific slash commands in the TUI. Accepts a comma-separated list of command names (leading slash optional, case-insensitive). E.g. `--disable-commands="/cost,/eval,/model"`. | -| `--theme ` | Preselect a TUI theme by name (overrides the theme from user config; ignored outside the interactive TUI) | +| `--theme ` | Preselect a TUI theme by name, or `auto` to follow the terminal's light/dark background (overrides the theme from user config; ignored outside the interactive TUI) | | `--on-event =` | Run a shell command when an event of the given type fires (`*=` matches any event). Repeatable. | | `--json` | Output results as newline-delimited JSON (use with `--exec`) | | `--hide-tool-calls` | Hide tool calls in the output | @@ -50,7 +51,7 @@ $ docker agent run [config] [message...] [flags] | `--template ` | Template image for the sandbox (default: `docker/sandbox-templates:docker-agent`) | | `--sbx` | Prefer the `sbx` CLI backend when available (default `true`; set `--sbx=false` to force `docker sandbox`) | | `--no-kit` | Disable the [auto-kit](../../configuration/sandbox/index.md#auto-kit): do not stage skills or prompt files into the sandbox | -| `--agent-picker [refs]` | Show a full-screen interactive picker before launching, letting you browse and select an agent. Accepts an optional comma-separated list of agent references to show (defaults to `default,coder`). Arrow keys navigate; `?` toggles the YAML preview panel; Enter confirms. Not available in `--exec` or non-TTY modes. | +| `--agent-picker [refs]` | Show a full-screen interactive picker before launching, letting you browse and select an agent. Accepts an optional comma-separated list of agent references to show (defaults to the built-in `default` and `coder` agents plus any agent configs found in `~/.agents`). Arrow keys navigate; `?` toggles the YAML preview panel; `l` (or mouse-click) toggles the **Lean Mode** checkbox to launch in the lean TUI; `b` (or clicking **[ Open Board ]**) opens the Kanban board (`docker agent board`) instead of running an agent; Enter confirms. Not available in `--exec` or non-TTY modes. | | `-w, --worktree [name]` | Run the agent in a fresh git worktree of the working directory, isolating its changes from your checkout. Optionally name it (`--worktree=my-feature`); otherwise a name is generated. Requires the working directory to be inside a git repository. Every tool (the shell included) runs inside the worktree. Combine with `--working-dir` to branch from another repository, and with `--session` to resume into the same worktree later. Cannot be combined with `--remote` or `--sandbox`. When the session ends, a clean worktree is removed automatically; one with work prompts to keep or remove (never in `--exec`). | | `--worktree-base ` | Branch the `--worktree` from `` (a branch, tag, commit, or remote-tracking ref like `origin/main`) instead of the current `HEAD`. A remote-tracking ref is fetched first so the worktree starts from the latest remote state. Requires `--worktree`; cannot be combined with `--worktree-pr`, `--remote`, or `--sandbox`. | | `--worktree-pr ` | Run the agent in a git worktree checked out on an existing GitHub pull request (PR number, `#123`, or PR URL). Continues the PR's branch so commits push back to it. Requires the [GitHub CLI](https://cli.github.com/) (`gh`). Cannot be combined with `--worktree`, `--remote`, or `--sandbox`. | @@ -66,7 +67,7 @@ $ docker agent run [config] [message...] [flags] | `--hook-stop ` | Add a stop hook command, fired when the model finishes responding (repeatable) | | `--fake ` | Replay AI responses from a cassette file (for testing). Mutually exclusive with `--record`. | | `--fake-stream [ms]` | When replaying with `--fake`, simulate streaming with a delay between chunks (defaults to 15ms when given without a value). | -| `--record [path]` | Record AI API interactions to a cassette file (auto-generates filename if no path given) | +| `--record [path]` | Record AI API interactions to a cassette file and generate a TUI e2e test from the session (auto-generates filename if no path given). Routes through `--models-gateway` when one is configured. | | `-d, --debug` | Enable debug logging | | `--log-file ` | Custom debug log location | | `-o, --otel` | Enable OpenTelemetry observability: traces, metrics, and logs. Requires `OTEL_EXPORTER_OTLP_ENDPOINT` to export to a collector. | @@ -198,6 +199,57 @@ $ docker agent models --provider openai $ docker agent models --format json | jq ``` +### `docker agent toolsets` + +List the built-in toolset types available for use in an agent configuration. Each type can be referenced under `toolsets:` in an agent YAML file. Use this to discover what's available without leaving the terminal. + +```bash +$ docker agent toolsets [flags] +``` + +| Flag | Default | Description | +| ---------------- | ------- | --------------------------------- | +| `--format ` | `table` | Output format: `table` or `json`. | + +```bash +# Examples +$ docker agent toolsets # human-readable table +$ docker agent toolsets --format json | jq # machine-readable (type, summary, docs URL) +``` + +### `docker agent setup` + +Set up a model interactively. Three paths: pick a cloud provider, paste its API key, and choose where to store it (macOS Keychain, `pass`, or the docker agent env file `~/.config/cagent/.env`); check Docker Model Runner and pull a local model (no API key needed); or register a custom OpenAI-compatible provider (endpoint URL, API format, and API key variable) saved to your [user configuration](../../providers/custom/index.md#global-providers-user-configuration) so its models work everywhere via `--model /`. Ends with the exact command to start chatting. Secret values are never printed. + +The wizard is also offered automatically when an interactive run finds no usable model (decline-able; set `DOCKER_AGENT_NO_SETUP=1` to suppress the offer). + +```bash +$ docker agent setup +``` + +### `docker agent doctor` + +Diagnose the model and credential setup. Reports which model providers have credentials and where each credential comes from (shell environment, env file, pass, keychain, …), whether Docker Model Runner is reachable and which models are pulled, and which model the `auto` selection would pick. Secret values are never printed. Exits with a non-zero status when an issue would prevent an agent from running, which makes it usable in scripts and CI. + +```bash +$ docker agent doctor [agent-file|registry-ref] [flags] +``` + +With an agent file, also lists the environment variables that file requires (model credentials and tool secrets such as `GITHUB_PERSONAL_ACCESS_TOKEN`), whether each one is set, and from which source. + +| Flag | Default | Description | +| ------------------------ | ------- | -------------------------------------------------------------- | +| `--json` | `false` | Output the full report in JSON format (for scripting). | +| `--env-from-file ` | (none) | Also check variables supplied by an env file. | +| `--models-gateway ` | (none) | Diagnose against a models gateway (credentials come from it). | + +```bash +# Examples +$ docker agent doctor # credential, DMR, and auto-selection state +$ docker agent doctor ./agent.yaml # also check that file's requirements +$ docker agent doctor --json | jq .issues +``` + ### `docker agent serve api` Start the HTTP API server for programmatic access. The argument can be a single agent file, a registry reference, or a directory — when given a directory, every `.yaml`/`.yml`/`.hcl` file in it is exposed as a separate entry under `/api/agents`. @@ -213,7 +265,7 @@ $ docker agent serve api || [flags] | `-s, --session-db ` | `session.db` | Path to the SQLite session database (relative paths resolve against the working directory). | | `--pull-interval `| `0` | Periodically re-pull OCI/URL references and refresh the agent definition. `0` disables auto-pull. | | `--fake ` | (none) | Replay AI responses from a cassette file (for testing). Mutually exclusive with `--record`. | -| `--record [path]` | (none) | Record AI API interactions to a cassette file. | +| `--record [path]` | (none) | Record AI API interactions to a cassette file. Routes through `--models-gateway` when one is configured. | | `--mcp-oauth-redirect-uri ` | (none) | OAuth redirect URI for the unmanaged MCP OAuth flow in server mode. When set, the runtime drives PKCE and code exchange in-process and sends the full authorize URL to the client via elicitation. See [Remote MCP](../remote-mcp/index.md) for details. | > **Diagnostics:** Set `CAGENT_PPROF_ADDR=127.0.0.1:6060` (or `--pprof-addr`, a hidden flag) to start a live Go pprof server at `/debug/pprof/`. Use a loopback address; a non-loopback binding logs a security warning. @@ -271,6 +323,7 @@ $ docker agent serve a2a [flags] | ---------------------- | ------------------ | ------------------------------------------------------------------------------------------ | | `-a, --agent ` | (team default) | Name of the agent to run. Defaults to the team's first agent if not specified. | | `-l, --listen ` | `127.0.0.1:8082` | Address to listen on. | +| `-s, --session-db ` | `/session.db` | Path to the SQLite session database. | All [runtime configuration flags](#runtime-configuration-flags) are also accepted. @@ -291,7 +344,7 @@ $ docker agent serve acp [flags] | Flag | Default | Description | | ------------------------- | --------------------------- | ------------------------------------------------- | -| `-s, --session-db ` | `~/.cagent/session.db` | Path to the SQLite session database. | +| `-s, --session-db ` | `/session.db` | Path to the SQLite session database. | All [runtime configuration flags](#runtime-configuration-flags) are also accepted. @@ -340,6 +393,18 @@ $ curl http://127.0.0.1:8083/v1/chat/completions \ See [Chat Server](../chat-server/index.md) for the full feature reference. +### `docker agent board` + +Launch a full-screen Kanban TUI for orchestrating multiple agents at once. Each card runs an agent in its own tmux session on an isolated git worktree; moving a card forward through the pipeline (Dev → Review → Push → Done) delivers the destination column's prompt to that card's agent. Projects and column prompts are stored in the global config file (`~/.config/cagent/config.yaml`) and can be managed from the TUI. + +```bash +$ docker agent board +``` + +Takes no arguments or flags. Requires `tmux` and `git` to be installed. + +See [Kanban Board](../board/index.md) for key bindings, configuration, and workflow details. + ### `docker agent share push` / `docker agent share pull` Share agents via OCI registries. @@ -432,7 +497,7 @@ $ docker agent run yolo-coder **Alias Options:** Aliases can include runtime options that apply automatically when used: -- `--yolo` — Auto-approve all tool calls when running the alias +- `--yolo` — Auto-approve tool calls (unless explicitly denied) when running the alias - `--model ` — Override the model for the alias - `--hide-tool-results` — Hide tool call results in the TUI when running the alias - `--sandbox` — Always run the alias inside a [Docker sandbox](../../configuration/sandbox/index.md) @@ -522,8 +587,8 @@ These flags are available on every `docker agent` command: | `--log-file ` | Custom debug log location (only used with `--debug`) | | `-o, --otel` | Enable OpenTelemetry observability: traces, metrics, and logs. Requires `OTEL_EXPORTER_OTLP_ENDPOINT` to export to a collector. | | `--cache-dir ` | Override the cache directory (default: `~/Library/Caches/cagent` on macOS) | -| `--config-dir ` | Override the config directory (default: `~/.config/cagent`) | -| `--data-dir ` | Override the data directory (default: `~/.cagent`) | +| `--config-dir ` | Override the config directory (default: `~/.config/cagent`). Also reads `DOCKER_AGENT_CONFIG_DIR` (legacy `CAGENT_CONFIG_DIR`) env var. | +| `--data-dir ` | Override the data directory (default: `~/.cagent`; holds `session.db`, worktrees, plans, …) | | `--help` | Show help for any command | ### OpenTelemetry environment variables diff --git a/_vendor/github.com/docker/docker-agent/docs/features/remote-mcp/index.md b/_vendor/github.com/docker/docker-agent/docs/features/remote-mcp/index.md index 87d29c7b0fa7..2de5640871d6 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/remote-mcp/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/remote-mcp/index.md @@ -3,13 +3,14 @@ title: "Remote MCP Servers" description: "Connect docker-agent to cloud services via remote MCP servers with built-in OAuth authentication." keywords: docker agent, ai agents, features, remote mcp servers weight: 120 +canonical: https://docs.docker.com/ai/docker-agent/features/remote-mcp/ --- _Connect docker-agent to cloud services via remote MCP servers with built-in OAuth authentication._ ## Overview -Docker Agent supports connecting to remote MCP servers over **Streamable HTTP** and **SSE** (Server-Sent Events) transports. Streamable HTTP is the current recommended transport for most hosted MCP servers. Many popular services offer MCP endpoints with OAuth — docker-agent handles the authentication flow automatically. +Docker Agent supports connecting to remote MCP servers over **Streamable HTTP**, **SSE** (Server-Sent Events), and **Unix domain sockets**. Streamable HTTP is the current recommended transport for most hosted MCP servers. Many popular services offer MCP endpoints with OAuth — docker-agent handles the authentication flow automatically. ```yaml toolsets: @@ -19,6 +20,20 @@ toolsets: transport_type: "streamable" ``` +## Unix Domain Sockets + +Use a `unix://` URL to connect to an MCP server listening on a local Unix socket. This is useful when running docker-agent inside a container and exposing an MCP server from the host via a bind-mounted socket: + +```yaml +toolsets: + - type: mcp + remote: + url: "unix:///tmp/mcp-notify.sock" + transport_type: "streamable" +``` + +The path after `unix://` is the absolute path to the socket file. Configured `headers` are forwarded over the socket connection. OAuth discovery is not supported for Unix socket URLs. + > [!TIP] > **OAuth flow** > @@ -38,7 +53,7 @@ toolsets: url: "https://mcp.example.com/mcp" transport_type: "streamable" # or "sse" for legacy servers headers: - Authorization: "Bearer token" # optional: static auth + Authorization: "Bearer ${env.MY_TOKEN}" # resolved per request # Optional: use only for trusted internal/private MCP or OAuth endpoints. allow_private_ips: true ``` @@ -52,6 +67,14 @@ Set `allow_private_ips: true` on a remote MCP toolset only when the MCP server o > > Configured `headers` are forwarded to OAuth protected-resource-metadata discovery requests directed at the MCP server's own host — not to third-party authorization servers. This allows services like Grafana Cloud that require a routing header (e.g. `X-Grafana-URL`) on the discovery request to scope the OAuth flow correctly. Headers are never sent to a different host than the one in `remote.url`. +> [!NOTE] +> **Per-request header template expansion** +> +> Header values in `remote.headers` support `${env.VAR}` and `${headers.NAME}` placeholders. Both are resolved on every outbound HTTP request (not just once at initialization), so short-lived credentials and forwarded caller headers always reflect the latest values: +> +> - `${env.VAR}` — reads the named environment variable. Useful for credentials stored in a secret manager that rotates them in-process. +> - `${headers.NAME}` — forwards the named header from the caller's incoming HTTP request. Only meaningful when docker-agent is running as an API server (`docker agent serve api`) and a client passes authentication headers that the upstream MCP server also accepts. + > [!NOTE] > **Automatic reconnection after idle timeouts** > @@ -71,7 +94,10 @@ Set `allow_private_ips: true` on a remote MCP toolset only when the MCP server o Most remote MCP servers that require OAuth support [Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) — no configuration is needed, docker-agent handles the flow for you. -For servers that do **not** support DCR, provide explicit OAuth credentials with the `oauth:` block: +For servers that do **not** support DCR, docker-agent falls back automatically: + +1. **Interactive credential prompt**: docker-agent presents a dialog asking for your `client_id` (required) and optionally a `client_secret`. This covers servers that require pre-registered app credentials but don't advertise them via DCR. +2. **Explicit `oauth:` block** (recommended when you know the credentials in advance): add the block described below to skip the interactive prompt and supply credentials directly in config. ```yaml toolsets: diff --git a/_vendor/github.com/docker/docker-agent/docs/features/skills/index.md b/_vendor/github.com/docker/docker-agent/docs/features/skills/index.md index c76101ea7c44..92bb74ca1bce 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/skills/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/skills/index.md @@ -3,6 +3,7 @@ title: "Skills" description: "Skills provide specialized instructions that agents can load on demand when a task matches a skill's description." keywords: docker agent, ai agents, features, skills weight: 110 +canonical: https://docs.docker.com/ai/docker-agent/features/skills/ --- _Skills provide specialized instructions that agents can load on demand when a task matches a skill's description._ @@ -311,6 +312,7 @@ Skills are discovered from these locations (later overrides earlier): | Path | Search Type | | ----------------- | ------------------------------------------ | | `.claude/skills/` | Flat (cwd only) | +| `.github/skills/` | Flat (each directory from git root to cwd) | | `.agents/skills/` | Flat (each directory from git root to cwd) | ## Invoking Skills @@ -336,6 +338,7 @@ When multiple skills share the same name: 1. Global skills load first 2. Project skills load next, from git root toward current directory 3. Skills closer to the current directory override those further away +4. At the same directory level, `.agents/skills/` overrides `.github/skills/` ## Skills in Sandbox Mode diff --git a/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md b/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md index 922b11059588..c42809206d33 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md @@ -136,6 +136,36 @@ The **effort gauge** is a fixed-width six-cell indicator (`▰` filled, `▱` em Harness-backed agents (e.g. `claude-code`) show the harness type as their model and no thinking gauge. Press **Shift+Tab** to cycle the current model's thinking-effort level; a `✻ Thinking: ` toast confirms the change (useful when the sidebar is hidden). +### Agent Delegation Feedback + +When a parent agent calls `transfer_task` to delegate work to a sub-agent, the TUI provides live visual feedback in both the sidebar and the chat. + +**Sidebar — Transfer box:** As soon as the delegation starts, an animated **Transfer** box appears below the agent roster, showing the direction of the handoff with a traveling dot: + +```text +╭─ Transfer ─────────────────╮ +│ parent ●──────► child │ +╰────────────────────────────╯ +``` + +The box stays visible for at least 1.5 seconds. Once the sub-agent produces its first message, reasoning, or tool output, the box hides (still honoring the minimum window) to keep the sidebar focused on the active agent. If the sub-agent is slow or silent, the box hides after a 3-second maximum cutoff. The header shows a `↔` marker while any delegation is still in flight, even after the box hides. + +**Sidebar — Return box:** When the sub-agent finishes and control returns to the parent, a brief **Return** box animates the reverse direction for up to 1.5 seconds, then disappears: + +```text +╭─ Return ───────────────────╮ +│ child ●──────► parent │ +╰────────────────────────────╯ +``` + +**Chat — return transition:** Alongside the sidebar Return animation, the chat shows a one-line static transition between the two agent badges: + +```text +[child] returned control to [parent] +``` + +This transition is not persisted — it does not reappear when you reload the session. + ### Thinking and Tool Details Reasoning/thinking blocks are collapsed by default and carry a `Thinking` header badge. When collapsed, the TUI shows a short preview and compact tool summaries. Expand a block to see the full thinking content and the real tool renderers, including detailed tool output such as file edit diffs. diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/go-sdk/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/go-sdk/index.md index ede2272bc283..11ae69989487 100644 --- a/_vendor/github.com/docker/docker-agent/docs/guides/go-sdk/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/guides/go-sdk/index.md @@ -3,6 +3,7 @@ title: "Go SDK" description: "Use docker-agent as a Go library to embed AI agents in your applications." keywords: docker agent, ai agents, guides, go sdk weight: 40 +canonical: https://docs.docker.com/ai/docker-agent/guides/go-sdk/ --- _Use docker-agent as a Go library to embed AI agents in your applications._ @@ -128,6 +129,23 @@ if err := chat.Restart(); err != nil { For advanced use (custom elicitation, raw event inspection), call `chat.Runtime()` to access the underlying `runtime.Runtime` directly. +> [!WARNING] +> **Breaking change: `Runtime.ResumeElicitation` (#3584)** +> +> `Runtime.ResumeElicitation` gained an `elicitationID` parameter so responses can +> be correlated with a specific concurrent elicitation request (needed once +> multiple background jobs can be eliciting input at the same time). It is +> declared **variadic** (`elicitationID ...string`) specifically so existing +> *callers* of the 3-argument form keep compiling unchanged — `rt.ResumeElicitation(ctx, action, content)` +> still works and falls back to resolving the sole pending request. +> +> If you implement your own `runtime.Runtime` (rather than embedding +> `runtime.LocalRuntime`/`runtime.RemoteRuntime`), you do need to update your +> method's signature to match, and also add an `OnElicitationRequest(handler +> func(runtime.Event))` method (a no-op is fine if your runtime never raises +> elicitations) — both are required interface methods, matching the existing +> no-op-able pattern already used by `OnToolsChanged`/`OnBackgroundEvent`. + ## Optional Provider Build Tags By default docker-agent includes all four cloud providers (OpenAI, Anthropic, Google, Amazon Bedrock). When embedding docker-agent in your own binary you can compile out unneeded providers — together with their transitive SDK dependencies — to reduce binary size. diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/thinking/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/thinking/index.md index 0464aece6385..1e43db54627c 100644 --- a/_vendor/github.com/docker/docker-agent/docs/guides/thinking/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/guides/thinking/index.md @@ -3,6 +3,7 @@ title: "Thinking / Reasoning" description: "Control how much a model reasons before responding. Works across OpenAI, Anthropic, Google Gemini, AWS Bedrock, and Docker Model Runner." keywords: docker agent, ai agents, guides, thinking / reasoning weight: 20 +canonical: https://docs.docker.com/ai/docker-agent/guides/thinking/ --- _Control how much a model reasons before responding. Works across OpenAI, Anthropic, Google Gemini, AWS Bedrock, and Docker Model Runner._ @@ -22,7 +23,7 @@ docker-agent exposes this through a single `thinking_budget` field on any named | Provider | Format | Values | Default | | ------------------- | ---------- | --------------------------------------------------------------------------------------- | ------------------ | -| OpenAI | string | `minimal`, `low`, `medium`, `high`, `none`; `xhigh` on gpt-5.2+ only | `medium` (API default) | +| OpenAI | string | `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`; `xhigh` on gpt-5.2+, `none`/`max` on gpt-5.6+ only, `minimal` dropped on gpt-5.6+ | `medium` (API default) | | Anthropic | int or str | 1024–32768 tokens, or `minimal`–`max`, `adaptive`, `adaptive/`, `none` | off | | Gemini 2.5 | int | `0` (off), `-1` (dynamic), or token count (max 24576 / 32768) | `-1` (dynamic) | | Gemini 3 | string | `minimal`, `low`, `medium`, `high` | API default (model-dependent) | @@ -35,33 +36,34 @@ String values are case-insensitive. The full set of accepted strings is `none`, ## OpenAI -OpenAI reasoning models (o-series, gpt-5, gpt-5-mini) use a string effort level that maps to their `reasoning_effort` API parameter. The `xhigh` level is only accepted by gpt-5.2 and later minor versions; o-series and earlier gpt-5 releases top out at `high`. +OpenAI reasoning models (o-series, gpt-5, gpt-5-mini, gpt-5.6 family) use a string effort level that maps to their `reasoning_effort` API parameter. The `xhigh` level requires gpt-5.2+; `none` and `max` require gpt-5.6+ (Sol/Terra/Luna); `minimal` is dropped on gpt-5.6+. ```yaml models: gpt-thinker: provider: openai - model: gpt-5-mini - thinking_budget: high # minimal | low | medium | high | xhigh + model: gpt-5.6 + thinking_budget: high # none | minimal | low | medium | high | xhigh | max ``` **Effort levels:** | Level | Description | | --------- | -------------------------------------------------------- | -| `none` | Don't request extra reasoning (alias for `0`); the API's own default still applies. | -| `minimal` | Fastest; lightest reasoning pass. | +| `none` | No reasoning. Sent as-is on gpt-5.6+ (a real API value); on older models it just disables the local `thinking_budget` (the API's own default still applies). | +| `minimal` | Fastest; lightest reasoning pass. Not accepted on gpt-5.6+ (dropped from the API). | | `low` | Quick reasoning for straightforward tasks. | | `medium` | Balanced default. | | `high` | More thorough; recommended for complex tasks. | -| `xhigh` | Near-maximum effort; slower but most accurate. | +| `xhigh` | Near-maximum effort; slower but most accurate. Requires gpt-5.2+. | +| `max` | Maximum effort. Requires gpt-5.6+. | -These effort levels (`minimal`–`xhigh`) are the **only** values accepted for OpenAI. Token counts, `max`, `adaptive`, and `adaptive/` are rejected with a configuration error at request time. The `xhigh` level is only supported by gpt-5.2 and later minor versions (e.g. gpt-5.2, gpt-5.4-mini); o-series and earlier gpt-5 releases top out at `high`. Older models (o1, o3-mini) only accept `low`/`medium`/`high` — sending an unsupported level returns an API error. +Token counts, `adaptive`, and `adaptive/` are rejected with a configuration error at request time. `xhigh` is only supported by gpt-5.2 and later minor versions (e.g. gpt-5.2, gpt-5.4-mini); `none` and `max` are only supported by gpt-5.6 and later (Sol/Terra/Luna); `minimal` is not accepted on gpt-5.6+. Older models (o1, o3-mini) only accept `low`/`medium`/`high` — sending an unsupported level returns an API error. > [!WARNING] > **Tokens and max_tokens** > -> OpenAI reasoning models always reason internally — even with `thinking_budget: none` there are hidden reasoning tokens that count against `max_tokens`. docker-agent automatically raises the output-token floor for its internal low-effort calls (e.g. title generation) so hidden reasoning cannot starve visible text output. +> Older OpenAI reasoning models always reason internally — even with `thinking_budget: none` there are hidden reasoning tokens that count against `max_tokens`. On gpt-5.6+ (Sol/Terra/Luna), `none` is a real API value that genuinely disables reasoning. docker-agent automatically raises the output-token floor for its internal low-effort calls (e.g. title generation) so hidden reasoning cannot starve visible text output. ## Anthropic @@ -310,7 +312,7 @@ models: thinking_budget: 0 ``` -`none` and `0` clear docker-agent's thinking configuration — no thinking parameter is sent. Models that always reason (OpenAI o-series, gpt-5, Gemini 3) then fall back to the API's default behavior and still reason internally; only models with optional thinking (Gemini 2.5, Claude, local models) are fully disabled. +`none` and `0` clear docker-agent's thinking configuration — no thinking parameter is sent. Models that always reason (OpenAI o-series, gpt-5 through gpt-5.5, Gemini 3) then fall back to the API's default behavior and still reason internally; gpt-5.6+ (Sol/Terra/Luna) sends `none` as a real API value that genuinely disables reasoning. Models with optional thinking (Gemini 2.5, Claude, local models) are also fully disabled. ## Choosing an Effort Level @@ -325,9 +327,9 @@ models: ## Changing Thinking Level at Runtime -While running in the TUI, press **Shift+Tab** to cycle the thinking effort level for the current model without editing your YAML config, or type `/effort ` to jump straight to a specific level (e.g. `/effort high`): +While running in the TUI, press **Shift+Tab** to cycle the thinking effort level for the current model without editing your YAML config, or type `/effort ` to jump straight to a specific level (e.g. `/effort high`). Running `/effort` without an argument opens a picker listing the levels the current model supports: -- The level steps through the model's supported range (model-specific), wrapping around — for example `none → minimal → low → medium → high → none` on OpenAI gpt-5/o-series, `none → minimal → low → medium → high → xhigh → none` on gpt-5.2+, `none → low → medium → high → max → none` on Anthropic Opus 4.6 and Sonnet 4.6, and `none → low → medium → high → xhigh → max → none` on Anthropic Opus 4.7+, Fable 5, and Mythos 5. For older Anthropic models (e.g. Sonnet 4.5) that only accept token budgets, effort-string cycling has no effect — use an integer `thinking_budget` in your YAML config instead. +- The level steps through the model's supported range (model-specific), wrapping around — for example `none → minimal → low → medium → high → none` on OpenAI gpt-5/o-series, `none → minimal → low → medium → high → xhigh → none` on gpt-5.2+, `none → low → medium → high → xhigh → max → none` on gpt-5.6+ (no `minimal`), `none → low → medium → high → max → none` on Anthropic Opus 4.6 and Sonnet 4.6, and `none → low → medium → high → xhigh → max → none` on Anthropic Opus 4.7+, Fable 5, and Mythos 5. For older Anthropic models (e.g. Sonnet 4.5) that only accept token budgets, effort-string cycling has no effect — use an integer `thinking_budget` in your YAML config instead. - The current level is shown in the sidebar next to the model name (e.g. `openai/gpt-5 • high`). - This applies as a session override — it is **not** saved to the config file. The next session starts from the level defined in your YAML. - For models that don't support reasoning, and for remote runtimes, Shift+Tab is a no-op and an informational message is displayed. diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/chatgpt/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/chatgpt/index.md new file mode 100644 index 000000000000..d911d179701f --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/chatgpt/index.md @@ -0,0 +1,128 @@ +--- +title: "ChatGPT (OpenAI account)" +description: "Use your ChatGPT Plus/Pro/Business subscription with docker-agent by signing in with your OpenAI account, no API key needed." +keywords: docker agent, ai agents, model providers, llm, chatgpt, openai, codex, subscription +weight: 55 +canonical: https://docs.docker.com/ai/docker-agent/providers/chatgpt/ +--- + +_Use your ChatGPT subscription with docker-agent by signing in with your OpenAI account. No API key needed._ + +## Overview + +The `chatgpt` provider authenticates with a ChatGPT account (the same +"Sign in with ChatGPT" flow used by OpenAI's Codex CLI) instead of an +`OPENAI_API_KEY`. Usage is billed against your ChatGPT Plus, Pro, or +Business plan rather than pay-per-token API credits. + +Under the hood, docker-agent talks to the ChatGPT Codex backend +(`https://chatgpt.com/backend-api/codex`), which serves the `gpt-5` model +family over the OpenAI Responses API. GPT-5.6 (Sol/Terra/Luna) is served +there too; GPT-5.2 and GPT-5.3-Codex are deprecated for ChatGPT sign-in. + +## Prerequisites + +- A paid **ChatGPT** subscription (Plus, Pro, or Business). +- A browser on the machine running the sign-in (the OAuth flow uses a + fixed `localhost:1455` callback). + +## Sign In + +```bash +docker agent setup +``` + +Pick **chatgpt** in the provider list: instead of asking for an API key, the +wizard opens your browser on the ChatGPT sign-in page and stores the +resulting OAuth credential in the docker-agent config directory +(`~/.config/cagent/chatgpt-auth.json`, owner-only permissions). The access +token is refreshed automatically; you only need to sign in again if the +refresh token is revoked. + +Related commands: + +```bash +docker agent doctor # the chatgpt row shows the credential state +rm ~/.config/cagent/chatgpt-auth.json # sign out (remove the stored sign-in) +``` + +## Configuration + +### Inline + +```yaml +agents: + root: + model: chatgpt/gpt-5.6 + instruction: You are a helpful assistant. +``` + +### Named model + +```yaml +models: + gpt: + provider: chatgpt + model: gpt-5.6 + thinking_budget: medium + +agents: + root: + model: gpt +``` + +## Available Models + +The Codex backend serves the models available to your ChatGPT plan, +typically: + +| Model | Best For | +| -------------------- | -------------------------------------- | +| `gpt-5.6` | Alias for `gpt-5.6-sol`; general purpose, strong reasoning | +| `gpt-5.6-sol` | Frontier model, most capable | +| `gpt-5.6-terra` | Everyday workhorse | +| `gpt-5.6-luna` | High-volume, cost-efficient | +| `gpt-5.2` | Deprecated for ChatGPT sign-in | +| `gpt-5.2-codex` | Deprecated for ChatGPT sign-in | + +The effort picker exposes Low/Medium/High/XHigh/Max on the GPT-5.6 family +(no Minimal). + +## How It Works + +- **Auth:** the `docker agent setup` sign-in runs an OAuth 2.0 + authorization-code + PKCE flow against `auth.openai.com`. The stored login + is exposed to credential checks (doctor, `first_available`, auto model + selection) as the virtual `CHATGPT_OAUTH_TOKEN` variable. +- **API:** requests go to the Responses API only; the backend has no Chat + Completions endpoint, so `api_type` is pinned automatically. +- **Request shape:** the backend requires stateless requests (`store: false`) + and a top-level `instructions` field, so docker-agent moves system messages + there. Client-side sampling parameters (`temperature`, `top_p`, + `max_tokens`) are not supported by the backend and are dropped. + +## Setting the Token Explicitly + +`CHATGPT_OAUTH_TOKEN` can also be set like any other credential (shell +environment, `--env-from-file`, keychain, ...). An explicitly set value takes +precedence over the stored sign-in. This is useful for short-lived CI runs +with a pre-minted access token, but note that such a token expires and is not +refreshed. + +## ChatGPT Subscription vs. OpenAI API Key + +| | `chatgpt` | `openai` | +| --- | --- | --- | +| Credential | ChatGPT account sign-in | `OPENAI_API_KEY` | +| Billing | Included in the ChatGPT plan (rate-limited) | Pay per token | +| Models | `gpt-5` family served by the Codex backend | Full OpenAI API catalog | +| Sampling controls (`temperature`, ...) | Not supported | Supported | +| Embeddings / reranking | Not supported | Supported | + +When both credentials are configured, automatic model selection prefers +`openai`; pin `--model chatgpt/gpt-5.6` (or use a named model) to use the +subscription. + +> [!NOTE] +> Use of the Codex backend is governed by OpenAI's terms for ChatGPT and +> Codex. Sign-in is per user; do not share the stored credential. diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/custom/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/custom/index.md index 240acddb60e1..a56534cbd423 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/custom/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/custom/index.md @@ -3,6 +3,7 @@ title: "Provider Definitions" description: "Define reusable provider configurations with shared defaults for any provider type — OpenAI, Anthropic, Google, Bedrock, and more." keywords: docker agent, ai agents, model providers, llm, provider definitions weight: 280 +canonical: https://docs.docker.com/ai/docker-agent/providers/custom/ --- _Define reusable provider configurations with shared defaults for any provider type — OpenAI, Anthropic, Google, Bedrock, and more._ @@ -254,6 +255,44 @@ agents: model: fast_openai/gpt-4o-mini ``` +## Global Providers (User Configuration) + +Providers defined in an agent file only apply to that file. To make a custom +provider available to every command (`docker agent run`, `new`, `models`, ...), +define it once in your user configuration (`~/.config/cagent/config.yaml`) +under the same `providers` key: + +```yaml +# ~/.config/cagent/config.yaml +providers: + myprovider: + base_url: https://llm.corp.example.com/v1 + api_type: openai_chatcompletions + token_key: MYPROVIDER_API_KEY +``` + +The easiest way to register one is the interactive wizard: + +```bash +docker agent setup +# pick "3. OpenAI-compatible provider", then enter the endpoint, +# API format, and the environment variable holding the API key +``` + +Once registered, the provider works everywhere: + +```bash +docker agent models --provider myprovider # list the endpoint's models +docker agent new --model myprovider/mymodel # build agents with it +docker agent run --model myprovider/mymodel # chat with it +``` + +Global providers are merged into every loaded agent configuration; when an +agent file defines a provider with the same name, the agent file wins. Note +that automatic model selection (`model: auto`) never picks a custom provider, +so reference its models explicitly with `--model /` or +`default_model`. + ## How It Works When you reference a provider: @@ -263,3 +302,9 @@ When you reference a provider: 3. All model-level defaults (temperature, max_tokens, thinking_budget, etc.) are inherited (model settings take precedence) 4. For OpenAI-compatible providers, the `api_type` is stored in `provider_opts.api_type` 5. The model is used with the appropriate API client + +A provider with a `base_url` implies `bypass_models_gateway: true` for every +model that references it: user-chosen endpoints are never routed through a +configured models gateway, and such models authenticate with the provider's +own credentials (`token_key`). See +[Gateway Bypass](../../configuration/models/index.md#gateway-bypass). diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/openai/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/openai/index.md index 2ef18bbbddd5..4e866c24deee 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/openai/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/openai/index.md @@ -1,11 +1,12 @@ --- title: "OpenAI" -description: "Use GPT-4o, GPT-5, GPT-5-mini, and other OpenAI models with docker-agent." +description: "Use GPT-5.6, GPT-4o, GPT-5, GPT-5-mini, and other OpenAI models with docker-agent." keywords: docker agent, ai agents, model providers, llm, openai weight: 200 +canonical: https://docs.docker.com/ai/docker-agent/providers/openai/ --- -_Use GPT-4o, GPT-5, GPT-5-mini, and other OpenAI models with docker-agent._ +_Use GPT-5.6, GPT-4o, GPT-5, GPT-5-mini, and other OpenAI models with docker-agent._ ## Setup @@ -14,6 +15,11 @@ _Use GPT-4o, GPT-5, GPT-5-mini, and other OpenAI models with docker-agent._ export OPENAI_API_KEY="sk-..." ``` +> [!TIP] +> No API key? A ChatGPT Plus/Pro/Business subscription can be used instead +> through the [`chatgpt` provider](../chatgpt/index.md): sign in once with +> `docker agent setup` (pick chatgpt). + ## Configuration ### Inline @@ -21,7 +27,7 @@ export OPENAI_API_KEY="sk-..." ```yaml agents: root: - model: openai/gpt-5 + model: openai/gpt-5.6 ``` ### Named Model @@ -30,51 +36,57 @@ agents: models: gpt: provider: openai - model: gpt-5 - temperature: 0.7 + model: gpt-5.6 max_tokens: 4000 ``` ## Available Models -| Model | Best For | -| ------------- | ------------------------------------ | -| `gpt-5` | Most capable, complex reasoning | -| `gpt-5-mini` | Fast, cost-effective, good reasoning | -| `gpt-4o` | Multimodal, balanced performance | -| `gpt-4o-mini` | Cheapest, fast for simple tasks | +| Model | Best For | +| ---------------- | ----------------------------------------------------- | +| `gpt-5.6` | Alias for `gpt-5.6-sol`; tracks the flagship model | +| `gpt-5.6-sol` | Frontier model, most capable, complex reasoning | +| `gpt-5.6-terra` | Everyday workhorse; successor to the `-mini` tier | +| `gpt-5.6-luna` | High-volume, cost-efficient; successor to `-nano` tier | +| `gpt-5` | Previous-generation flagship | +| `gpt-5-mini` | Previous-generation fast, cost-effective model | +| `gpt-4o` | Multimodal, balanced performance | +| `gpt-4o-mini` | Cheapest, fast for simple tasks | + +Starting with GPT-5.6, OpenAI renamed the `-mini`/`-nano` size tiers to `-terra`/`-luna` (with `-sol` denoting the frontier tier previously left unsuffixed). Find more model names at [modelnames.ai](https://modelnames.ai/) or in the [official OpenAI docs](https://platform.openai.com/docs/models). ## Thinking Budget -OpenAI reasoning models (o-series, gpt-5, gpt-5-mini) support extended thinking through the `reasoning_effort` API parameter. Set `thinking_budget` to control the effort level: +OpenAI reasoning models (o-series, gpt-5, gpt-5-mini, gpt-5.6 family) support extended thinking through the `reasoning_effort` API parameter. Set `thinking_budget` to control the effort level: ```yaml models: gpt-thinker: provider: openai - model: gpt-5-mini - thinking_budget: high # minimal | low | medium | high | xhigh + model: gpt-5.6 + thinking_budget: high # none | minimal | low | medium | high | xhigh | max ``` **Effort levels:** | Level | Description | | --------- | -------------------------------------------------------- | -| `none` | Don't request extra reasoning (alias for `0`); the API's own default still applies. | -| `minimal` | Fastest; lightest reasoning pass. | +| `none` | No reasoning. On `gpt-5.6`+ this is a real API value that is sent as-is; on older models it just disables the local `thinking_budget` (the API's own default still applies). | +| `minimal` | Fastest; lightest reasoning pass. Not accepted on `gpt-5.6`+ (dropped from the API). | | `low` | Quick reasoning for straightforward tasks. | | `medium` | Balanced default. | | `high` | More thorough; recommended for complex tasks. | -| `xhigh` | Near-maximum effort; slower but most accurate. | +| `xhigh` | Near-maximum effort; slower but most accurate. Requires `gpt-5.2`+. | +| `max` | Maximum effort. Requires `gpt-5.6`+ (Sol/Terra/Luna). | -These are the **only** values OpenAI accepts — token counts, `max`, `adaptive`, and `adaptive/` are rejected with a configuration error at request time. Older models (o1, o3-mini) only accept `low`/`medium`/`high`. +Token counts, `adaptive`, and `adaptive/` are rejected with a configuration error at request time. Older models (o1, o3-mini) only accept `low`/`medium`/`high`; `xhigh` requires `gpt-5.2`+; `none` and `max` require `gpt-5.6`+; `minimal` is not accepted on `gpt-5.6`+. > [!WARNING] > **Hidden reasoning tokens** > -> OpenAI reasoning models always produce hidden reasoning tokens that count against `max_tokens` — even with `thinking_budget: none`. docker-agent automatically raises the output-token floor for its internal low-effort calls so reasoning cannot starve visible text output. +> OpenAI reasoning models always produce hidden reasoning tokens that count against `max_tokens` — even with `thinking_budget: none` on older models. docker-agent automatically raises the output-token floor for its internal low-effort calls so reasoning cannot starve visible text output. See the [Thinking / Reasoning guide](../../guides/thinking/index.md) for a cross-provider overview. diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/vercel/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/vercel/index.md index 8db5d1163ed2..1047fa0d46c1 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/vercel/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/vercel/index.md @@ -3,6 +3,7 @@ title: "Vercel AI Gateway" description: "Use Vercel AI Gateway models with docker-agent." keywords: docker agent, ai agents, model providers, llm, vercel ai gateway weight: 260 +canonical: https://docs.docker.com/ai/docker-agent/providers/vercel/ --- _Use Vercel AI Gateway models with docker-agent._ @@ -27,8 +28,10 @@ built-in support for Vercel AI Gateway as an alias provider. ## Usage Vercel AI Gateway model IDs use a `creator/model` form (for example -`openai/gpt-5` or `anthropic/claude-sonnet-4.5`); the gateway routes each -request to the underlying provider. +`openai/gpt-5.6-sol` or `anthropic/claude-sonnet-4.5`); the gateway routes each +request to the underlying provider. The gateway lists explicit variant slugs +only (`openai/gpt-5.6-sol`, `-terra`, `-luna`) — there is no unsuffixed +`openai/gpt-5.6` alias on the gateway. ### Inline Syntax @@ -37,7 +40,7 @@ The simplest way to use Vercel AI Gateway: ```yaml agents: root: - model: vercel/openai/gpt-5 + model: vercel/openai/gpt-5.6-sol description: Assistant using Vercel AI Gateway instruction: You are a helpful assistant. ``` @@ -50,8 +53,7 @@ For more control over parameters: models: vercel_model: provider: vercel - model: openai/gpt-5 - temperature: 0.7 + model: openai/gpt-5.6-sol max_tokens: 8192 agents: @@ -69,7 +71,9 @@ the current model list, IDs, and pricing. | Model | Description | | --- | --- | -| `openai/gpt-5` | OpenAI GPT-5 routed through the gateway | +| `openai/gpt-5.6-sol` | OpenAI GPT-5.6 Sol (frontier) routed through the gateway | +| `openai/gpt-5.6-terra` | OpenAI GPT-5.6 Terra (workhorse) routed through the gateway | +| `openai/gpt-5.6-luna` | OpenAI GPT-5.6 Luna (high-volume) routed through the gateway | | `anthropic/claude-sonnet-4.5` | Anthropic Claude Sonnet routed through the gateway | | `google/gemini-2.5-flash` | Google Gemini routed through the gateway | diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/background-agents/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/background-agents/index.md index 93ed5d021cc5..4ea266d4cfa0 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/background-agents/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/background-agents/index.md @@ -4,6 +4,7 @@ description: "Dispatch work to sub-agents concurrently and collect results async keywords: docker agent, ai agents, tools, toolsets, background agents tool linkTitle: "Background Agents" weight: 90 +canonical: https://docs.docker.com/ai/docker-agent/tools/background-agents/ --- _Dispatch work to sub-agents concurrently and collect results asynchronously._ @@ -29,7 +30,7 @@ The background agents tool lets an orchestrator dispatch work to sub-agents conc | `task` | string | ✓ | Clear, concise description of the task the sub-agent should achieve. | | `expected_output` | string | ✗ | Optional description of the result format the caller expects. | -`run_background_agent` returns a **task ID** string. Tools run by the sub-agent are pre-approved, so only dispatch to trusted sub-agents with well-scoped tasks. +`run_background_agent` returns a **task ID** string. Tools run by the sub-agent inherit the parent session's permissions. Because background tasks run non-interactively, any tool call that would normally prompt the user for approval will be automatically denied. To allow background agents to run mutating tools, you must explicitly approve them in the parent session (e.g. via YOLO mode or explicit allow rules). ### `view_background_agent` and `stop_background_agent` parameters @@ -75,6 +76,8 @@ agents: > > Use `background_agents` when your orchestrator needs to fan out work to multiple specialists in parallel — for example, researching several topics simultaneously or running independent code analyses side by side. +In the TUI, each background task's token usage is accounted for live: the sidebar's Agents panel shows the sub-agent's context usage percentage on its roster row, the Agent Inspector shows its exact token counts, and the task's cost joins the session total. + ## Using Harness Sub-Agents Background agents work equally well with [harness-backed sub-agents](../../features/harnesses/index.md) — sub-agents driven by external coding CLIs such as Claude Code or Codex. This lets you dispatch multiple independent coding tasks in parallel: diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/mcp/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/mcp/index.md index dbc845b55933..0b60da519391 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/mcp/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/mcp/index.md @@ -4,6 +4,7 @@ description: "Extend agents with external tools via the Model Context Protocol." keywords: docker agent, ai agents, tools, toolsets, mcp tool linkTitle: "MCP" weight: 130 +canonical: https://docs.docker.com/ai/docker-agent/tools/mcp/ aliases: - /ai/docker-agent/integrations/mcp/ --- @@ -98,12 +99,33 @@ toolsets: | ----------------------- | ------- | ----------- | | `remote.url` | string | Base URL of the MCP server. | | `remote.transport_type` | string | `streamable` or `sse`. | -| `remote.headers` | object | HTTP headers (typically for static auth tokens). | +| `remote.headers` | object | HTTP headers sent on every request. Values support `${env.VAR}` and `${headers.NAME}` placeholders, resolved per request. See [Remote MCP Servers](../../features/remote-mcp/index.md#per-request-header-template-expansion) for details. | | `remote.oauth` | object | Explicit OAuth client credentials for servers that don't support DCR. See [Remote MCP Servers](../../features/remote-mcp/index.md#oauth-for-servers-without-dynamic-client-registration). | | `allow_private_ips` | boolean | Permit remote MCP OAuth helper requests to dial non-public IP addresses. Use only for trusted internal servers. | For a curated list of public remote MCP endpoints (Linear, GitHub, Vercel, Notion, …) and full OAuth configuration details, see [Remote MCP Servers](../../features/remote-mcp/index.md). +## MCP Prompts + +MCP servers can expose **prompts** — named, parameterized templates that the server provides via the `/prompts` endpoint. Docker Agent discovers these at toolset startup and registers them as **slash commands** in the TUI, so you can invoke them directly from the input box. + +```text +# Type / to see available prompts alongside built-in commands +/review # invoke an MCP prompt named "review" +/summarize My text here # invoke with the first argument filled in +``` + +**How it works:** + +- Each MCP prompt appears in the command palette (accessible via Ctrl+K) under the **MCP Prompts** category. +- Typing `/` in the input box invokes the prompt immediately. +- If the prompt declares arguments and you provide text after the slash command, that text is mapped to the first declared argument. +- If a required argument is missing, docker-agent opens the argument input dialog before running the prompt. +- When no argument is needed or all required arguments are supplied, the prompt runs immediately. + +> [!NOTE] +> MCP prompt discovery requires a YAML-declared `mcp` toolset. Prompts from servers activated through the [Docker MCP Catalog](../../tools/mcp-catalog/index.md) (`ref: docker:`) are not currently surfaced. + ## Embedded Resources MCP tool results can include embedded resources — images, PDFs, and text files returned directly in the tool response. Docker Agent preserves these as attachments and forwards them to the model as native content blocks: diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/scheduler/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/scheduler/index.md new file mode 100644 index 000000000000..16635f7f77f2 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/scheduler/index.md @@ -0,0 +1,96 @@ +--- +title: "Scheduler Tool" +description: "Schedule instructions to run at a time or on a recurring interval." +keywords: docker agent, ai agents, tools, toolsets, scheduler tool, cron +linkTitle: "Scheduler" +weight: 135 +canonical: https://docs.docker.com/ai/docker-agent/tools/scheduler/ +--- + +_Schedule instructions to run at a time or on a recurring interval._ + +## Overview + +The scheduler toolset lets an agent make something happen at a chosen time or on a repeating cadence during a session. You give it an instruction and a schedule; when the schedule is due, the instruction is delivered back to the agent, which then carries out the action with its normal tools (`shell`, `api`, `fetch`, and so on). + +The scheduler does not run shell or API calls itself. When a schedule fires it injects the instruction into the agent loop via the runtime's recall mechanism — the same primitive [`background_jobs`](../background-jobs/index.md) uses to report completed work — and the agent decides how to act. This keeps every action under the agent's normal tools and permissions rather than adding a second, unattended +command runner. + +> [!NOTE] +> Schedules only fire while the session is running (interactive TUI or a server mode) and are not persisted across restarts. Scheduling requires a host that supports recall; if it does not, `create_schedule` returns an error. + +## Configuration + +```yaml +toolsets: + - type: scheduler +``` + +No configuration options. + +## Tools + +| Tool | Description | +| --- | --- | +| `create_schedule` | Register an instruction to run at a time or interval. | +| `list_schedules` | List active schedules with their id, spec, and next fire time. | +| `cancel_schedule` | Remove a schedule by id. | + +### `create_schedule` + +| Parameter | Required | Description | +| --- | --- | --- | +| `prompt` | Yes | The instruction to deliver to the agent when the schedule fires. | +| `when` | Yes | When to fire (see [Schedule specs](#schedule-specs)). | +| `name` | No | Optional human-readable label. | + +Returns the new schedule's id and its next fire time. + +### `cancel_schedule` + +| Parameter | Required | Description | +| --- | --- | --- | +| `id` | Yes | The id of the schedule to cancel (from `create_schedule` or `list_schedules`). | + +## Schedule specs + +The `when` argument accepts: + +| Form | Meaning | Example | +| --- | --- | --- | +| `in:` | One-shot, after a delay | `in:10m` | +| `at:` | One-shot, at an absolute future time | `at:2026-07-14T09:00:00Z` | +| `every:` | Recurring, at a fixed interval | `every:1h` | +| `minutely` / `hourly` / `daily` / `weekly` | Recurring preset intervals | `hourly` | + +Durations use Go's duration syntax (`30s`, `15m`, `2h`). Preset and `every:` intervals are measured from the schedule's creation time (for example `hourly` fires every hour after it is created), not aligned to wall-clock slots. + +> [!IMPORTANT] +> **Recurring schedules have a one-minute minimum.** Every fire injects a message into the agent loop and typically costs an LLM turn, so `every:` values below `1m` are rejected — a typo such as `every:1s` in place of `every:1h` would otherwise become a runaway token burn. One-shot schedules (`in:` / `at:`) are not restricted, since they fire once. + +## Example + +```yaml +agents: + root: + model: openai/gpt-5-mini + description: A monitoring assistant + instruction: | + Every 15 minutes, run `git fetch` and tell me if origin/main moved. + toolsets: + - type: scheduler + - type: shell +``` + +The agent calls: + +```text +create_schedule(prompt="Run git fetch and report if origin/main moved", when="every:15m") +``` + +Every 15 minutes it is reminded, runs the command with the `shell` tool, and reports back. + +> [!TIP] +> **When to use** +> +> Use the scheduler for recurring monitoring, timed one-shots, and unattended housekeeping loops during a long-running session. For work that should run immediately and be awaited, use [`background_jobs`](../background-jobs/index.md) instead. diff --git a/_vendor/modules.txt b/_vendor/modules.txt index 5ab27750d8f4..8403425740b0 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -4,4 +4,4 @@ # github.com/docker/cli v29.6.1+incompatible # github.com/docker/compose/v5 v5.3.0 # github.com/docker/model-runner v1.1.36 -# github.com/docker/docker-agent v1.96.0 +# github.com/docker/docker-agent v1.110.0 diff --git a/content/manuals/ai/docker-agent/model-providers.md b/content/manuals/ai/docker-agent/model-providers.md new file mode 100644 index 000000000000..82865c10190f --- /dev/null +++ b/content/manuals/ai/docker-agent/model-providers.md @@ -0,0 +1,526 @@ +--- +title: Model providers +description: Get API keys and configure cloud model providers for Docker Agent +keywords: [docker agent, model providers, api keys, anthropic, openai, google, gemini, groq, deepseek, cerebras, fireworks, together, moonshot, openrouter, ovhcloud, baseten, vercel, cloudflare] +weight: 10 +--- + +To run Docker Agent, you need a model provider. You can either use a cloud provider +with an API key or run models locally with [Docker Model +Runner](local-models.md). + +This guide covers cloud providers. For the local alternative, see [Local +models with Docker Model Runner](local-models.md). + +## Supported providers + +Docker Agent supports these cloud model providers: + +- Anthropic — Claude models +- Baseten — open-weight models via Baseten +- Cerebras — fast inference for open-weight models +- Cloudflare AI Gateway — multi-provider gateway with caching and observability +- Cloudflare Workers AI — open-weight models on the Cloudflare edge +- DeepSeek — DeepSeek chat and reasoning models +- Fireworks AI — fast inference for open-weight models +- Google — Gemini models +- Groq — ultra-low-latency open-weight models +- Moonshot AI — Kimi models +- OpenAI — GPT models +- OpenRouter — unified gateway to hundreds of models +- OVHcloud — EU-hosted open-weight models +- Together AI — large catalog of open-weight models +- Vercel AI Gateway — unified gateway to OpenAI, Anthropic, Google, and more + +## Anthropic + +Anthropic provides the Claude family of models, including Claude Sonnet and +Claude Opus. + +To get an API key: + +1. Go to [console.anthropic.com](https://console.anthropic.com/). +2. Sign up or sign in to your account. +3. Navigate to the API Keys section. +4. Create a new API key. +5. Copy the key. + +Set your API key as an environment variable: + +```console +$ export ANTHROPIC_API_KEY=your_key_here +``` + +Use Anthropic models in your agent configuration: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + instruction: You are a helpful coding assistant +``` + +Available models include: + +- `anthropic/claude-sonnet-4-5` +- `anthropic/claude-opus-4-5` +- `anthropic/claude-haiku-4-5` + +## Baseten + +[Baseten](https://www.baseten.co/) provides AI models through an +OpenAI-compatible API. It is a good choice for deploying your own models or +accessing hosted open-weight models. + +1. Get an API key from [Baseten](https://www.baseten.co/). +2. Set the environment variable: + +```console +$ export BASETEN_API_KEY=your_key_here +``` + +Use Baseten models in your agent configuration: + +```yaml +agents: + root: + model: baseten/deepseek-ai/DeepSeek-V3.1 + instruction: You are a helpful assistant +``` + +Or with a named model for more control: + +```yaml +models: + baseten_model: + provider: baseten + model: deepseek-ai/DeepSeek-V3.1 + max_tokens: 8192 + +agents: + root: + model: baseten_model + instruction: You are a helpful assistant +``` + +## Cerebras + +[Cerebras](https://www.cerebras.ai/) serves open-weight models (including +GPT-OSS and GLM) on its wafer-scale hardware through an OpenAI-compatible API, +delivering some of the highest inference speeds available. + +1. Create an API key from the [Cerebras Cloud console](https://cloud.cerebras.ai/). +2. Set the environment variable: + +```console +$ export CEREBRAS_API_KEY=your_key_here +``` + +Use Cerebras models in your agent configuration: + +```yaml +agents: + root: + model: cerebras/gpt-oss-120b + instruction: You are a helpful assistant +``` + +Available models include: + +- `cerebras/gpt-oss-120b` +- `cerebras/zai-glm-4.7` + +## Cloudflare AI Gateway + +[Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/) is a +single OpenAI-compatible endpoint that routes to models from OpenAI, Anthropic, +Workers AI, and more, with caching, rate limiting, and observability. + +The gateway endpoint is account- and gateway-scoped. Three environment variables +are required: + +```console +$ export CLOUDFLARE_ACCOUNT_ID=your_account_id +$ export CLOUDFLARE_GATEWAY_ID=your_gateway_id +$ export CLOUDFLARE_API_TOKEN=your_api_token +``` + +Use Cloudflare AI Gateway in your agent configuration: + +```yaml +agents: + root: + model: cloudflare-ai-gateway/workers-ai/@cf/meta/llama-3.1-8b-instruct + instruction: You are a helpful assistant +``` + +Or with a named model: + +```yaml +models: + cf_gateway_model: + provider: cloudflare-ai-gateway + model: "workers-ai/@cf/meta/llama-3.1-8b-instruct" + +agents: + root: + model: cf_gateway_model + instruction: You are a helpful assistant +``` + +> [!NOTE] +> The alias sends your token in the standard `Authorization: Bearer` header, +> which works for unauthenticated gateways (the default) routing to Workers AI +> models. Gateways with authentication enabled require the `cf-aig-authorization` +> header, which is not supported by this alias. For that setup, use a [custom +> provider](reference/config.md#models) instead. + +## Cloudflare Workers AI + +[Cloudflare Workers AI](https://developers.cloudflare.com/workers-ai/) runs +open-weight models (Llama, Mistral, Qwen, Gemma, and more) on Cloudflare's +global edge network. + +Workers AI is account-scoped, so two environment variables are required: + +```console +$ export CLOUDFLARE_ACCOUNT_ID=your_account_id +$ export CLOUDFLARE_API_TOKEN=your_api_token +``` + +Use Cloudflare Workers AI in your agent configuration: + +```yaml +agents: + root: + model: cloudflare-workers-ai/@cf/meta/llama-3.1-8b-instruct + instruction: You are a helpful assistant +``` + +Available models include `@cf/meta/llama-3.1-8b-instruct`, +`@cf/mistralai/mistral-small-3.1-24b-instruct`, and more. See the +[Workers AI models catalog](https://developers.cloudflare.com/workers-ai/models/) +for the full list. + +## DeepSeek + +[DeepSeek](https://www.deepseek.com/) serves its frontier chat and reasoning +models through an OpenAI-compatible API, with strong price/performance on coding +and reasoning tasks. + +1. Create an API key from the [DeepSeek Platform](https://platform.deepseek.com/api_keys). +2. Set the environment variable: + +```console +$ export DEEPSEEK_API_KEY=your_key_here +``` + +Use DeepSeek models in your agent configuration: + +```yaml +agents: + root: + model: deepseek/deepseek-chat + instruction: You are a helpful coding assistant +``` + +Available models include: + +- `deepseek/deepseek-chat` — DeepSeek-V3, general-purpose chat and tool calling +- `deepseek/deepseek-reasoner` — DeepSeek-R1, extended-reasoning model + +## Fireworks AI + +[Fireworks AI](https://fireworks.ai/) is a fast inference host for open-weight +models, serving Kimi K2, Llama, Qwen, DeepSeek, GLM, and others through an +OpenAI-compatible API. + +1. Create an API key from the [Fireworks dashboard](https://fireworks.ai/account/api-keys). +2. Set the environment variable: + +```console +$ export FIREWORKS_API_KEY=your_key_here +``` + +Use Fireworks AI models in your agent configuration: + +```yaml +agents: + root: + model: fireworks/accounts/fireworks/models/kimi-k2-instruct + instruction: You are a helpful assistant +``` + +Fireworks model IDs use the `accounts/fireworks/models/` form. See the +[Fireworks model library](https://fireworks.ai/models) for current IDs. + +## Google Gemini + +Google provides the Gemini family of models. + +To get an API key: + +1. Go to [aistudio.google.com/apikey](https://aistudio.google.com/apikey). +2. Sign in with your Google account. +3. Create an API key. +4. Copy the key. + +Set your API key as an environment variable: + +```console +$ export GOOGLE_API_KEY=your_key_here +``` + +Use Gemini models in your agent configuration: + +```yaml +agents: + root: + model: google/gemini-2.5-flash + instruction: You are a helpful coding assistant +``` + +Available models include: + +- `google/gemini-2.5-flash` +- `google/gemini-2.5-pro` + +## Groq + +[Groq](https://groq.com/) serves open-weight models on its LPU inference engine +through an OpenAI-compatible API, with a focus on very low latency. + +1. Create an API key from the [Groq Console](https://console.groq.com/keys). +2. Set the environment variable: + +```console +$ export GROQ_API_KEY=your_key_here +``` + +Use Groq models in your agent configuration: + +```yaml +agents: + root: + model: groq/llama-3.3-70b-versatile + instruction: You are a helpful assistant +``` + +Available models include `llama-3.3-70b-versatile`, `llama-3.1-8b-instant`, and +more. See the [Groq models documentation](https://console.groq.com/docs/models) +for current model IDs. + +## Moonshot AI + +[Moonshot AI](https://www.moonshot.ai/) serves its Kimi model family through an +OpenAI-compatible API. Kimi K2 models are well-suited for coding and agentic +tasks. + +1. Create an API key from the [Moonshot AI console](https://platform.moonshot.ai/console/api-keys). +2. Set the environment variable: + +```console +$ export MOONSHOT_API_KEY=your_key_here +``` + +Use Moonshot AI models in your agent configuration: + +```yaml +agents: + root: + model: moonshot/kimi-k2-0905-preview + instruction: You are a helpful assistant +``` + +Available models include: + +- `moonshot/kimi-k2-0905-preview` +- `moonshot/kimi-k2-turbo-preview` +- `moonshot/kimi-k2-thinking` + +## OpenAI + +OpenAI provides the GPT family of models, including GPT-5 and GPT-5 mini. + +To get an API key: + +1. Go to [platform.openai.com/api-keys](https://platform.openai.com/api-keys). +2. Sign up or sign in to your account. +3. Navigate to the API Keys section. +4. Create a new API key. +5. Copy the key. + +Set your API key as an environment variable: + +```console +$ export OPENAI_API_KEY=your_key_here +``` + +Use OpenAI models in your agent configuration: + +```yaml +agents: + root: + model: openai/gpt-5 + instruction: You are a helpful coding assistant +``` + +Available models include: + +- `openai/gpt-5` +- `openai/gpt-5-mini` + +## OpenRouter + +[OpenRouter](https://openrouter.ai/) provides access to hundreds of models from +many providers through a single OpenAI-compatible API, with automatic failover +and unified billing. + +1. Get an API key from [OpenRouter](https://openrouter.ai/settings/keys). +2. Set the environment variable: + +```console +$ export OPENROUTER_API_KEY=your_key_here +``` + +Use OpenRouter in your agent configuration: + +```yaml +agents: + root: + model: openrouter/meta-llama/llama-3.3-70b-instruct + instruction: You are a helpful assistant +``` + +OpenRouter model IDs include the upstream provider name (for example +`anthropic/claude-sonnet-4-5` or `meta-llama/llama-3.3-70b-instruct`). Docker +Agent preserves the full upstream model ID after the first slash. See the +[OpenRouter models list](https://openrouter.ai/models) for available models. + +## OVHcloud + +[OVHcloud AI Endpoints](https://endpoints.ai.cloud.ovh.net/) serves open-weight +models through an OpenAI-compatible API, hosted in the EU. Several models are +available on a rate-limited free tier with no billing setup required. + +1. Create an access token from the + [OVHcloud AI Endpoints portal](https://endpoints.ai.cloud.ovh.net/). +2. Set the environment variable: + +```console +$ export OVH_AI_ENDPOINTS_ACCESS_TOKEN=your_token_here +``` + +Use OVHcloud models in your agent configuration: + +```yaml +agents: + root: + model: ovhcloud/Qwen3.5-397B-A17B + instruction: You are a helpful assistant +``` + +Available models include `Qwen3.5-397B-A17B`, `Qwen3-32B`, +`Meta-Llama-3_3-70B-Instruct`, and more. See the +[AI Endpoints catalogue](https://endpoints.ai.cloud.ovh.net/) for current model +IDs. + +## Together AI + +[Together AI](https://www.together.ai/) is one of the largest hosts of +open-weight models, serving Llama, Qwen, DeepSeek, Kimi, GLM, and others +through an OpenAI-compatible API. + +1. Create an API key from the [Together AI settings](https://api.together.ai/settings/api-keys). +2. Set the environment variable: + +```console +$ export TOGETHER_API_KEY=your_key_here +``` + +Use Together AI models in your agent configuration: + +```yaml +agents: + root: + model: together/meta-llama/Llama-3.3-70B-Instruct-Turbo + instruction: You are a helpful assistant +``` + +See the [Together AI model library](https://docs.together.ai/docs/serverless-models) +for current model IDs. + +## Vercel AI Gateway + +[Vercel AI Gateway](https://vercel.com/docs/ai-gateway) is a unified +OpenAI-compatible endpoint that routes to models from OpenAI, Anthropic, Google, +xAI, and more at list price with no markup. + +1. Create an API key from the [Vercel AI Gateway dashboard](https://vercel.com/docs/ai-gateway). +2. Set the environment variable: + +```console +$ export AI_GATEWAY_API_KEY=your_key_here +``` + +Use Vercel AI Gateway in your agent configuration: + +```yaml +agents: + root: + model: vercel/openai/gpt-5 + instruction: You are a helpful assistant +``` + +Vercel AI Gateway model IDs use the `creator/model` form (for example +`openai/gpt-5` or `anthropic/claude-sonnet-4.5`). See the +[Vercel AI Gateway documentation](https://vercel.com/docs/ai-gateway) for the +current model list. + +## OpenAI-compatible providers + +You can use the `openai` provider type to connect to any model or provider that +implements the OpenAI API specification. This includes services like Azure +OpenAI, local inference servers, and other compatible endpoints. + +Define a named model in the `models` section with the `openai` provider and a +`base_url`, then reference it from your agent: + +```yaml +models: + my-model: + provider: openai + model: your-model-name + base_url: https://your-provider.example.com/v1 + +agents: + root: + model: my-model + instruction: You are a helpful coding assistant +``` + +By default, Docker Agent uses the `OPENAI_API_KEY` environment variable for +authentication. If your provider uses a different variable, specify it with +`token_key`: + +```yaml +models: + my-model: + provider: openai + model: your-model-name + base_url: https://your-provider.example.com/v1 + token_key: YOUR_PROVIDER_API_KEY + +agents: + root: + model: my-model + instruction: You are a helpful coding assistant +``` + +## What's next + +- Follow the [tutorial](tutorial.md) to build your first agent +- Learn about [local models with Docker Model Runner](local-models.md) as an + alternative to cloud providers +- Review the [configuration reference](reference/config.md) for advanced model + settings diff --git a/content/manuals/ai/docker-agent/reference/config.md b/content/manuals/ai/docker-agent/reference/config.md new file mode 100644 index 000000000000..70e5ea56ecca --- /dev/null +++ b/content/manuals/ai/docker-agent/reference/config.md @@ -0,0 +1,695 @@ +--- +title: Configuration file reference +linkTitle: Configuration file +description: Complete reference for the Docker Agent YAML configuration file format +keywords: [ai, agent, cagent, configuration, yaml] +weight: 10 +--- + +This reference documents the YAML configuration file format for agents using Docker Agent. +It covers file structure, agent parameters, model configuration, toolset setup, +and RAG sources. + +For detailed documentation of each toolset's capabilities and specific options, +see the [Toolsets reference](./toolsets.md). + +## File structure + +A configuration file has four top-level sections: + +```yaml +agents: # Required - agent definitions + root: + model: anthropic/claude-sonnet-4-5 + description: What this agent does + instruction: How it should behave + +models: # Optional - model configurations + custom_model: + provider: openai + model: gpt-5 + +rag: # Optional - RAG sources + docs: + docs: [./documents] + strategies: [...] + +metadata: # Optional - author, license, readme, version, tags + author: Your Name +``` + +## Agents + +| Property | Type | Description | Required | +| ---------------------- | ------- | ---------------------------------------------- | -------- | +| `model` | string | Model reference or name | Yes | +| `description` | string | Brief description of agent's purpose | No | +| `instruction` | string | Detailed behavior instructions | Yes | +| `sub_agents` | array | Agent names for task delegation | No | +| `handoffs` | array | Agent names for conversation handoff | No | +| `toolsets` | array | Available tools | No | +| `welcome_message` | string | Message displayed on start | No | +| `add_date` | boolean | Include current date in context | No | +| `add_environment_info` | boolean | Include working directory, OS, Git info | No | +| `add_prompt_files` | array | Prompt file paths to include | No | +| `max_iterations` | integer | Maximum tool call loops (unlimited if not set) | No | +| `num_history_items` | integer | Conversation history limit | No | +| `code_mode_tools` | boolean | Enable Code Mode for tools | No | +| `commands` | object | Named prompts accessible via `/command_name` | No | +| `structured_output` | object | JSON schema for structured responses | No | +| `rag` | array | RAG source names | No | + +### Task delegation versus conversation handoff + +Agents support two different delegation mechanisms. Choose based on whether you +need task results or conversation control. + +#### Sub_agents: Hierarchical task delegation + +Use `sub_agents` for hierarchical task delegation. The parent agent assigns a +specific task to a child agent using the `transfer_task` tool. The child +executes in its own context and returns results. The parent maintains control +and can delegate to multiple agents in sequence. + +This works well for structured workflows where you need to combine results from +specialists, or when tasks have clear boundaries. Each delegated task runs +independently and reports back to the parent. + +**Example:** + +```yaml +agents: + root: + sub_agents: [researcher, analyst] + instruction: | + Delegate research to researcher. + Delegate analysis to analyst. + Combine results and present findings. +``` + +Root calls: `transfer_task(agent="researcher", task="Find pricing data")`. The +researcher completes the task and returns results to root. + +#### Handoffs: Conversation transfer + +Use `handoffs` to transfer conversation control to a different agent. When an +agent uses the `handoff` tool, the new agent takes over completely. The +original agent steps back until someone hands back to it. + +This works well when different agents should own different parts of an ongoing +conversation, or when specialists need to collaborate as peers without a +coordinator managing every step. + +**Example:** + +```yaml +agents: + generalist: + handoffs: [database_expert, security_expert] + instruction: | + Help with general development questions. + If the conversation moves to database optimization, + hand off to database_expert. + If security concerns arise, hand off to security_expert. + + database_expert: + handoffs: [generalist, security_expert] + instruction: Handle database design and optimization. + + security_expert: + handoffs: [generalist, database_expert] + instruction: Review code for security vulnerabilities. +``` + +When the user asks about query performance, generalist executes: +`handoff(agent="database_expert")`. The database expert now owns the +conversation and can continue working with the user directly, or hand off to +security_expert if the discussion shifts to SQL injection concerns. + +### Commands + +Named prompts users invoke with `/command_name`. Supports JavaScript template +literals with `${env.VARIABLE}` for environment variables: + +```yaml +commands: + greet: "Say hello to ${env.USER}" + analyze: "Analyze ${env.PROJECT_NAME || 'demo'}" +``` + +Run with: `docker agent run config.yaml /greet` + +### Structured output + +Constrain responses to a JSON schema (OpenAI and Gemini only): + +```yaml +structured_output: + name: code_analysis + strict: true + schema: + type: object + properties: + issues: + type: array + items: { ... } + required: [issues] +``` + +## Models + +| Property | Type | Description | Required | +| --------------------- | ------- | ---------------------------------------------- | -------- | +| `provider` | string | `openai`, `anthropic`, `google`, `dmr` | Yes | +| `model` | string | Model name | Yes | +| `temperature` | float | Randomness (0.0-2.0) | No | +| `max_tokens` | integer | Maximum response length | No | +| `top_p` | float | Nucleus sampling (0.0-1.0) | No | +| `frequency_penalty` | float | Repetition penalty (-2.0 to 2.0, OpenAI only) | No | +| `presence_penalty` | float | Topic penalty (-2.0 to 2.0, OpenAI only) | No | +| `base_url` | string | Custom API endpoint | No | +| `parallel_tool_calls` | boolean | Enable parallel tool execution (default: true) | No | +| `token_key` | string | Authentication token key | No | +| `track_usage` | boolean | Track token usage | No | +| `thinking_budget` | mixed | Reasoning effort (provider-specific) | No | +| `compaction_model` | string | Model to use for session compaction (summary generation); defaults to the agent's own model | No | +| `bypass_models_gateway` | boolean | Connect directly to the provider, bypassing any configured models gateway | No | +| `provider_opts` | object | Provider-specific options | No | + +### Alloy models + +Use multiple models in rotation by separating names with commas: + +```yaml +model: anthropic/claude-sonnet-4-5,openai/gpt-5 +``` + +### Compaction model + +By default, when a session is compacted (via `/compact`, the proactive +threshold trigger, or post-overflow recovery), Docker Agent uses the agent's +own model to summarize the conversation. That summary call ingests the entire +conversation and is the slowest, most expensive call in a session. + +You can point `compaction_model` at a smaller, faster model to make compaction +cheaper without changing the model that runs the conversation: + +```yaml +models: + primary: + provider: anthropic + model: claude-sonnet-4-5 + compaction_model: fast # use the cheaper model for compaction + fast: + provider: anthropic + model: claude-haiku-4-5 + +agents: + root: + model: primary + instruction: You are a helpful assistant. +``` + +The value can be a model name from the `models` section or an inline +`provider/model` spec (for example `openai/gpt-5-mini`). When omitted, +compaction reuses the agent's own model. + +> [!NOTE] +> If the compaction model has a smaller context window than the primary model, +> Docker Agent triggers compaction against the smaller window, so the summary +> call can always ingest the full conversation. Pair the primary with a +> compaction model whose context window is at least as large to keep the +> proactive trigger aligned with the primary's window. + +### Bypass models gateway + +When a models gateway is configured (via `--models-gateway` or +`CAGENT_MODELS_GATEWAY`), Docker Agent routes all model requests through it by +default. Set `bypass_models_gateway: true` on a specific model to make it +connect directly to its provider instead: + +```yaml +models: + # Routed through the gateway when one is configured. + gateway-model: + provider: openai + model: gpt-5 + + # Always connects directly to Anthropic, even when a gateway is configured. + # Requires ANTHROPIC_API_KEY to be set. + direct-model: + provider: anthropic + model: claude-sonnet-4-5 + bypass_models_gateway: true + +agents: + root: + model: direct-model + instruction: You are a helpful assistant. +``` + +A bypassed model authenticates with its own provider credentials +(`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or the explicit `token_key`) rather +than the gateway's token. + +### Thinking budget + +Controls reasoning depth. Configuration varies by provider: + +- **OpenAI**: String values - `minimal`, `low`, `medium`, `high` +- **Anthropic**: Integer token budget (1024-32768, must be less than + `max_tokens`) + - Set `provider_opts.interleaved_thinking: true` for tool use during reasoning +- **Gemini**: Integer token budget (0 to disable, -1 for dynamic, max 24576) + - Gemini 2.5 Pro: 128-32768, cannot disable (minimum 128) + +```yaml +# OpenAI +thinking_budget: low + +# Anthropic +thinking_budget: 8192 +provider_opts: + interleaved_thinking: true + +# Gemini +thinking_budget: 8192 # Fixed +thinking_budget: -1 # Dynamic +thinking_budget: 0 # Disabled +``` + +### Docker Model Runner (DMR) + +Run local models. If `base_url` is omitted, Docker Agent auto-discovers via Docker +Model plugin. + +```yaml +provider: dmr +model: ai/qwen3 +max_tokens: 8192 +base_url: http://localhost:12434/engines/llama.cpp/v1 # Optional +``` + +Pass llama.cpp options via `provider_opts.runtime_flags` (array, string, or +multiline): + +```yaml +provider_opts: + runtime_flags: ["--ngl=33", "--threads=8"] + # or: runtime_flags: "--ngl=33 --threads=8" +``` + +Model config fields auto-map to runtime flags: + +- `temperature` → `--temp` +- `top_p` → `--top-p` +- `max_tokens` → `--context-size` + +Explicit `runtime_flags` override auto-mapped flags. + +Speculative decoding for faster inference: + +```yaml +provider_opts: + speculative_draft_model: ai/qwen3:0.6B-F16 + speculative_num_tokens: 16 + speculative_acceptance_rate: 0.8 +``` + +## Tools + +Configure tools in the `toolsets` array. Three types: built-in, MCP +(local/remote), and Docker Gateway. + +> [!NOTE] This section covers toolset configuration syntax. For detailed +> documentation of each toolset's capabilities, available tools, and specific +> configuration options, see the [Toolsets reference](./toolsets.md). + +All toolsets support common properties like `tools` (whitelist), `defer` +(deferred loading), `toon` (output compression), `env` (environment variables), +and `instruction` (usage guidance). See the [Toolsets reference](./toolsets.md) +for details on these properties and what each toolset does. + +### Built-in tools + +```yaml +toolsets: + - type: filesystem + - type: shell + - type: think + - type: todo + shared: true + - type: memory + path: ./memory.db +``` + +### MCP tools + +Local process: + +```yaml +- type: mcp + command: npx + args: + ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"] + tools: ["read_file", "write_file"] # Optional: limit to specific tools + env: + NODE_OPTIONS: "--max-old-space-size=8192" +``` + +Remote server: + +```yaml +- type: mcp + remote: + url: https://mcp-server.example.com + transport_type: sse + headers: + Authorization: Bearer token +``` + +### Docker MCP Gateway + +Containerized tools from [Docker MCP +Catalog](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md): + +```yaml +- type: mcp + ref: docker:duckduckgo +``` + +## RAG + +Retrieval-augmented generation for document knowledge bases. Define sources at +the top level, reference in agents. + +```yaml +rag: + docs: + docs: [./documents, ./README.md] + strategies: + - type: chunked-embeddings + embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 + database: ./embeddings.db + +agents: + root: + rag: [docs] +``` + +### Retrieval strategies + +All strategies support chunking configuration. Chunk size and overlap are +measured in characters (Unicode code points), not tokens. + +#### Chunked-embeddings + +Direct semantic search using vector embeddings. Best for understanding intent, +synonyms, and paraphrasing. + +| Field | Type | Default | +| ---------------------------------- | ------- | ------- | +| `embedding_model` | string | - | +| `database` | string | - | +| `vector_dimensions` | integer | - | +| `similarity_metric` | string | cosine | +| `threshold` | float | 0.5 | +| `limit` | integer | 5 | +| `chunking.size` | integer | 1000 | +| `chunking.overlap` | integer | 75 | +| `chunking.respect_word_boundaries` | boolean | true | +| `chunking.code_aware` | boolean | false | + +```yaml +- type: chunked-embeddings + embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 + database: ./vector.db + similarity_metric: cosine_similarity + threshold: 0.5 + limit: 10 + chunking: + size: 1000 + overlap: 100 +``` + +#### Semantic-embeddings + +LLM-enhanced semantic search. Uses a language model to generate rich semantic +summaries of each chunk before embedding, capturing deeper meaning. Best for complex documents where context and relationships between concepts matter. + +| Field | Type | Default | +| ---------------------------------- | ------- | ------- | +| `embedding_model` | string | - | +| `chat_model` | string | - | +| `database` | string | - | +| `vector_dimensions` | integer | - | +| `similarity_metric` | string | cosine | +| `threshold` | float | 0.5 | +| `limit` | integer | 5 | +| `ast_context` | boolean | false | +| `semantic_prompt` | string | - | +| `chunking.size` | integer | 1000 | +| `chunking.overlap` | integer | 75 | +| `chunking.respect_word_boundaries` | boolean | true | +| `chunking.code_aware` | boolean | false | + +```yaml +- type: semantic-embeddings + embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 + chat_model: openai/gpt-5-mini + database: ./semantic.db + threshold: 0.3 + limit: 10 + chunking: + size: 1000 + overlap: 100 +``` + +#### BM25 + +Keyword-based search using BM25 algorithm. Best for exact terms, technical +jargon, and code identifiers. + +| Field | Type | Default | +| ---------------------------------- | ------- | ------- | +| `database` | string | - | +| `k1` | float | 1.5 | +| `b` | float | 0.75 | +| `threshold` | float | 0.0 | +| `limit` | integer | 5 | +| `chunking.size` | integer | 1000 | +| `chunking.overlap` | integer | 75 | +| `chunking.respect_word_boundaries` | boolean | true | +| `chunking.code_aware` | boolean | false | + +```yaml +- type: bm25 + database: ./bm25.db + k1: 1.5 + b: 0.75 + threshold: 0.3 + limit: 10 + chunking: + size: 1000 + overlap: 100 +``` + +### Hybrid retrieval + +Combine multiple strategies with fusion: + +```yaml +strategies: + - type: chunked-embeddings + embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 + database: ./vector.db + limit: 20 + - type: bm25 + database: ./bm25.db + limit: 15 + +results: + fusion: + strategy: rrf # Options: rrf, weighted, max + k: 60 # RRF smoothing parameter + deduplicate: true + limit: 5 +``` + +Fusion strategies: + +- `rrf`: Reciprocal Rank Fusion (recommended, rank-based, no normalization + needed) +- `weighted`: Weighted combination (`fusion.weights: {chunked-embeddings: 0.7, +bm25: 0.3}`) +- `max`: Maximum score across strategies + +### Reranking + +Re-score results with a specialized model for improved relevance: + +```yaml +results: + reranking: + model: openai/gpt-5-mini + top_k: 10 # Only rerank top K (0 = all) + threshold: 0.3 # Minimum score after reranking + criteria: | # Optional domain-specific guidance + Prioritize official docs over blog posts + limit: 5 +``` + +DMR native reranking: + +```yaml +models: + reranker: + provider: dmr + model: hf.co/ggml-org/qwen3-reranker-0.6b-q8_0-gguf + +results: + reranking: + model: reranker +``` + +### Code-aware chunking + +For source code, use AST-based chunking. With semantic-embeddings, you can +include AST metadata in the LLM prompts: + +```yaml +- type: semantic-embeddings + embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 + chat_model: openai/gpt-5-mini + database: ./code.db + ast_context: true # Include AST metadata in semantic prompts + chunking: + size: 2000 + code_aware: true # Enable AST-based chunking +``` + +### RAG properties + +Top-level RAG source: + +| Field | Type | Description | +| ------------ | -------- | --------------------------------------------------------------- | +| `docs` | []string | Document paths (supports glob patterns, respects `.gitignore`) | +| `tool` | object | Customize RAG tool name/description/instruction | +| `strategies` | []object | Retrieval strategies (see above for strategy-specific fields) | +| `results` | object | Post-processing (fusion, reranking, limits) | + +Results: + +| Field | Type | Default | +| --------------------- | ------- | ------- | +| `limit` | integer | 15 | +| `deduplicate` | boolean | true | +| `include_score` | boolean | false | +| `fusion.strategy` | string | - | +| `fusion.k` | integer | 60 | +| `fusion.weights` | object | - | +| `reranking.model` | string | - | +| `reranking.top_k` | integer | 0 | +| `reranking.threshold` | float | 0.5 | +| `reranking.criteria` | string | "" | +| `return_full_content` | boolean | false | + +## Metadata + +Documentation and sharing information: + +| Property | Type | Description | +| --------- | -------- | ----------------------------------------- | +| `author` | string | Author name | +| `license` | string | License (e.g., MIT, Apache-2.0) | +| `readme` | string | Usage documentation | +| `version` | string | Semantic version string | +| `tags` | []string | Tags for categorization and discovery | + +```yaml +metadata: + author: Your Name + license: MIT + version: "1.0.0" + tags: [coding, review] + readme: | + Description and usage instructions +``` + +## Example configuration + +Complete configuration demonstrating key features: + +```yaml +agents: + root: + model: claude + description: Technical lead + instruction: Coordinate development tasks and delegate to specialists + sub_agents: [developer, reviewer] + toolsets: + - type: filesystem + - type: mcp + ref: docker:duckduckgo + rag: [readmes] + commands: + status: "Check project status" + + developer: + model: gpt + description: Software developer + instruction: Write clean, maintainable code + toolsets: + - type: filesystem + - type: shell + + reviewer: + model: claude + description: Code reviewer + instruction: Review for quality and security + toolsets: + - type: filesystem + +models: + gpt: + provider: openai + model: gpt-5 + + claude: + provider: anthropic + model: claude-sonnet-4-5 + max_tokens: 64000 + +rag: + readmes: + docs: ["**/README.md"] + strategies: + - type: chunked-embeddings + embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 + database: ./embeddings.db + limit: 10 + - type: bm25 + database: ./bm25.db + limit: 10 + results: + fusion: + strategy: rrf + k: 60 + limit: 5 +``` + +## What's next + +- Read the [Toolsets reference](./toolsets.md) for detailed toolset + documentation +- Review the [CLI reference](./cli.md) for command-line options +- Browse [example + configurations](https://github.com/docker/docker-agent/tree/main/examples) +- Learn about [sharing agents](../sharing-agents.md) diff --git a/go.mod b/go.mod index 9df5b9ab3cf7..2d11839dba6a 100644 --- a/go.mod +++ b/go.mod @@ -11,7 +11,7 @@ require ( github.com/docker/buildx v0.35.0 github.com/docker/cli v29.6.1+incompatible github.com/docker/compose/v5 v5.3.0 - github.com/docker/docker-agent v1.96.0 + github.com/docker/docker-agent v1.110.0 github.com/docker/model-runner v1.1.36 github.com/moby/buildkit v0.31.0 github.com/moby/moby/api v1.55.0 diff --git a/go.sum b/go.sum index f3ac2b7f9d2c..f64691f7eb2a 100644 --- a/go.sum +++ b/go.sum @@ -128,6 +128,8 @@ github.com/docker/docker v28.5.2+incompatible h1:DBX0Y0zAjZbSrm1uzOkdr1onVghKaft github.com/docker/docker v28.5.2+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk= github.com/docker/docker-agent v1.96.0 h1:wt018652ejWtHpMOdhvjwIxaeI46rc6o8snqb9QsmiI= github.com/docker/docker-agent v1.96.0/go.mod h1:PJlLIntWPY0KPepCIeR4+WRo2fmQnmnONYBmb/ULorM= +github.com/docker/docker-agent v1.103.0 h1:hmS2u0fU4MMyUnXrjJlhcfjpBUzkBEBM9/DrmL0yTpY= +github.com/docker/docker-agent v1.103.0/go.mod h1:KUYwjuxrs2N3BBrAQ6CMNPVQxOfoZoLUYpbxyGTM02w= github.com/docker/docker-credential-helpers v0.9.3 h1:gAm/VtF9wgqJMoxzT3Gj5p4AqIjCBS4wrsOh9yRqcz8= github.com/docker/docker-credential-helpers v0.9.3/go.mod h1:x+4Gbw9aGmChi3qTLZj8Dfn0TD20M/fuWy0E5+WDeCo= github.com/docker/docker-credential-helpers v0.9.5 h1:EFNN8DHvaiK8zVqFA2DT6BjXE0GzfLOZ38ggPTKePkY= @@ -563,3 +565,5 @@ gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= howett.net/plist v1.0.2-0.20250314012144-ee69052608d9 h1:eeH1AIcPvSc0Z25ThsYF+Xoqbn0CI/YnXVYoTLFdGQw= howett.net/plist v1.0.2-0.20250314012144-ee69052608d9/go.mod h1:fyFX5Hj5tP1Mpk8obqA9MZgXT416Q5711SDT7dQLTLk= +github.com/docker/docker-agent v1.110.0 h1:B5LJRkEvIk1WLojMR09gD6ZAD2hD43SIRSbjKs+yyc4= +github.com/docker/docker-agent v1.110.0/go.mod h1:TcrFxPYbc9SL0ouAcb/YwwjePfS0ULYkzfTJkvDUfzY=