diff --git a/_vendor/github.com/docker/cli/docs/reference/run.md b/_vendor/github.com/docker/cli/docs/reference/run.md index 4824233685c9..c0c8a1a90e73 100644 --- a/_vendor/github.com/docker/cli/docs/reference/run.md +++ b/_vendor/github.com/docker/cli/docs/reference/run.md @@ -35,7 +35,7 @@ reference to create or run a container based on an image. An image tag is the image version, which defaults to `latest` when omitted. Use the tag to run a container from specific version of an image. For example, to -run version `24.04` of the `ubuntu` image: `docker run ubuntu:24.04`. +run version `26.04` of the `ubuntu` image: `docker run ubuntu:26.04`. #### Image digests @@ -406,14 +406,14 @@ We have four ways to set user memory usage: Examples: ```console -$ docker run -it ubuntu:24.04 /bin/bash +$ docker run -it ubuntu:26.04 /bin/bash ``` We set nothing about memory, this means the processes in the container can use as much memory and swap memory as they need. ```console -$ docker run -it -m 300M --memory-swap -1 ubuntu:24.04 /bin/bash +$ docker run -it -m 300M --memory-swap -1 ubuntu:26.04 /bin/bash ``` We set memory limit and disabled swap memory limit, this means the processes in @@ -421,7 +421,7 @@ the container can use 300M memory and as much swap memory as they need (if the host supports swap memory). ```console -$ docker run -it -m 300M ubuntu:24.04 /bin/bash +$ docker run -it -m 300M ubuntu:26.04 /bin/bash ``` We set memory limit only, this means the processes in the container can use @@ -430,7 +430,7 @@ We set memory limit only, this means the processes in the container can use would be 2*300M, so processes can use 300M swap memory as well. ```console -$ docker run -it -m 300M --memory-swap 1G ubuntu:24.04 /bin/bash +$ docker run -it -m 300M --memory-swap 1G ubuntu:26.04 /bin/bash ``` We set both memory and swap memory, so the processes in the container can use @@ -456,7 +456,7 @@ The following example limits the memory (`-m`) to 500M and sets the memory reservation to 200M. ```console -$ docker run -it -m 500M --memory-reservation 200M ubuntu:24.04 /bin/bash +$ docker run -it -m 500M --memory-reservation 200M ubuntu:26.04 /bin/bash ``` Under this configuration, when the container consumes memory more than 200M and @@ -466,7 +466,7 @@ memory below 200M. The following example set memory reservation to 1G without a hard memory limit. ```console -$ docker run -it --memory-reservation 1G ubuntu:24.04 /bin/bash +$ docker run -it --memory-reservation 1G ubuntu:26.04 /bin/bash ``` The container can use as much memory as it needs. The memory reservation setting @@ -484,13 +484,13 @@ The following example limits the memory to 100M and disables the OOM killer for this container: ```console -$ docker run -it -m 100M --oom-kill-disable ubuntu:24.04 /bin/bash +$ docker run -it -m 100M --oom-kill-disable ubuntu:26.04 /bin/bash ``` The following example, illustrates a dangerous way to use the flag: ```console -$ docker run -it --oom-kill-disable ubuntu:24.04 /bin/bash +$ docker run -it --oom-kill-disable ubuntu:26.04 /bin/bash ``` The container has unlimited memory which can cause the host to run out memory @@ -510,7 +510,7 @@ between 0 and 100. A value of 0 turns off anonymous page swapping. A value of For example, you can set: ```console -$ docker run -it --memory-swappiness=0 ubuntu:24.04 /bin/bash +$ docker run -it --memory-swappiness=0 ubuntu:26.04 /bin/bash ``` Setting the `--memory-swappiness` option is helpful when you want to retain the @@ -561,7 +561,7 @@ And usually `--cpu-period` should work with `--cpu-quota`. Examples: ```console -$ docker run -it --cpu-period=50000 --cpu-quota=25000 ubuntu:24.04 /bin/bash +$ docker run -it --cpu-period=50000 --cpu-quota=25000 ubuntu:26.04 /bin/bash ``` If there is 1 CPU, this means the container can get 50% CPU worth of run-time every 50ms. @@ -582,13 +582,13 @@ We can set cpus in which to allow execution for containers. Examples: ```console -$ docker run -it --cpuset-cpus="1,3" ubuntu:24.04 /bin/bash +$ docker run -it --cpuset-cpus="1,3" ubuntu:26.04 /bin/bash ``` This means processes in container can be executed on cpu 1 and cpu 3. ```console -$ docker run -it --cpuset-cpus="0-2" ubuntu:24.04 /bin/bash +$ docker run -it --cpuset-cpus="0-2" ubuntu:26.04 /bin/bash ``` This means processes in container can be executed on cpu 0, cpu 1 and cpu 2. @@ -599,14 +599,14 @@ on NUMA systems. Examples: ```console -$ docker run -it --cpuset-mems="1,3" ubuntu:24.04 /bin/bash +$ docker run -it --cpuset-mems="1,3" ubuntu:26.04 /bin/bash ``` This example restricts the processes in the container to only use memory from memory nodes 1 and 3. ```console -$ docker run -it --cpuset-mems="0-2" ubuntu:24.04 /bin/bash +$ docker run -it --cpuset-mems="0-2" ubuntu:26.04 /bin/bash ``` This example restricts the processes in the container to only use memory from @@ -637,8 +637,8 @@ For example, the commands below create two containers with different blkio weight: ```console -$ docker run -it --name c1 --blkio-weight 300 ubuntu:24.04 /bin/bash -$ docker run -it --name c2 --blkio-weight 600 ubuntu:24.04 /bin/bash +$ docker run -it --name c1 --blkio-weight 300 ubuntu:26.04 /bin/bash +$ docker run -it --name c2 --blkio-weight 600 ubuntu:26.04 /bin/bash ``` If you do block IO in the two containers at the same time, by, for example: @@ -854,11 +854,11 @@ For interacting with the network stack, instead of using `--privileged` they should use `--cap-add=NET_ADMIN` to modify the network interfaces. ```console -$ docker run -it --rm ubuntu:24.04 ip link add dummy0 type dummy +$ docker run -it --rm ubuntu:26.04 ip link add dummy0 type dummy RTNETLINK answers: Operation not permitted -$ docker run -it --rm --cap-add=NET_ADMIN ubuntu:24.04 ip link add dummy0 type dummy +$ docker run -it --rm --cap-add=NET_ADMIN ubuntu:26.04 ip link add dummy0 type dummy ``` To mount a FUSE based filesystem, you need to combine both `--cap-add` and diff --git a/_vendor/github.com/docker/docker-agent/docs/concepts/agents/index.md b/_vendor/github.com/docker/docker-agent/docs/concepts/agents/index.md index 17b70ce5e85c..a9cf800d767c 100644 --- a/_vendor/github.com/docker/docker-agent/docs/concepts/agents/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/concepts/agents/index.md @@ -6,8 +6,6 @@ weight: 10 canonical: https://docs.docker.com/ai/docker-agent/concepts/agents/ --- -_Agents are the core building blocks of Docker Agent. Each agent is an AI-powered entity with a model, instructions, tools, and optional sub-agents._ - ## What is an Agent? An agent in Docker Agent is defined by: @@ -95,14 +93,27 @@ $ docker agent run agent.yaml /greet Commands support environment variable interpolation using JavaScript template literal syntax. Undefined variables expand to empty strings. -## Default Agent +## Built-in Agents + +Docker Agent includes two built-in agents: + +- **`default`**: A capable coding agent with a development workflow, file and shell tools, skills, environment information, and project instructions from `AGENTS.md`. +- **`minimal`**: A small general-purpose configuration with a concise instruction and file, shell, and fetch tools. It uses automatic model selection. -Running `docker agent run` without a config argument uses `docker-agent.yaml`, `docker-agent.yml`, or `docker-agent.hcl` from the current directory when present. Otherwise, it uses a capable built-in default agent for quick tasks without needing any configuration. +The former `coder` built-in is now `default`; use `docker agent run default` for coding tasks. + +### Default Agent + +Running `docker agent run` without a config argument uses `docker-agent.yaml`, `docker-agent.yml`, or `docker-agent.hcl` from the current directory when present. Otherwise, it uses `default`. ```bash # Use the project config or built-in default agent $ docker agent run +# Explicitly choose a built-in agent +$ docker agent run default +$ docker agent run minimal + # Override the default with an alias $ docker agent alias add default /path/to/my-agent.yaml $ docker agent run # now runs your custom agent diff --git a/_vendor/github.com/docker/docker-agent/docs/concepts/distribution/index.md b/_vendor/github.com/docker/docker-agent/docs/concepts/distribution/index.md index 17087fd5319a..9e0f12c24625 100644 --- a/_vendor/github.com/docker/docker-agent/docs/concepts/distribution/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/concepts/distribution/index.md @@ -8,8 +8,6 @@ aliases: - /ai/docker-agent/sharing-agents/ --- -_Package, share, and run agents via OCI-compatible registries — just like container images._ - ## Overview Docker Agent agents can be pushed to any OCI-compatible registry (Docker Hub, GitHub Container Registry, etc.) and pulled/run anywhere. This makes sharing agents as easy as sharing Docker images. 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 cc20031517e3..cca42a1a05de 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 @@ -96,21 +96,15 @@ Control how much the model "thinks" before responding: | Provider | Format | Values | Default | | ---------- | ---------- | ------------------------------------------------------------------- | -------------------------------- | | 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 | +| Anthropic | int or str | Fixed budgets: ≥1024 and less than `max_tokens`; or `adaptive`, `adaptive/`, effort level | Model-dependent; Claude 5.x defaults to adaptive | | 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` clears Docker Agent's local config | — | -`none` and `0` are not universal API-level disable switches. On genuine OpenAI -endpoints running GPT-5.x from 5.6 onward or GPT-6 Sol/Luna, `none` is a real -`reasoning_effort` value that Docker Agent sends as-is and the model does not -reason. On GPT-6 Astra and 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. +**Turning thinking off:** Set `thinking_budget` to `none` or `0`. Models that +support disabling reasoning turn it off; others keep reasoning at their default +or minimum effort. Check your model's behavior in the +[Thinking / Reasoning guide](../../guides/thinking/index.md#disabling-thinking). ```yaml models: diff --git a/_vendor/github.com/docker/docker-agent/docs/concepts/multi-agent/index.md b/_vendor/github.com/docker/docker-agent/docs/concepts/multi-agent/index.md index 082a38ddf680..76bf18e116b6 100644 --- a/_vendor/github.com/docker/docker-agent/docs/concepts/multi-agent/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/concepts/multi-agent/index.md @@ -64,9 +64,9 @@ transfer_task( ``` > [!NOTE] -> **Auto-Approved** +> **Approval rules still apply** > -> Unlike other tools, `transfer_task` is always auto-approved — no user confirmation needed. This allows seamless delegation between agents. +> `transfer_task` carries a read-only hint and normally runs without confirmation under the default policy. Strict mode, permission rules, and hooks can still require approval or block delegation. The delegated agent's own tool calls are checked separately. ## Handoffs Routing @@ -196,6 +196,18 @@ agents: toolsets: - type: think - type: background_agents + researcher: + model: anthropic/claude-sonnet-4-5 + description: Finds relevant research + instruction: Research the assigned topic and report your findings. + analyst: + model: anthropic/claude-sonnet-4-5 + description: Analyzes the project architecture + instruction: Analyze the assigned problem and explain your conclusions. + writer: + model: anthropic/claude-sonnet-4-5 + description: Drafts reports + instruction: Write a clear report from the provided findings. ``` The coordinator can then: diff --git a/_vendor/github.com/docker/docker-agent/docs/concepts/tools/index.md b/_vendor/github.com/docker/docker-agent/docs/concepts/tools/index.md index 9bf000b197e5..f98395d90238 100644 --- a/_vendor/github.com/docker/docker-agent/docs/concepts/tools/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/concepts/tools/index.md @@ -56,8 +56,3 @@ toolsets: ``` See [Tool Config](../../configuration/tools/index.md#mcp-tools) for full MCP configuration reference. - -> [!TIP] -> **See also** -> -> For full configuration reference, see [Tool Config](../../configuration/tools/index.md). 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 586d2a5d03a5..4519382aeb75 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 @@ -7,8 +7,6 @@ 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 @@ -381,7 +379,7 @@ agents: ## Deferred Tool Loading -Toolsets support `defer` to load tools on-demand and speed up agent startup. See [Deferred Tool Loading](../tools/index.md#deferred-tool-loading) for details. +Toolsets support `defer` to expose tool definitions to the model on demand and reduce prompt size. The underlying toolsets still start normally. See [Deferred Tool Loading](../tools/index.md#deferred-tool-loading) for details. ```yaml agents: diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/agentsignore/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/agentsignore/index.md index 65e295131721..4e52d1916983 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/agentsignore/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/agentsignore/index.md @@ -6,8 +6,6 @@ weight: 75 canonical: https://docs.docker.com/ai/docker-agent/configuration/agentsignore/ --- -_Hide files from the agent with a `.agentsignore` file, using the same syntax as `.gitignore`._ - ## Overview Put a `.agentsignore` file in your project and the agent stops seeing the paths it lists. Matched files are absent from directory listings and searches, and reads, writes and edits targeting them are refused. @@ -62,6 +60,10 @@ When `.agentsignore` contains at least one active pattern, the filesystem toolse > [!NOTE] > `.agentsignore` is independent of the filesystem toolset's [`ignore_vcs`](../tools/index.md) option. Setting `ignore_vcs: false` turns off `.gitignore` filtering but does **not** un-hide `.agentsignore` entries. +## Worktrees + +When a source checkout has a [`.worktreeinclude`](../../features/cli/index.md#copy-ignored-files-into-worktrees), files blocked by its `.agentsignore` are skipped even if they match the include patterns. The `.agentsignore` file itself is not copied by that mechanism. A worktree loads its own `.agentsignore` independently; commit or otherwise arrange its rules when needed, including for files already tracked in the worktree. + ## Relationship to `.gitignore` They are separate, and they do different amounts of work. diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/budget/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/budget/index.md index 0c96ce28b31f..d3e8a8655377 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/budget/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/budget/index.md @@ -6,8 +6,6 @@ weight: 75 canonical: https://docs.docker.com/ai/docker-agent/configuration/budget/ --- -_Cap what a single run may spend in money, tokens, or working time._ - ## Overview A budget sets ceilings on a run. When a ceiling is crossed the run stops with a message naming the exact limit that tripped, and the TUI tracks consumption live while the run is still going. @@ -75,8 +73,6 @@ Referencing a budget name that isn't defined is a config error, caught at parse When several agents reference the same budget name they draw from the **same** ceiling — not a copy each. Above, `root` and `researcher` share `shell-work`: together they cannot spend more than `$0.03`. -This is deliberate, and it is the whole reason budgets are worth having. If each agent received its own allowance, a run could spend `max_cost` × N simply by fanning out to N sub-agents, and the ceiling would mean nothing for exactly the workloads that most need one. - Give agents **distinct budget names** when you want independent pots. The same applies to the run-wide `budget`: every sub-session inside a run (transferred tasks, sub-agents, skills) spends from that one wallet. @@ -85,7 +81,7 @@ Compaction model calls also count towards the run-wide budget and the compacted ## Scope: a budget spans the session -Spend accumulates for the life of the **session**, across every message you send — it does not reset each time you hit enter. A `max_cost: 0.50` you could re-spend on every message would not be a ceiling at all. +Spend accumulates for the life of the **session**, across every message you send — it does not reset each time you hit enter. Starting a new session starts a fresh budget. It is a per-session ceiling, not a lifetime quota across sessions. @@ -100,7 +96,7 @@ stored conversation history and cost totals. External `harness:` execution does not use the native budget-enforcement loop. > [!NOTE] -> `max_time` measures the time the agents actually spend **working** — the sum of their turn durations — not wall-clock since the session opened. Because a budget spans a session, and a session sits idle while you read and type, wall-clock would let a budget expire during a coffee break: leave the TUI open for ten minutes and your next message would instantly trip a `max_time` of `2m` without the agent having done anything. +> `max_time` measures the time the agents spend **working** — the sum of their turn durations — not wall-clock time since the session opened. ## What stops a run @@ -118,7 +114,7 @@ Execution stopped after reaching the configured budgets.shell-work.max_cost limit (used $0.0312 of $0.0300). ``` -Unlike [`max_iterations`](../agents/index.md), a budget stop is **terminal** — there is no prompt offering to continue. A budget is a ceiling you set deliberately, so raising it means editing the config rather than answering a dialog. +Unlike [`max_iterations`](../agents/index.md), a budget stop is **terminal** — there is no prompt offering to continue. Edit the config to raise the limit. ## Budget stops in evaluation output @@ -194,6 +190,8 @@ This is the same granularity [`max_iterations`](../agents/index.md) has, and it The `max_tokens` in a budget is a **cumulative** count of tokens across the whole run: fresh input, cache-read input, cache-write input, and output all count towards it. It is unrelated to the provider- or model-level [`max_tokens`](../models/index.md), which caps the output of a single response. +When a server-side fallback (for example [Anthropic server-side fallbacks](../../providers/anthropic/index.md#server-side-fallbacks)) serves a turn, the token budgets count the tokens of every attempt, including declined ones, not just the final model's usage. + It is also not the session's context length: compaction resets that, while the budget keeps counting. ## Examples diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/flavors/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/flavors/index.md index 3218fa381e61..bf03779e7e43 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/flavors/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/flavors/index.md @@ -6,8 +6,6 @@ weight: 95 canonical: https://docs.docker.com/ai/docker-agent/configuration/flavors/ --- -_Ship one agent file with named variants, enabled at run time as YAML patches._ - ## Overview A flavor is a named YAML patch declared in the agent file itself, under the 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 d898512efdc9..e5f7b2b240a0 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 @@ -6,8 +6,6 @@ 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._ - ## Overview Hooks allow you to execute shell commands or scripts at key points in an agent's lifecycle. They provide deterministic control that works alongside the LLM's behavior, enabling validation, logging, environment setup, and more. @@ -62,7 +60,7 @@ Docker Agent dispatches the following hook events: | `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 (permissions / yolo / readonly / ask) resolves | No | -| `worktree_create` | After `docker agent run --worktree` creates a git worktree, before the session | Yes | +| `worktree_create` | After a git worktree is created — by `docker agent run --worktree` (before the session) or for a [background agent task](../../tools/background-agents/index.md#isolated-coding-tasks) with `worktree: true` (before the child's tools load) | Yes | | `before_agent_run` | Once per agent activation, before its model runs — can [route](#agent-routing-hooks) to another agent | Yes | | `after_agent_complete` | Once after an agent completes successfully — can [route](#agent-routing-hooks) onward | Yes | @@ -80,7 +78,7 @@ The shared catalog in `pkg/hooks/events` drives configuration validation, dispatch strategy, output aggregation, and strict output validation. Tests keep this table, the configuration fields, and the JSON schema synchronized. “Context” means additional context is consumed by the runtime; `worktree_create` -shows it to the CLI user. The internal preempting `pre_tool_use` lane is parallel, +shows it to the CLI user, or adds it to the instructions of an isolated background task. The internal preempting `pre_tool_use` lane is parallel, collects metadata, and does not rewrite input. | Event | Execution | Can block | Failure default | Context | Rewrite | @@ -293,6 +291,7 @@ Built-ins are typically zero-config and faster than equivalent shell hooks becau | `redact_secrets` | `tool_input_transform`, `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. | | `transform_json` | `tool_response_transform` | JSON field names | Keeps only the named top-level fields of a JSON object. Nested values are preserved; missing fields are omitted. No expression language or domain validation. | | `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`, `background_jobs`, `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 excerpt (up to 2,000 excerpt lines; 50 KiB including the notice): the tail for most tools, but the head for the built-in filesystem `read_file`, whose notice suggests a follow-up call with `line`/`limit` to continue reading. If saving the payload fails, a bounded inline excerpt is returned without a file reference. Background-job excerpts retain status metadata before the log tail. The `session_end` leg deletes the temp directory. Internal toolsets (`memory`, `plan`, `tasks`, `think`, …) are not affected. | +| `keep_awake` | `session_start`, `session_end` | _none_ | CLI-owned sleep inhibitor, controlled by the disabled-by-default `settings.keep_awake` preference. | | `http_post` | Any event | `[URL, body]` | Sends an HTTP POST request with the optional body in `args[1]` to the URL in `args[0]`. Missing or empty URLs are ignored; only HTTP(S) destinations are accepted, using an SSRF-safe transport. | | `safer_shell` | `pre_tool_use` | _none_ | **Deprecated compatibility shim.** The runtime now classifies every shell command natively (`safe` / `destructive` / `unknown`) and gates it through the session's [safety mode](../permissions/index.md#safety-modes), so this builtin no longer emits verdicts. Pinned entries keep working as pure labellers that attach classification metadata (`safety_label`, `blast_radius`, `category`, `reason`) to the call. Filters by tool name internally (no-op for calls other than `shell` and `run_background_job`). | | `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). | @@ -311,6 +310,8 @@ Historical tool results are also bounded on outgoing chat and compaction request > `limit_large_tool_results` is injected unconditionally by the runtime — it is always active and cannot be removed from config. +The CLI also installs `keep_awake` on `session_start` and `session_end`. It uses [`github.com/rumpl/keepawake`](https://github.com/rumpl/keepawake) to hold a native sleep inhibitor for each run when `settings.keep_awake` is enabled. The setting is disabled by default and available in both TUIs. Cleanup runs even after cancellation or errors; acquisition failures warn without blocking the agent. This builtin is registered by the CLI, not the base runtime. + A minimal snapshot wiring looks like this: ```yaml @@ -426,8 +427,8 @@ In addition to the common fields, each event ships its own payload: | `tool_input_transform` | `agent_name`, `tool_name`, `tool_use_id`, `tool_category`, `tool_input`, `safety_policy` | | `tool_guard` | `agent_name`, `tool_name`, `tool_use_id`, `tool_category`, `tool_input`, `safety_policy` | | `pre_tool_use` | `agent_name`, `tool_name`, `tool_use_id`, `tool_input` | -| `tool_response_transform` | `tool_name`, `tool_use_id`, `tool_input`, `tool_response` | -| `post_tool_use` | `agent_name`, `tool_name`, `tool_use_id`, `tool_input`, `tool_response`, `tool_error` | +| `tool_response_transform` | `tool_name`, `tool_use_id`, `tool_input`, `tool_response`, `tool_result_meta` | +| `post_tool_use` | `agent_name`, `tool_name`, `tool_use_id`, `tool_input`, `tool_response`, `tool_error`, `tool_result_meta` | | `permission_request` | `agent_name`, `tool_name`, `tool_use_id`, `tool_input` | | `session_start` | `source` — `startup` for each run stream | | `user_prompt_submit` | `prompt` — the text the user just submitted | @@ -657,9 +658,12 @@ The `hook_specific_output` for `tool_response_transform` supports: | Field | Type | Description | | ----------------------- | ------ | --------------------------------------------- | | `updated_tool_response` | string | Rewritten tool output (replaces the original) | +| `updated_tool_result_meta` | JSON | Replacement for the tool result's display metadata (for example, the recorded diff of an `edit_file` call). A JSON value replaces the metadata, `null` clears it, and omitting the field leaves it unchanged | This is the symmetric counterpart of `tool_input_transform`'s `updated_input`, applied to tool **results** instead of tool **arguments**. The rewrite reaches every downstream consumer — event subscribers, the persisted session file, the `post_tool_use` hook input, and the next LLM call. Use it to truncate excessive output, scrub PII, or normalise tool dialects. The built-in `redact_secrets` registers itself on this event as the third leg of the redact_secrets feature. +Hooks on `tool_response_transform` and `post_tool_use` also receive `tool_result_meta`, the structured display metadata a tool recorded alongside its text output (the TUI renders completed `edit_file` diffs from it). Only `tool_response_transform` hooks can rewrite it, with `updated_tool_result_meta` (independently of `updated_tool_response`); the rewritten metadata is what gets emitted and persisted. `post_tool_use` hooks receive the already-transformed metadata and cannot change it. `redact_secrets` also scrubs this metadata, and clears it when it cannot be serialized safely. + ### Composing transformations Hooks for the following events run **sequentially in configuration order**: @@ -669,7 +673,7 @@ Hooks for the following events run **sequentially in configuration order**: | `tool_input_transform` | `updated_input` | `tool_input` with the patch applied | | `pre_tool_use` (default lane) | `updated_input` | `tool_input` with the patch applied | | `before_llm_call` | `updated_messages` | The rewritten `messages` array | -| `tool_response_transform` | `updated_tool_response` | The rewritten `tool_response` string | +| `tool_response_transform` | `updated_tool_response`, `updated_tool_result_meta` | The rewritten `tool_response` string and `tool_result_meta` | Every matching hook on these events participates in the sequence, whether it rewrites, observes, or returns a verdict. Each hook sees the most recent @@ -1042,7 +1046,9 @@ hooks: fi ``` -Unlike most events, `worktree_create` is dispatched from the CLI rather than the run loop, because the worktree (and the working directory the runtime, session, tools, and snapshot machinery all capture) must be settled before the runtime and session exist. See [`examples/worktree_create_hook.yaml`](https://github.com/docker/docker-agent/blob/main/examples/worktree_create_hook.yaml) for the full file. +`worktree_create` also fires when `run_background_agent` is called with `worktree: true`. Hooks run inside the task's new checkout with `agent_name` and `parent_session_id` set, before the child's toolsets and skills are loaded. Their additional context is added to the child's instructions, and a blocking decision (or error) fails the task; the checkout and branch are retained. + +For `docker agent run --worktree`, `worktree_create` is dispatched from the CLI rather than the run loop, because the worktree (and the working directory the runtime, session, tools, and snapshot machinery all capture) must be settled before the runtime and session exist. See [`examples/worktree_create_hook.yaml`](https://github.com/docker/docker-agent/blob/main/examples/worktree_create_hook.yaml) for the full file. ### Pre-Compact: steer the summary @@ -1260,6 +1266,18 @@ request -> evaluator +-- specialist --------------+-> final answer ``` ```yaml +evaluators: + task_route: + provider: typesafe + model: jev-latest + type: choice + instructions: Classify the work required by the request in input. + choices: + simple: A narrow question or routine explanation. + complex: A problem requiring detailed analysis. + research: A request requiring investigation and evidence. + unclear: A request missing essential information. + agents: root: model: openai/gpt-5-mini @@ -1273,6 +1291,18 @@ agents: routing_policy: routes: {simple: quick, complex: specialist, research: researcher, unclear: clarifier} min_probability: 0.85 + quick: + model: openai/gpt-5-mini + instruction: Answer the question directly. + specialist: + model: openai/gpt-5-mini + instruction: Analyze the problem and explain your conclusions. + researcher: + model: openai/gpt-5-mini + instruction: Investigate the request and report evidence and limitations. + clarifier: + model: openai/gpt-5-mini + instruction: Ask for the missing information needed to answer the request. ``` See [`examples/hook_routing.yaml`](https://github.com/docker/docker-agent/blob/main/examples/hook_routing.yaml) 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 34b876ae26b4..d87289da4dd4 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 @@ -7,8 +7,6 @@ weight: 40 canonical: https://docs.docker.com/ai/docker-agent/configuration/models/ --- -_Complete reference for defining models with providers, parameters, and reasoning settings._ - ## Full Schema @@ -18,11 +16,12 @@ 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, nvidia, minimax, baseten, daoxe, ovhcloud, groq, fireworks-ai, deepseek, cerebras, togetherai, huggingface, moonshotai, vercel, cloudflare-workers-ai, cloudflare-ai-gateway, requesty, openrouter, api-route, atlascloud, + # dmr, mistral, xai, nebius, nvidia, minimax, baseten, daoxe, ovhcloud, groq, fireworks-ai, deepseek, cerebras, togetherai, huggingface, moonshotai, vercel, cloudflare-workers-ai, cloudflare-ai-gateway, requesty, openrouter, opper, runcrate, api-route, lunaroute, orcarouter, atlascloud, popnow, cloudgpu, obscurify, hopbase, # azure, ollama, github-copilot, or a named provider defined # under the top-level `providers:` section. model: string # Required: model identifier description: string # Optional: human-readable summary of the model's purpose or strengths + stream_idle_timeout: duration|-1 # Optional: per-model stream idle limit temperature: float # Optional: 0.0–2.0 (provider-dependent; e.g. Anthropic caps at 1.0) max_tokens: integer # Optional: response length limit top_p: float # Optional: 0.0–1.0 @@ -47,6 +46,7 @@ models: 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 + context_window: integer # Optional: context window in tokens (metadata; never sent to the provider) provider_opts: # Optional: provider-specific options key: value title_model: string # Optional: model used for session-title generation @@ -55,14 +55,58 @@ models: bypass_models_gateway: boolean # Optional: skip the models gateway for this model (implied by a custom base_url) ``` +## Stream idle timeout + +`runtime.stream_idle_timeout` sets the default for agent conversation streams, +including subagents, inline models, model switches, fallbacks, routed models, +and LLM compaction summaries. Imported agent files use their own runtime +defaults. For each attempt, an explicit routed target setting takes precedence +over the router or fallback entry setting, which takes precedence over the +agent file's runtime setting. + +Use a positive Go duration such as `90s` or `2m30s`, or the integer `-1` to +disable the idle timer, overriding any lower-priority setting. Zero and other +negative values are invalid. An omitted or null value inherits the next setting; +when no setting applies, the idle timer is disabled for all models, including +Gemini Flex and routed requests. A short configured timeout can expire while a +Flex request is still queued. + +The timer measures silence while waiting for the first chunk and between chunks, +not total request duration. Each chunk resets it. If it expires, Docker Agent +cancels the model request and handles the stalled stream as a failure. Disabling +the timer leaves stalled streams waiting until the caller cancels or the +connection closes; normal cancellation still works. Title generation and model +hooks do not use this idle timer: they retain their separate total deadlines +(30 seconds for titles and the configured per-hook timeout). Setting `-1` does +not remove those deadlines. + +```yaml +runtime: + stream_idle_timeout: 10m +models: + slow: + provider: google + model: gemini-2.5-flash + stream_idle_timeout: 20m + local: + provider: ollama + model: llama3 + stream_idle_timeout: -1 +agents: + root: + model: slow + instruction: You are a helpful assistant. +``` + ## Properties Reference | 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`, `nvidia`, `minimax`, `baseten`, `daoxe`, `ovhcloud`, `groq`, `fireworks-ai`, `deepseek`, `cerebras`, `togetherai`, `huggingface`, `moonshotai`, `vercel`, `cloudflare-workers-ai`, `cloudflare-ai-gateway`, `requesty`, `openrouter`, `api-route`, `atlascloud`, `azure`, `ollama`, `github-copilot`, `chatgpt`, `opencode`, `opencode-go`, 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`, `daoxe`, `ovhcloud`, `groq`, `fireworks-ai`, `deepseek`, `cerebras`, `togetherai`, `huggingface`, `moonshotai`, `vercel`, `cloudflare-workers-ai`, `cloudflare-ai-gateway`, `requesty`, `openrouter`, `opper`, `runcrate`, `api-route`, `lunaroute`, `orcarouter`, `atlascloud`, `popnow`, `cloudgpu`, `obscurify`, `hopbase`, `azure`, `ollama`, `github-copilot`, `chatgpt`, `opencode`, `opencode-go`, 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`) | | `description` | string | ✗ | Informational, human-readable summary of the model's purpose or strengths (e.g., "fast and cheap, good for summaries"). Not sent to the model. Can be combined with `first_available` (a selector's description is kept when it resolves). | +| `stream_idle_timeout` | duration/int | ✗ | Maximum silence between stream chunks; overrides `runtime.stream_idle_timeout`. See [Stream idle timeout](#stream-idle-timeout). | | `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 | | `top_p` | float | ✗ | Nucleus sampling threshold (`0.0–1.0`) | @@ -78,6 +122,7 @@ models: | `capabilities` | object | ✗ | Override attachment (input) capabilities for this model. See [Attachment Capability Overrides](#attachment-capability-overrides). | | `output_capabilities` | object | ✗ | Override generative output capabilities for this model, e.g. image generation. Omitted flags are detected from models.dev; explicit values take precedence. Cannot be combined with `first_available`. See [Output Capabilities](#output-capabilities). | | `cost` | object | ✗ | Explicit token pricing in USD per 1M tokens, overriding the built-in catalogue. See [Custom Token Pricing](#custom-token-pricing). | +| `context_window` | int | ✗ | Context window of the model in tokens. Metadata for accounting, compaction and `max_tokens` clamping; never sent to the provider. Must not exceed the models.dev window for the model. Cannot be combined with `first_available`. See [Context Window](#context-window). | | `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. The agent-level `compaction_model` takes precedence over this value, which in turn takes precedence over a provider-level default. When none is set, the primary model compacts. Cannot be combined with `first_available`. See the [Context & Compaction guide](../../guides/compaction/index.md). | @@ -254,6 +299,106 @@ models instead). See [`examples/custom-pricing.yaml`](https://github.com/docker/docker-agent/blob/main/examples/custom-pricing.yaml) for a complete example. +## Context Window + +A model's context window drives context-usage accounting, the automatic +compaction threshold, and `max_tokens` clamping. Hosted models get it from the +[models.dev](https://models.dev/) catalogue. Custom endpoints (for example an +`openai_responses` or `openai_chatcompletions` provider with a `base_url`) and +local models often are not in the catalogue, so declare the window yourself: + +```yaml +version: "16" + +providers: + gateway: + api_type: openai_responses + base_url: https://gateway.example.com/v1 + token_key: GATEWAY_API_KEY + +models: + gateway_model: + provider: gateway + model: my-hosted-model + context_window: 200000 # context window in tokens +``` + +`context_window` is **metadata only**. It is never forwarded as a request +parameter, and it never configures the Docker Model Runner engine. + +Precedence for the context window of a model, highest first: + +1. The model-level `context_window`. This is the window for every provider. +2. For the `dmr` provider only, `provider_opts.context_size`. It also sizes the + DMR engine (see [Docker Model Runner](../../providers/dmr/index.md#context-size)), + so it must equal `context_window` when both are set. +3. The window discovered at runtime (for example from the Docker Model Runner + API). +4. The models.dev catalogue. + +`provider_opts.context_size` is **not** read for any other provider. Setting it +on a model that runs on a non-DMR provider (including a `providers:` alias +backed by `openai_responses`, `openai_chatcompletions` or `anthropic`) fails +validation with a message pointing to `context_window`. Move the value to the +model's `context_window` instead, and update the top-level `version` to `"16"` +when migrating an older config: earlier versions reject `context_window` before +migration. If the value is inherited from +`providers..provider_opts.context_size`, remove it from that provider and +set `context_window` on each model using it. Replace inline `provider/model` +references with named entries in `models` when they need a declared window. + +If none applies, the window is unknown: context usage cannot be shown as a +percentage and compaction cannot run. Compaction then reports a session warning +naming the model and asking for `context_window`. Pair a dedicated +`compaction_model` with its own `context_window` when its window is unknown. + +### Compaction thresholds + +`context_window` is capacity, not a fixed-token trigger. `compaction_threshold` +on the model or agent (default `0.9`) and background compaction (user setting, +default `70%`) apply their thresholds +to the effective window. With `context_window: 200000`, the default foreground +trigger fires above 180,000 tokens; the context gauge and `/context` use the same +limit. + +A dedicated `compaction_model` caps that limit at the smaller window so the summary +call can ingest the conversation. A 32,000-token compaction model paired with a +200,000-token primary triggers above 28,800 tokens at `0.9`. A larger compaction +window never raises the primary limit; if only one window is known, it is used. +See the [Context & Compaction guide](../../guides/compaction/index.md). + +Validation rejects: + +- a `context_window` that is not a positive integer; +- a DMR `provider_opts.context_size` that conflicts with the model-level value; +- `provider_opts.context_size` on a non-DMR provider. Custom providers and + aliases are judged by the provider they run (an alias backed by + `openai_responses` is non-DMR). The error names the field to move; +- a `context_window` above the context window the models.dev catalogue declares + for the model. The check applies provider defaults and environment expansion + and uses the runtime's catalogue identity, including the original display name + retained during alias resolution. Vertex Model Garden uses `anthropic` for + Anthropic publishers and `google-vertex` for other publishers, retaining their + publisher-prefixed model names; API dispatch remains separate. The check + compares the raw catalogue limit, so the declared value cannot hide a + conflict. The error identifies the model or construction reference, + `context_window`, and the catalogue maximum. + +A model the catalogue has no context limit for (custom endpoints, local models, +uncatalogued names) accepts any positive `context_window`; no cap is guessed. +Fallback, title, compaction, and routing models are checked when constructed, +including inherited provider options on inline references. This does not traverse +unused providers or recursively load auxiliary references on auxiliary models. + +Config loading requires an available models.dev catalogue when a model declares +`context_window`; this is different from an available catalogue that has no limit +for the model. Standalone provider construction (including RAG and SDK callers) +without a catalogue still validates positive windows and DMR/provider-option +constraints, and checks catalogue caps when a store is supplied. + +A `context_window` also cannot be set on a `first_available` selector; set it on +the candidate models instead. + ## Delegating Session-Title Generation The `title_model` field lets a heavyweight primary model hand off the cheap @@ -462,7 +607,7 @@ Use a string effort level. See [Gemini thinking budgets](../../providers/google/ thinking_budget: none # or 0 ``` -`none` and `0` both clear Docker Agent's local thinking configuration (omitting `thinking_budget` has the same effect). Whether that reaches the API as a real "off" switch depends on the model — see [Disabling Thinking](../../guides/thinking/index.md#disabling-thinking) in the guide. +`none` and `0` request disabled thinking, but their effect depends on the model. Omitting `thinking_budget` leaves model defaults in place and is not necessarily equivalent: some Claude models disable thinking explicitly, while those that require it use adaptive thinking with low effort. See [Disabling Thinking](../../guides/thinking/index.md#disabling-thinking) in the guide. ## Task Budget @@ -558,7 +703,7 @@ for a complete local-server configuration. ## Custom HTTP Headers For OpenAI-compatible providers (`openai`, `github-copilot`, `mistral`, `xai`, -`nebius`, `nvidia`, `minimax`, `baseten`, `daoxe`, `ovhcloud`, `groq`, `fireworks-ai`, `deepseek`, `cerebras`, `togetherai`, `huggingface`, `moonshotai`, `vercel`, `cloudflare-workers-ai`, `cloudflare-ai-gateway`, `requesty`, `openrouter`, `atlascloud`, `ollama`, and any custom provider using the OpenAI API), +`nebius`, `nvidia`, `minimax`, `baseten`, `daoxe`, `ovhcloud`, `groq`, `fireworks-ai`, `deepseek`, `cerebras`, `togetherai`, `huggingface`, `moonshotai`, `vercel`, `cloudflare-workers-ai`, `cloudflare-ai-gateway`, `requesty`, `openrouter`, `opper`, `runcrate`, `lunaroute`, `orcarouter`, `atlascloud`, `popnow`, `cloudgpu`, `obscurify`, `hopbase`, `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 47ce1666e167..0a739bf01285 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 @@ -17,7 +17,7 @@ A Docker Agent config can be written in YAML or HCL. The examples on this page u A Docker Agent config has these main sections: -```bash +```yaml # 1. Version — configuration schema version (optional but recommended) version: 16 @@ -50,6 +50,7 @@ rag: strategies: - type: chunked-embeddings embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 # 6. MCPs — reusable MCP server definitions (optional) mcps: @@ -155,7 +156,7 @@ See [Provider Credentials](../../providers/overview/index.md#provider-credential | `DOCKER_AGENT_HIDE_TELEMETRY_BANNER`| Set to `1` to suppress the first-run telemetry notice. | | `DOCKER_AGENT_AUTO_UPDATE` | Set to a truthy value (`1`, `true`, `yes`, `on`) to let standalone release binaries self-update before running. See [Optional Self-Updates](../../getting-started/installation/index.md#optional-self-updates). | | `DOCKER_AGENT_NO_TOKEN_EXCHANGE` | Set to `1` to stop Docker Agent from exchanging the access token stored by `docker login` for a Docker token. See [Docker authentication](../../guides/secrets/index.md#docker-authentication). | -| `DOCKER_AGENT_HUB_LOGIN_URL` | Point the token exchange at a Docker staging environment. Ignored unless it is an HTTPS `docker.com` URL. | +| `DOCKER_AGENT_HUB_LOGIN_URL` | Point the token exchange at a Docker staging environment. Ignored unless it is an HTTPS `docker.com` URL. A staging host, such as `hub-stage.docker.com`, also makes Docker Agent read staging sessions from the Docker secrets engine. | | `DOCKER_AGENT_DISABLE_DESKTOP_PROXY` | Set to a truthy value (`1`, `true`, `yes`, `on`) to bypass Docker Desktop's PAC adapter per request and restore standard `HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY`/`NO_PROXY` routing. | > [!NOTE] @@ -278,13 +279,13 @@ Docker Agent validates your configuration at startup: - Named model references must exist in the `models` section - Provider names must be valid (`openai`, `anthropic`, `google`, `dmr`, etc.) - Required environment variables (API keys) must be set -- Tool-specific fields are validated (e.g., `path` is only valid for `memory`) +- Tool-specific fields are validated (e.g., `path` is only valid for `memory` and `tasks`) ## JSON Schema For YAML editor autocompletion and validation, use the [Docker Agent JSON Schema](https://github.com/docker/docker-agent/blob/main/agent-schema.json). Add this to the top of your YAML file: -```bash +```yaml # yaml-language-server: $schema=https://raw.githubusercontent.com/docker/docker-agent/main/agent-schema.json ``` @@ -467,7 +468,7 @@ agents: | Field | Description | | --------------------- | ---------------------------------------------------------------------------------------- | | `provider` | Underlying provider type: `openai` (default), `anthropic`, `google`, `amazon-bedrock`, etc. | -| `api_type` | API schema: `openai_chatcompletions` (default) or `openai_responses`. OpenAI-only. | +| `api_type` | API schema: `openai_chatcompletions` or `openai_responses`. If omitted, selected from the model: Responses for supported newer OpenAI models, Chat Completions otherwise. Applies to OpenAI-compatible providers. | | `base_url` | Base URL for the API endpoint. Required for OpenAI-compatible providers. | | `token_key` | Environment variable name for the API token. | | `temperature` | Default sampling temperature. | diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/permissions/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/permissions/index.md index b04b6a5bfefa..927a9a1a85c4 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/permissions/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/permissions/index.md @@ -6,8 +6,6 @@ weight: 70 canonical: https://docs.docker.com/ai/docker-agent/configuration/permissions/ --- -_Control which tools can execute automatically, require confirmation, or are blocked entirely._ - ## Overview Permissions provide fine-grained control over tool execution. You can configure which tools are auto-approved (run without asking), which require user confirmation, and which are completely blocked. @@ -255,28 +253,39 @@ permissions: - "shell" ``` -### Safe Shell Agent +### Shell Agent with Safety Classification -Allow specific safe commands, block dangerous ones: +Use balanced safety without broad command-prefix allows: ```yaml -permissions: - allow: - - "shell:cmd=ls*" - - "shell:cmd=cat*" - - "shell:cmd=grep*" - - "shell:cmd=find*" - - "shell:cmd=head*" - - "shell:cmd=tail*" - - "shell:cmd=wc*" - deny: - - "shell:cmd=sudo*" - - "shell:cmd=rm*" - - "shell:cmd=mv*" - - "shell:cmd=chmod*" - - "shell:cmd=chown*" +runtime: + safety: balanced ``` +Balanced runs positively classified safe calls automatically and asks for approval +for unknown or destructive calls; it does not automatically deny them. This applies +to both `shell` and `run_background_job`. + +Explicit allow grants authorize matching arguments and override the safety mode's +fallback, including strict and restricted. For example, `shell:cmd=find*` also +authorizes `find / -exec rm -rf {} +` and +`find . -maxdepth 1 -name seed -exec sh -c 'touch marker' {} +`. A command name +alone does not establish that its arguments are safe. Avoid these broad grants +when you want classification to decide whether approval is needed. + +For these two builtin command tools, allow rules whose `cmd` value is a literal +followed by a single `*` reject shell chaining, redirection, and substitutions. +Command-name prefixes such as `cmd=ls*` additionally require a token boundary, +so they do not authorize `lsanything`. Argument and path prefixes such as +`cmd=ls *`, `cmd=git commit *`, and `cmd=ls /tmp/*` retain prefix matching. +Ordinary colons in values (quoted filenames or URLs) remain literal; only +`:key=` introduces another condition. + +This hardening does not inspect execution or write options such as `find -exec`. +Other glob shapes (`cmd=ls**`, `cmd=[l]s*`) and the `command=ls*` condition +retain generic matching and can authorize compound commands. Bare-tool grants, +`cmd=*`, and exact compound-command grants also remain broad explicit opt-ins. + ### MCP Tool Permissions Control MCP tools by their qualified names: diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/routing/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/routing/index.md index b96cf4054f54..8eb73a50d0c6 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/routing/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/routing/index.md @@ -6,8 +6,6 @@ weight: 100 canonical: https://docs.docker.com/ai/docker-agent/configuration/routing/ --- -_Route requests to different models based on the content of user messages._ - ## Overview Model routing lets you define a "router" model that automatically selects the best underlying model based on the user's message. This is useful for cost optimization, specialized handling, or load balancing across models. 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 fb2a4e704775..b13f0d9133c5 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 @@ -6,8 +6,6 @@ weight: 80 canonical: https://docs.docker.com/ai/docker-agent/configuration/sandbox/ --- -_Run agents in an isolated [Docker sandbox VM](https://docs.docker.com/ai/sandboxes/)._ - ## Overview Sandbox mode integrates Docker Agent with [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/). @@ -98,7 +96,7 @@ weakening a kit's restrictions or silently copying local credentials. Any provider, registry, or tool endpoint the agent needs must be reachable under the cloud policy. CLI-specified model, safety, flavor, and prompt options still apply. -Docker Agent uses `sbx --cloud run --detached`, then `exec`: this supports sbx's +Docker Agent uses `sbx --cloud run --detach`, then `exec`: this supports sbx's v3 source builds and multi-kit assembly without launching a second agent TUI. Provisioning messages go to stderr, leaving stdout for the agent (including `--json` output). Piped/headless execution does not allocate a TTY. @@ -367,10 +365,10 @@ This host auto-kit is distinct from an sbx workload/mixin kit. It is built for l 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/`, `.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/`. +- **Prompt files** — every file referenced via the agent's `add_prompt_files` (`AGENTS.md`, `CLAUDE.md`, …) is collected. Paths under the working directory are left to the live workspace mount, even when a file or intermediate directory is a symlink pointing outside it. Such links do not cause their host targets to be copied into the kit and may be unreadable inside the sandbox. Files discovered outside the workspace (e.g. an `AGENTS.md` in `$HOME` or a parent directory) are still copied under `/prompt_files/`, unless they resolve into the workspace. - **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. -Before launch, Docker Agent prints a summary of what was staged so you can see exactly which skills and prompt files the agent will have access to inside the sandbox. +Before launch, Docker Agent prints a summary of staged skills and prompt files, plus prompt-file paths left to the workspace mount. A workspace entry does not guarantee that its symlink target is accessible inside the sandbox. When building a kit, `add_prompt_files` entries must be local relative paths (e.g. `AGENTS.md` or `instructions/AGENTS.md`), not absolute paths or paths diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/structured-output/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/structured-output/index.md index 1092dbfff410..0b55d18361a6 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/structured-output/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/structured-output/index.md @@ -6,20 +6,10 @@ weight: 90 canonical: https://docs.docker.com/ai/docker-agent/configuration/structured-output/ --- -_Force the agent to respond with JSON matching a specific schema._ - ## Overview Structured output constrains the agent's responses to match a predefined JSON schema. This is useful for building agents that need to produce machine-readable output for downstream processing, API responses, or integration with other systems. -> [!NOTE] -> **When to Use** -> -> - Building API endpoints that need consistent JSON responses -> - Data extraction and transformation pipelines -> - Agents that feed into other automated systems -> - Ensuring predictable output format for parsing - ## Configuration ```yaml @@ -252,4 +242,4 @@ agents: > [!WARNING] > **Tool Limitations** > -> When using native structured output, the agent typically cannot use tools since its response format is constrained to the schema. Design your agent workflow accordingly — native structured output agents work best for single-turn analysis or extraction tasks. Use `mode: tool` when the agent needs to call tools before producing its schema-constrained final answer. +> Native structured output can coexist with tool calls when the provider and model support both; Docker Agent sends the tools alongside the output schema. Check your provider's restrictions rather than assuming tools are disabled. Use `mode: tool` when native schemas are unsupported or you want the final response submitted through an explicit output tool. diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/telemetry/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/telemetry/index.md index 55cdfdf7ea88..4c4f66dc6759 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/telemetry/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/telemetry/index.md @@ -10,10 +10,12 @@ aliases: _Docker Agent collects usage data to help improve the tool. Telemetry can be disabled at any time._ -On first startup, Docker Agent displays a notice about telemetry collection so you're always informed. Ordinary telemetry events are sent asynchronously; selected error events are sent synchronously before exit. +On first startup, Docker Agent displays a notice about telemetry collection. Ordinary telemetry events are sent asynchronously; selected error events are sent synchronously before exit. ## Disabling Telemetry +Telemetry is **enabled by default**. Set `TELEMETRY_ENABLED=false` to opt out: + ```bash # Disable via environment variable $ TELEMETRY_ENABLED=false docker agent run agent.yaml @@ -22,11 +24,6 @@ $ TELEMETRY_ENABLED=false docker agent run agent.yaml $ export TELEMETRY_ENABLED=false ``` -> [!NOTE] -> **Default** -> -> Telemetry is **enabled by default**. Set `TELEMETRY_ENABLED=false` to opt out. - ## What's Collected ✅ - Command names, positional arguments, and success/failure status 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 e115044986f8..d437639125d6 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 @@ -9,8 +9,6 @@ aliases: - /ai/docker-agent/reference/toolsets/ --- -_Complete reference for configuring built-in tools, MCP tools, and Docker-based tools._ - ## Built-in Tools Built-in tools are included with Docker Agent and require no external dependencies. Add them to your agent's `toolsets` list by `type`. Each tool's dedicated page covers its full configuration options, available operations, and examples. @@ -23,7 +21,7 @@ Built-in tools are included with Docker Agent and require no external dependenci | `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) | -| `environment` | Report the OS and resolved shell (read-only, no arguments, auto-approved) | [Environment](../../tools/environment/index.md) | +| `environment` | Report the OS and resolved shell (read-only, no arguments; subject to approval policy) | [Environment](../../tools/environment/index.md) | | `datetime` | Current date and time in a model-chosen format and timezone (read-only) | [Date and Time](../../tools/datetime/index.md) | | `calculator` | Exact arithmetic without code execution | [Calculator](../../tools/calculator/index.md) | | `think` | Reasoning scratchpad | [Think](../../tools/think/index.md) | @@ -134,10 +132,6 @@ Where the aqua registry includes a checksum manifest, downloaded binaries are ve - **Unsupported or weak checksum types (e.g. md5, sha1)** — skipped with a warning; installation proceeds without verification. - **No manifest** — if no checksum is advertised in the registry entry, the binary is installed without verification. -### version_overrides Resolution - -The auto-installer correctly resolves **`version_overrides`** entries in the aqua registry. Many common tools (for example, `fzf`) keep their package configuration — including download URLs and checksums — under `version_overrides` rather than at the top level of their registry entry. These tools previously failed to install silently; they are now handled correctly. - ### Disabling Auto-Install **Per toolset** — set `version` to `"false"` or `"off"`: @@ -234,7 +228,7 @@ toolsets: > [!NOTE] > **`required` is not yet enforced** > -> The schema validates this field and the supervisor stores it, but no code path acts on it yet. It is documented now so config files written today keep working when the planned eager-startup phase lands. Picking the `strict` profile is forward-compatible — it will start enforcing `required=true` automatically. +> `required` is informational and does not prevent an agent from starting when a toolset is unavailable. ### Inspecting and restarting toolsets at runtime @@ -374,7 +368,7 @@ See [`examples/toolset_instructions.yaml`](https://github.com/docker/docker-agen ## Deferred Tool Loading -Load tools on-demand to speed up agent startup. When a toolset is deferred, its tools are registered lazily — the tool server process is not started until the agent first calls one of its tools. This is useful for large toolsets (e.g., an MCP server with hundreds of tools) where startup time matters. +Expose tool definitions to the model on demand to reduce prompt size. Deferred toolsets still start normally, including their MCP server processes, but their tool definitions stay hidden until activated. This is useful for large toolsets, such as an MCP server with hundreds of tools; it does not delay server startup. ```yaml toolsets: @@ -426,7 +420,7 @@ models: Every deferred tool is then declared to the API with `defer_loading: true` next to a server-executed `tool_search` tool, so the model discovers and calls deferred tools directly, without a `search_tool`/`add_tool` round trip. `search_tool` and `add_tool` stay available. Toolset `tools`, `read_only`, and skill allow-lists apply to the catalog exactly as they do to regular tools, and so do permissions. -The option is ignored, and the legacy behaviour kept, for models without support (only `openai` models that support deferred tools qualify; the `chatgpt` provider and OpenAI-compatible endpoints, including `openai` with a custom `base_url`, do not), on Chat Completions requests, and on fallback models without the option. Agents using `code_mode_tools` keep the legacy behaviour: wrapped tools are reachable through `run_tools_with_javascript`, while todo and repeatable tools remain directly callable. +The option is ignored, and the legacy behaviour kept, for models without support (only `openai` models that support deferred tools qualify; the `chatgpt` provider and OpenAI-compatible endpoints, including `openai` with a custom `base_url` or `OPENAI_BASE_URL`, do not), on Chat Completions requests, and on fallback models without the option. Agents using `code_mode_tools` keep the legacy behaviour: wrapped tools are reachable through `run_tools_with_javascript`, while todo and repeatable tools remain directly callable. Native search also enables ordered response replay, including encrypted reasoning. For native-only workflows, tell the agent to prefer native tool search over `search_tool`/`add_tool`; those tools remain available for fallback models. diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/user-settings/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/user-settings/index.md index a0a689b9bff7..11b2701ee8e4 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/user-settings/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/user-settings/index.md @@ -7,8 +7,6 @@ weight: 110 canonical: https://docs.docker.com/ai/docker-agent/configuration/user-settings/ --- -_Full reference for the global settings block in your user config file._ - ## Where Settings Live Docker Agent reads a single user-level config file, independent of any agent YAML: @@ -40,7 +38,7 @@ You rarely need to hand-edit this file. Most fields are managed from the TUI's ` | `expand_thinking` | boolean | `false` | Start new sessions with thinking/tool blocks expanded instead of collapsed. | | `split_diff_view` | boolean | `true` | Render file-edit diffs side-by-side instead of unified. | | `render_images` | boolean | `true` | Render images in the TUI using the Kitty graphics protocol. Applies to both tool-result images and Markdown images in agent responses. Automatically disabled when the terminal does not support Kitty. | -| `show_banner` | boolean | `true` | Show the ASCII-art startup banner on an empty conversation. Applies to both the full TUI and the [lean TUI](../../features/tui/index.md#lean-tui). Managed from the **Appearance** tab of `/settings`. | +| `show_banner` | boolean | `true` | Show the braille wordmark startup banner. In the full TUI it appears on an empty conversation; in the [lean TUI](../../features/tui/index.md#lean-tui) it is printed at the start of the transcript, before any resumed session. Managed from the **Appearance** tab of `/settings` in the full TUI; the lean TUI's `/settings` panel has a *Show startup banner* toggle (labeled "next launch") that is saved for future launches. Unlike other settings marked **next launch**, saving it also adds or removes the banner in the current session, but only while the session's welcome block is still in the transcript: it cannot erase a banner already printed to your terminal scrollback, and after resuming another session with `/sessions` there is no welcome block to update. | | `theme` | string | `default` | Theme name, loaded from a built-in theme or `~/.cagent/themes/.yaml`. The special value `auto` follows the terminal's light/dark background. See [Theming](../../features/tui/index.md#theming). | | `theme_dark` | string | `default` | Theme applied when `theme: auto` and the terminal background is dark. | | `theme_light` | string | `default-light` | Theme applied when `theme: auto` and the terminal background is light. | @@ -53,6 +51,8 @@ You rarely need to hand-edit this file. Most fields are managed from the TUI's ` | `sound` | boolean | `false` | Play a notification sound on task success or failure. | | `sound_threshold` | int | `10` | Minimum duration in seconds a task must run before a success sound plays (failures always play). | | `snapshot` | boolean | `false` | Enable automatic shadow-git snapshots at turn boundaries globally. See [Snapshots](../../features/snapshots/index.md). | +| `background_compaction` | boolean | `false` | Generate automatic compaction summaries while the agent continues working. Apply completed summaries between turns, preserving messages added during generation. Unfinished work is cancelled when the stream ends. | +| `background_compaction_threshold` | integer | `70` | Context-window percentage (1–99) at which background compaction starts. Invalid values fall back to 70. Set below the agent's blocking `compaction_threshold` (90% by default) to allow time for generation. | | `cache_stable_prompts` | boolean | `false` | Keep changing trusted context (date, environment info, dynamic prompt files) out of the frozen system prefix and append chronological updates instead, improving prompt-cache hit rates on long sessions. | | `warn_on_cache_miss` | boolean | `false` | Warn when a model call after the first one in a session reports no cached input tokens (a prompt-cache miss). Managed from the **Notifications** tab of `/settings`. | | `busy_send_mode` | string | `steer` | What happens to a message sent while the agent is working: `steer` injects it into the ongoing stream; `queue` holds it until the current turn ends. | @@ -107,6 +107,8 @@ settings: sound_threshold: 10 snapshot: true cache_stable_prompts: true + background_compaction: true + background_compaction_threshold: 70 warn_on_cache_miss: true busy_send_mode: queue interrupt_confirmation: double-tap diff --git a/_vendor/github.com/docker/docker-agent/docs/features/a2a/index.md b/_vendor/github.com/docker/docker-agent/docs/features/a2a/index.md index 3be53136e9b2..6ac42f169c8d 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/a2a/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/a2a/index.md @@ -8,8 +8,6 @@ aliases: - /ai/docker-agent/integrations/a2a/ --- -_Expose Docker Agent agents via Google's Agent-to-Agent (A2A) protocol for interoperability with other agent frameworks._ - ## Overview The `docker agent serve a2a` command starts an A2A server that exposes your agents using the [A2A protocol](https://a2a-protocol.org/latest/). This enables communication between Docker Agent and other agent frameworks that support A2A. diff --git a/_vendor/github.com/docker/docker-agent/docs/features/acp/index.md b/_vendor/github.com/docker/docker-agent/docs/features/acp/index.md index 5007be77313d..5af15be82715 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/acp/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/acp/index.md @@ -9,8 +9,6 @@ aliases: - /ai/docker-agent/integrations/acp/ --- -_Expose Docker Agent agents via the Agent Client Protocol for integration with ACP-compatible hosts like VS Code, IDEs, and other developer tools._ - ## Overview The `docker agent serve acp` command starts an ACP server that communicates over **stdio** (standard input/output). This makes it ideal for integration with editors, IDEs, and other tools that spawn agent processes — the host sends JSON-RPC messages to Docker Agent's stdin and reads responses from stdout. @@ -24,7 +22,12 @@ ACP is built on the [ACP Go SDK](https://github.com/coder/acp-go-sdk) and provid ## Usage +Without an agent argument, the server uses the `default` built-in agent (or your `default` alias, if configured). + ```bash +# Start ACP server with the default agent +$ docker agent serve acp + # Start ACP server on stdio $ docker agent serve acp ./agent.yaml @@ -106,7 +109,7 @@ Send W3C context in **request/notification `params._meta`**, not at the JSON-RPC Each implemented agent request/notification starts an `acp.` SERVER span, linked to valid incoming context and enclosing its handler. These boundary spans record only the static RPC method, not request content, paths, credential metadata, or raw errors. Invalid/non-string/oversized trace fields are ignored; each accepted field is bounded to 512 bytes and validated by the W3C propagator. A bad tracestate does not invalidate a valid traceparent. Client baggage and arbitrary `_meta` fields are not imported into tracing. -The request context flows into existing runtime/model/tool instrumentation. Outgoing ACP session updates, permission requests, filesystem operations, terminal operations (including detached cleanup), and elicitation carry only `traceparent`/`tracestate` in `params._meta`. Metadata is copied before injection; stale trace fields and baggage are removed. Response metadata is never adopted as the current trace. MCP elicitation and sampling callbacks use the sole owning tool call's trace rather than the connection's setup trace; existing ambiguous-owner restrictions remain in effect. +The request context flows into existing runtime/model/tool instrumentation. Outgoing ACP session updates, permission requests, filesystem operations, terminal operations (including detached cleanup), and elicitation carry only `traceparent`/`tracestate` in `params._meta`. Metadata is copied before injection; stale trace fields and baggage are removed. Response metadata is never adopted as the current trace. MCP elicitation callbacks use the sole owning tool call's trace rather than the connection's setup trace; existing ambiguous-owner restrictions remain in effect. Traces are not stored on sessions: concurrent and later prompts use their own incoming context. Terminal final-close retries use the cleanup caller's context, not a remembered creation trace. Detached background/drain work may outlive the handler span while retaining its trace. This adds request SERVER spans and propagation, not separate ACP CLIENT spans for every outbound call, response metadata, or automatic metadata on unsupported SDK methods. Existing runtime/provider telemetry and its content-capture settings retain their own policy; the boundary-span restriction is not a global telemetry-redaction guarantee. @@ -433,7 +436,7 @@ Captured file contents are presentation-only metadata, excluded from generic res ## CLI Flags ```bash -docker agent serve acp | [flags] +docker agent serve acp [|] [flags] ``` See the [CLI reference](../cli/index.md#docker-agent-serve-acp) for all flags, defaults, and shared runtime options. 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 963772bc1f0f..d450e73524d6 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 @@ -6,8 +6,6 @@ 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._ - ## Overview The `docker agent serve api` command starts an HTTP server that exposes your agents through a REST-style API with Server-Sent Events (SSE) streaming. Use it to build web UIs, integrate with CI/CD pipelines, or connect agents to other services. @@ -211,7 +209,9 @@ Event types include: - `stream_started` / `stream_stopped` — Agent execution lifecycle - `agent_choice` — Streamed text content (partial responses) - `agent_choice_reasoning` — Streamed reasoning content +- `agent_choice_reasoning_reset` — Discard all reasoning accumulated for the identified `session_id` and `message_id` (for example, after a server fallback). Keep text, other messages, and tool calls; later reasoning deltas append to the now-empty buffer. This is an ordering barrier, never coalesced with deltas - `partial_tool_call` — Streamed tool-call arguments, keyed by `tool_call.id`. The first one also carries `tool_definition` +- `tool_calls_retracted` — Tool calls announced by `partial_tool_call` that will never run, listed in `tool_call_ids`: the model refused, the response was cut off by the output-token limit (`finish_reason: length`) while a tool call was still streaming, or a server fallback handed the turn to another model - `tool_call` — Agent requesting tool execution - `tool_call_output` — Streamed output of a running tool, keyed by `tool_call_id` - `tool_call_confirmation` — Tool call waiting for user approval @@ -219,6 +219,8 @@ Event types include: - `plan_changed` — A shared plan was created, updated, or deleted through the plan toolset. The payload carries the plan's `scope`, `name`, `action`, and `version` — never its content. Shared plans are deliberately process-global: every active stream served by the same process subscribes to the same shared plan notifier and receives the event regardless of which session performed the mutation, and the payload does not identify the mutating session (read the plan's `author` metadata for collaborative attribution). - `error` — Error during execution +Append-only outputs such as CLI `--exec` and ACP thought chunks cannot retract bytes already delivered; their consumers may still show declined reasoning. The mutable TUI, lean TUI, WASM demo and persisted transcript apply the reset. + ## Typical Workflow 1. **List agents** — `GET /api/agents` to discover available agents @@ -338,6 +340,11 @@ $ docker agent run agent.yaml --listen 127.0.0.1:8080 $ docker agent run agent.yaml --listen unix:///tmp/my-run.sock ``` +`fd://N` adopts an inherited listening socket (a Winsock socket handle on +Windows). It closes the supplied descriptor after duplicating it; callers must +not close that descriptor again. The inherited listener retains its bound +address and the same authentication requirements as a directly bound listener. + The run keeps its interactive TUI; the control plane runs alongside it. A follow-up delivered over HTTP is processed exactly as if it had been typed into the TUI: it starts a turn even when the agent is idle, generates the 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 index 176966a7e59c..cdb2a9dee86e 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/board/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/board/index.md @@ -76,7 +76,7 @@ board: projects: - name: my-app path: /Users/me/src/my-app - agent: coder # any agent ref; defaults to the built-in agent + agent: default # any agent ref; defaults to the built-in agent columns: - id: dev name: Dev diff --git a/_vendor/github.com/docker/docker-agent/docs/features/chat-server/index.md b/_vendor/github.com/docker/docker-agent/docs/features/chat-server/index.md index ec8746ca61af..c5aa140bed59 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/chat-server/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/chat-server/index.md @@ -6,8 +6,6 @@ weight: 90 canonical: https://docs.docker.com/ai/docker-agent/features/chat-server/ --- -_Expose your agents through an OpenAI-compatible Chat Completions API so any tool that already speaks OpenAI can drive a Docker Agent agent._ - ## Overview The `docker agent serve chat` command starts an HTTP server that exposes one or 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 5b885cac9902..852aa33721c0 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 @@ -8,12 +8,10 @@ aliases: - /ai/docker-agent/reference/cli/ --- -_Complete reference for all Docker Agent command-line commands and flags._ - > [!TIP] > **No config needed** > -> Running `docker agent run` without a config argument uses `docker-agent.yaml`, `docker-agent.yml`, or `docker-agent.hcl` from the current directory when present. Otherwise, it uses a built-in default agent that is perfect for quick experimentation. +> Running `docker agent run` without a config argument uses `docker-agent.yaml`, `docker-agent.yml`, or `docker-agent.hcl` from the current directory when present. Otherwise, it uses the built-in `default` coding agent. Use `docker agent run minimal` for a small general-purpose configuration. ## Commands @@ -30,7 +28,7 @@ $ docker agent run [config] [message...] [flags] | `-a, --agent ` | Run a specific agent from the config | | `--yolo` | Auto-approve tool calls (unless explicitly denied). Legacy alias for `--safety autonomous`. | | `--safety ` | Safety mode for tool approval: `strict` (ask for everything), `balanced` (auto-approve safe calls), `restricted` (auto-approve safe calls, deny the rest — fail-closed for unattended runs), or `autonomous` (approve everything). Wins over `--yolo` when both are given. Without the flag, the mode falls back to alias/user-config defaults, then the agent YAML's `agents..safety` / `runtime.safety`; a resumed session keeps its stored mode unless `--safety`/`--yolo` is passed explicitly. See [Safety Modes](../../configuration/permissions/index.md#safety-modes). | -| `--model ` | Override model(s). Use `provider/model` for all agents, or `agent=provider/model` for specific agents. Comma-separate multiple overrides. Inline overrides inherit each agent's explicit `parallel_tool_calls` setting only from a concrete, provider-qualified configured model. Existing named targets are authoritative on every invocation, including an omitted setting; harness, router, alloy/comma-list, `first_available`, providerless, and unresolved source models do not inherit it. | +| `--model ` | Override model(s). Use `provider/model` for all agents, or `agent=provider/model` for specific agents. Repeat the flag or comma-separate multiple overrides — the comma form only works when every segment is agent-scoped (`root=a,other=b`); a mixed `global,agent=spec` list is not split (one spec may legitimately contain commas, e.g. an alloy/`first_available` list) and should use repeated `--model` flags instead. Inline overrides inherit each agent's explicit `parallel_tool_calls` setting only from a concrete, provider-qualified configured model. Existing named targets are authoritative on every invocation, including an omitted setting; harness, router, alloy/comma-list, `first_available`, providerless, and unresolved source models do not inherit it. | | `--session ` | Resume a previous session. Supports relative refs (`-1` = newest by creation time, `-2` = second-newest, … — creation order, not last-used). 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: `/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`. | @@ -41,7 +39,7 @@ $ docker agent run [config] [message...] [flags] | `--remote-auth-token ` | Bearer token for `--remote`. Defaults to `DOCKER_AGENT_REMOTE_AUTH_TOKEN`; the flag takes precedence. Prefer the environment variable to keep the token out of command-line arguments. | | `--listen ` | Expose this run's control plane over HTTP so an external process can drive the running TUI (send follow-ups, stream events, read the title). Accepts `host:port` or `unix://`, `npipe://`, `fd://`. Hidden from `docker agent run --help` — it's a stable but advanced/automation-oriented flag rather than a day-to-day one. See the [API Server](../api-server/index.md#listen) guide for the full walkthrough. | | `--session-workingdir-root ` | Confine the `working_dir` of sessions created through the `--listen` control plane to this directory and its descendants (default: no restriction — any clean host directory is accepted, though raw values containing `..` are rejected). Recommended when the control plane is reachable by other users. Hidden from `--help`, like `--listen`. | -| `--lean` | Use a simplified, non-alternate-screen TUI. Unlike the default full-screen TUI, this renders inline in the normal terminal buffer — useful in environments where an alternate screen is unwanted (e.g. inside tmux panes, CI with a tty, or log-friendly pipelines). Like the full TUI, displays an ASCII art banner on startup when the chat is empty (configurable via `show_banner` in [user settings](../../configuration/user-settings/index.md)). | +| `--lean` | Use a simplified, non-alternate-screen TUI. Unlike the default full-screen TUI, this renders inline in the normal terminal buffer — useful in environments where an alternate screen is unwanted (e.g. inside tmux panes, CI with a tty, or log-friendly pipelines). Like the full TUI, displays a braille wordmark banner at the start of the transcript (configurable via `show_banner` in [user settings](../../configuration/user-settings/index.md)). | | `--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"`. | @@ -51,13 +49,14 @@ $ docker agent run [config] [message...] [flags] | `--last` | Print only the final agent answer after all turns finish (requires `--exec`); omit thinking, tool calls/results, and intermediate responses | | `--hide-tool-calls` | Hide tool calls in the output | | `--hide-tool-results` | Hide tool call results in the output | -| `--sandbox` | Run the agent in sandbox mode using `sbx` (see [Sandbox](../../configuration/sandbox/index.md)) | +| `--sandbox` | Run the agent in sandbox mode using standalone `sbx` or the `docker sandbox` plugin (see [Sandbox](../../configuration/sandbox/index.md)) | +| `--sbx` | Prefer standalone `sbx` when available (default: `true`); set `--sbx=false` to force the `docker sandbox` plugin. | | `--cloud` | Run in a fresh cloud sandbox without uploading host files/config/credentials; implies `--sandbox`. See [cloud sandbox mode](../../configuration/sandbox/index.md#cloud-sandboxes). | | `--sandbox-kit`, `--kit`, `--kit-arg` | Select an sbx workload and mixins, and pass kit arguments. Supports kits v3 through sbx. | | `--sandbox-ttl` | Cloud sandbox lifetime, default `1h`; stopped on expiry and when the agent exits. | | `--template ` | Template image for the sandbox (default: `docker/docker-agent-sbx-templates:latest`) | | `--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 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. | +| `--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 `minimal` 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`. | @@ -89,6 +88,9 @@ $ docker agent run agent.yaml --model "dev=openai/gpt-4o,reviewer=anthropic/clau $ docker agent run agent.yaml --session -1 # resume last session $ docker agent run agent.yaml --session -1 --session-read-only # review last session without sending messages $ docker agent run agent.yaml --prompt-file ./context.md # include file as context +$ docker agent run agent.yaml --model "root=openai/gpt-4o,anthropic/claude-sonnet-4-5" # agent-scoped alloy: commas stay inside the spec +$ docker agent run agent.yaml --model "openai/gpt-4o,anthropic/claude-sonnet-4-5" # global alloy applied to every agent +$ docker agent run agent.yaml --model openai/gpt-4o --model "reviewer=anthropic/claude-sonnet-4-5" # mix global + agent-scoped via repeated flags # Add hooks from the command line $ docker agent run agent.yaml --hook-session-start "./scripts/setup-env.sh" @@ -110,7 +112,7 @@ $ docker agent run --agent-picker=myorg/coder,myorg/researcher > [!TIP] > **Lean, inline TUI** > -> Pass `--lean` to get a lightweight TUI that renders inline in your terminal (no alternate screen). Like the full TUI, it displays an ASCII art banner on startup when the chat is empty (configurable via `show_banner` in [user settings](../../configuration/user-settings/index.md)), and supports the same slash commands and streaming output, making it handy inside tmux, scripts, or any context where a full-screen takeover is unwanted. +> Pass `--lean` to get a lightweight TUI that renders inline in your terminal (no alternate screen). Like the full TUI, it displays a braille wordmark banner at the start of the transcript (configurable via `show_banner` in [user settings](../../configuration/user-settings/index.md)), and supports the same slash commands and streaming output, making it handy inside tmux, scripts, or any context where a full-screen takeover is unwanted. > [!TIP] > **Background animations in tmux** @@ -147,6 +149,22 @@ $ docker agent run agent.yaml --worktree-pr https://github.com/owner/repo/pull/1 With `--worktree-pr`, the PR's head branch is checked out tracking its remote (via the [GitHub CLI](https://cli.github.com/)), so commits made during the run push straight back to the pull request. The worktree is stored under `/worktrees/pr-`. +#### Copy ignored files into worktrees + +Add a `.worktreeinclude` at the source repository root to copy selected **gitignored** files into new `--worktree`, `--worktree-pr`, and [background agent](../../tools/background-agents/index.md) worktrees before setup hooks run: + +```gitignore +.env.local +config/*.local.yaml +!config/private.local.yaml +``` + +Patterns use Git's `.gitignore` syntax, including comments, negations and directory patterns. Git's normal rules for ignored parent directories apply: to exclude a child, include the parent with a pattern such as `cache/*` rather than `cache/`. Only files ignored by Git in both the source and destination checkouts are copied. A file not ignored in the destination is skipped with a warning; add appropriate ignore rules to the destination base or PR if it is needed there. Destination checks retry failed batches up to a fixed limit; if the limit is reached, unverified files are skipped with a warning, even if some would otherwise be eligible. This differs from tools that treat `.worktreeinclude` as a list of paths or also copy non-ignored files. Tracked changes and other untracked files are not copied. Missing `.worktreeinclude` leaves worktree creation unchanged. + +File permissions are preserved except that group or other permissions are removed when source ancestor directories prevent traversal for that class. New parent directories are private (`0700`). Existing destination files are never overwritten; symlinks, special files, `.gitignore`, and `.gitattributes` files are skipped. This prevents copies from changing the destination's ignore rules or staging attributes. Failures and skipped protected files produce bounded warnings without undoing the worktree; repeated protected-file skips are aggregated, and omitted warnings are counted. Cancellation stops copying and removes an incomplete file, leaving the worktree in place. Background-task warnings appear in the task metadata and logs. Files blocked by the source checkout's nearest [`.agentsignore`](../../configuration/agentsignore/index.md) are not copied, even if included here. `.agentsignore` itself is not copied by this mechanism. As always, `.agentsignore` only governs the filesystem toolset, not shell or other independent tools. + +Copied files are independent copies. **Ignored files do not make a worktree dirty**, so an interactive run can remove a clean worktree and its copied files automatically. Changing the destination's ignore rules later can make copied files visible to ordinary `git add`; `git add -f` can stage ignored files even without such a change. Changes to those copies do not propagate back to the source checkout; save anything needed before cleanup. + When the interactive session ends, the worktree is cleaned up based on its state: - **Clean** (no uncommitted changes, untracked files, or new commits): the worktree and its branch are removed automatically. @@ -199,6 +217,8 @@ $ docker agent new --model openai/gpt-5 $ docker agent new --model dmr/ai/gemma3-qat:12B --max-iterations 15 ``` +When `--max-iterations` is omitted (or `0`) and the agent creator uses a DMR model, the session reaches its iteration limit after 20 iterations. In the interactive TUI that pauses for a decision to continue (approving grants 10 more iterations) rather than ending the session; non-interactive runs stop. With other providers no limit is applied. An explicit non-zero value always wins. + ### `docker agent getting-started` Run a short (about 2 minutes), skippable interactive tour inside the chat UI: sending messages, approving tool calls, the command palette (Ctrl+K), slash commands, and how agents are configured. Aliased as `docker agent tour`. Requires an interactive terminal. @@ -389,10 +409,10 @@ $ docker agent serve a2a myorg/agent:tag ### `docker agent serve acp` -Start an ACP (Agent Client Protocol) server over stdio. This allows external clients to interact with your agents using the ACP protocol. +Start an ACP (Agent Client Protocol) server over stdio. This allows external clients to interact with your agents using the ACP protocol. If no config is specified, uses the `default` built-in agent (or your `default` alias, if configured). ```bash -$ docker agent serve acp [flags] +$ docker agent serve acp [config] [flags] ``` | Flag | Default | Description | @@ -403,6 +423,7 @@ All [runtime configuration flags](#runtime-configuration-flags) are also accepte ```bash # Examples +$ docker agent serve acp $ docker agent serve acp agent.yaml $ docker agent serve acp ./team.yaml $ docker agent serve acp myorg/agent:tag @@ -801,7 +822,11 @@ $ docker agent debug oauth login agent.yaml github > > The text output of `debug auth` truncates the token to a short preview, but `--json` includes the complete, unredacted JWT in its `token` field. Never paste `debug auth --json` output into logs, issue trackers, or bug reports — anyone with that token can act as you against Docker. Use the plain-text output (or redact the `token` field yourself) when sharing diagnostic output. -The `Source` field says where the token came from: `docker desktop`, or `minted from the stored access token` when it was obtained by exchanging the access token `docker login` stored. See [Docker authentication](../../guides/secrets/index.md#docker-authentication). +The `Source` field says where the token came from: `docker desktop secrets engine` when it was read from the secrets engine Docker Desktop serves, `docker desktop` when Docker Desktop's backend served it, or `minted from the stored access token` when it was obtained by exchanging the access token `docker login` stored. See [Docker authentication](../../guides/secrets/index.md#docker-authentication). + +`Username` and `Email` come from the secrets engine's session when the engine supplied the token, otherwise from Docker Desktop, and otherwise from the token itself. + +When the secrets engine couldn't be read, `Secrets engine` says why, `Socket` which socket was tried, and `Hint` how to fix it. The JSON output has them under `secrets_engine` as `reason`, `socket` and `hint`, along with the full `error`. A secrets engine that isn't running is only reported when no token was found, since machines without Docker Desktop don't have one. The `config`, `toolsets`, `tool`, `skills`, and `title` subcommands also accept [runtime configuration flags](#runtime-configuration-flags) (`--working-dir`, `--models-gateway`, …); `title` additionally accepts `--model` to override the model used to resolve the config before generating the title. diff --git a/_vendor/github.com/docker/docker-agent/docs/features/code-mode/index.md b/_vendor/github.com/docker/docker-agent/docs/features/code-mode/index.md index 218e242d9130..e7c647c8dd19 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/code-mode/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/code-mode/index.md @@ -73,7 +73,7 @@ It is not a general-purpose replacement for direct tool calls: for an agent that - **One string result.** The script must return a string; use `console.*` inside the script to print debug information if something doesn't behave as expected — it comes back to the model as `stdout`/`stderr` alongside the result, but is not displayed by the terminal UIs. - **Failures are diagnosable.** If the script throws or returns unexpectedly, the response includes the tool calls it made before failing (name, arguments, and result or error), so the model can see what happened and adjust the script on the next attempt. -- **Not every tool is wrapped.** Tools in the `todo` category and repeatable tools such as `random_int` and `get_datetime` stay directly callable as ordinary tools. Repeatable tools are unavailable inside scripts so successful calls retain their duplicate-loop exemption without exempting failed or unrelated scripts. +- **Not every tool is wrapped.** Tools executed by the runtime itself, such as `transfer_task`, `handoff`, `run_skill`, and the background-agent tools, stay directly callable as ordinary tools because scripts can't invoke them. Tools in the `todo` category and repeatable tools such as `random_int` and `get_datetime` stay directly callable as ordinary tools. Repeatable tools are unavailable inside scripts so successful calls retain their duplicate-loop exemption without exempting failed or unrelated scripts. - **The script runs in an embedded, sandboxed JS engine** ([goja](https://github.com/dop251/goja)), not Node.js or a browser: there is no filesystem, network, or process access beyond the tool functions injected into it. - **Partial startup is supported.** If one toolset fails to initialize (for example, an MCP server that won't connect), Code Mode remains available with the successfully loaded toolsets. The failed toolset is omitted from the JavaScript environment and retried on subsequent turns. A warning is emitted once when the failure first occurs, but not on subsequent turns while the failure persists. When the toolset recovers, its tools silently reappear in the environment. When the failed toolset's cause is retryable (e.g. an MCP server or RAG knowledge base hitting rate limits), its retries are paced by the same [backoff gate](../../tools/mcp/index.md#lifecycle-auto-restart-profiles) used outside code mode, instead of retrying on every turn. @@ -86,4 +86,4 @@ In practice this means enabling `code_mode_tools` collapses the approval granula > [!WARNING] > **Coarser approval granularity** > -> Approving a `run_tools_with_javascript` call approves every tool it might invoke internally, including ones that would otherwise need a separate `ask` or be blocked by a `deny` pattern under [Permissions](../../configuration/permissions/index.md). If an agent's toolset includes anything destructive, consider whether Code Mode's coarser granularity is acceptable for that agent before enabling it. Delegating to a separate, non-Code-Mode agent isn't a way out either: [handoff](../../tools/handoff/index.md) and [transfer_task](../../tools/transfer-task/index.md) are themselves wrapped like any other tool once `code_mode_tools` is on, but they have no code-mode-compatible handler — the model's script gets `tool "handoff" is not available in code mode` if it tries to call them. This only rules out the model *choosing* to delegate from inside the script: a configured `force_handoff` target on the agent still runs deterministically after the agent's turn naturally stops, regardless of Code Mode, since it's applied by the runtime outside the tool-call dispatch path Code Mode replaces. Keep `code_mode_tools` off any agent whose model needs to hand off or transfer to one that holds a destructive toolset. +> Approving a `run_tools_with_javascript` call approves every tool it might invoke internally, including ones that would otherwise need a separate `ask` or be blocked by a `deny` pattern under [Permissions](../../configuration/permissions/index.md). If an agent's toolset includes anything destructive, consider whether Code Mode's coarser granularity is acceptable for that agent before enabling it. [handoff](../../tools/handoff/index.md) and [transfer_task](../../tools/transfer-task/index.md) are not affected: they are executed by the runtime itself and stay directly callable as ordinary tools, so the model can still delegate normally. They just can't be called from inside a script — a script that tries gets `tool "handoff" is not available in code mode`. A configured `force_handoff` target also still runs after the agent's turn naturally stops, regardless of Code Mode. diff --git a/_vendor/github.com/docker/docker-agent/docs/features/evaluation/index.md b/_vendor/github.com/docker/docker-agent/docs/features/evaluation/index.md index e664b7ad7982..9859d7207d50 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/evaluation/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/evaluation/index.md @@ -8,8 +8,6 @@ aliases: - /ai/docker-agent/evals/ --- -_Measure agent quality with automated evaluations — tool call accuracy, response relevance, output size, and more._ - ## Overview The `docker agent eval` command runs your agent against a set of recorded sessions and scores the results. Each eval session captures a user question, the expected tool calls, and criteria the response must satisfy. Docker Agent replays the question, compares the agent's behavior to expectations, and produces a report. @@ -388,31 +386,26 @@ passing: a gate that cannot fail is worse than no gate. ### Provider Credentials -Eval containers are isolated from your host environment. Dedicated model -provider API keys (for example `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`) are -forwarded into eval containers automatically, so most provider setups work -without extra flags. +Eval containers do not automatically receive host environment variables, including +provider API keys, gateway settings, Docker tokens, or credentials referenced by +evaluators and hooks. Pass each required variable explicitly with `-e`: -> [!WARNING] -> **`GITHUB_TOKEN` and `GH_TOKEN` are not forwarded automatically** -> -> GitHub tokens are broad credentials (git, `gh`, CI, packages), not dedicated -> model API keys, so for security reasons Docker Agent does not forward them -> into eval containers — even when they are set in your shell or in -> `~/.config/cagent/.env`. If your agent uses the `github-copilot` provider, -> pass the token explicitly by name: -> -> ```bash -> docker agent eval agent.yaml ./evals -e GITHUB_TOKEN -> ``` -> -> When using a custom env file, both flags are required: -> -> ```bash -> docker agent eval agent.yaml ./evals \ -> --env-from-file /path/to/secrets.env \ -> -e GITHUB_TOKEN -> ``` +```bash +docker agent eval agent.yaml ./evals -e OPENAI_API_KEY +``` + +`-e NAME` resolves the value from the configured environment sources; +`-e NAME=VALUE` supplies a literal value. Loading a custom env file does not +implicitly forward its contents: + +```bash +docker agent eval agent.yaml ./evals \ + --env-from-file /path/to/secrets.env \ + -e GITHUB_TOKEN +``` + +To use a models gateway inside the container, explicitly pass +`DOCKER_AGENT_MODELS_GATEWAY` and any authentication variables it requires. Note that the judge runs on the host, not inside the eval container. If the token is not forwarded, judge validation can succeed while every diff --git a/_vendor/github.com/docker/docker-agent/docs/features/harnesses/index.md b/_vendor/github.com/docker/docker-agent/docs/features/harnesses/index.md index 1dcb5b202e1d..5f979d6adf31 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/harnesses/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/harnesses/index.md @@ -6,22 +6,10 @@ weight: 50 canonical: https://docs.docker.com/ai/docker-agent/features/harnesses/ --- -_Delegate coding tasks to external AI coding CLIs (Claude Code, Codex, opencode) as sub-agents._ - ## Overview A **harness** agent delegates its work to an external coding CLI — `claude` (Claude Code), `codex` (OpenAI Codex), `opencode`, `pi`, or `cmd` (Command Code) — instead of calling a model API directly. The external CLI drives the coding loop while Docker Agent provides orchestration, hooks, permissions, and distribution. -This pattern gives you the best of both worlds: - -- **External CLI strengths** — deep IDE integration, specialized coding workflows, CLI-native tool access -- **Docker Agent strengths** — multi-agent coordination, hook-based auditing and policy enforcement, permission controls, OCI distribution, and the full agent config schema - -> [!NOTE] -> **When to use harnesses** -> -> Use a harness when you want a Claude Code / Codex / opencode session to act as a sub-agent inside a larger Docker Agent workflow — for example, an orchestrator that plans work and delegates coding tasks to specialized harness agents. - ## Prerequisites The external CLI must be installed and available on `PATH` before starting Docker Agent: @@ -78,7 +66,12 @@ agents: **not** a Docker Agent `provider/model` reference — the harness model never goes through Docker Agent's model providers or routing. - `effort` is forwarded as `--effort` and must be one of `low`, `medium`, - `high`, `xhigh`, or `max`. Omit it to use Claude Code's own default. + `high`, `xhigh`, or `max`. Omit it to use Claude Code's own default. In the + TUI, `/effort` and Shift+Tab change it for the + following turns of the session (`command-code` harnesses too). +- Session titles come from the CLI as well, since a harness agent has no + model: Docker Agent runs `claude --print` once on the `haiku` model, with + no tools, MCP servers or saved session, to title a new session. #### Authentication (Claude subscription, no API key) @@ -129,6 +122,29 @@ ready-to-run `claude-code-agent.yaml`. > harness unless the sandbox image is separately provisioned and > authenticated. +#### Questions and plan approval + +When you can answer, Claude Code's own questions reach you as an elicitation +form, like an MCP server's: in the TUI, through the API server's +`elicitation_request` events, or in any client that answers elicitations. + +- **`AskUserQuestion`**: one form per call, with each option's description + under it. You pick one option of a single-choice question and check any of + a multiple-choice one (Space toggles). A free answer replaces + the choices, like Claude Code's "Other". If you decline or dismiss the + form, Claude Code learns that you did not answer. +- **Plan approval** (`ExitPlanMode`): you see the plan and choose to proceed + or keep planning. Optional feedback goes back to Claude Code when you keep + planning. + +Docker Agent serves these prompts to the CLI through +`--permission-prompt-tool`, from an MCP server on loopback that lives for one +turn and requires a per-turn token. Other tools still run without asking. +Non-interactive sessions (`serve mcp`, A2A, background agents) keep the +previous behavior: Claude Code asks in plain text and ends its turn. +`docker agent run --exec` answers no forms, so it declines them and Claude +Code carries on without an answer. + ### Codex ```yaml 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 3e8c5925b29e..e07f11cd17bb 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 @@ -6,8 +6,6 @@ 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**, **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. @@ -42,7 +40,7 @@ The path after `unix://` is the absolute path to the socket file. Configured `he > [!TIP] > **Cancelling the authorization dialog** > -> If you dismiss the OAuth authorization dialog, the request is cancelled cleanly — no repeated prompts appear. The agent will report that authorization was declined. To try again, simply re-enable the server or repeat the request that triggered the flow. +> Dismissing the OAuth authorization dialog cancels the request. To try again, re-enable the server or repeat the request that triggered the flow. ## Configuration @@ -62,6 +60,8 @@ For full configuration details, see the [Tool Config](../../configuration/tools/ Set `allow_private_ips: true` on a remote MCP toolset only when the MCP server or its OAuth registration/token endpoints intentionally resolve to private, loopback, or link-local addresses. The default blocks those OAuth helper requests to reduce SSRF risk. +Set `standalone_sse: true` on a `streamable` remote toolset to open the optional standalone SSE `GET` stream on the MCP endpoint. Some gateways (for example the sbx MCP gateway) send keepalive pings and `notifications/tools/list_changed` over that stream and drop sessions they cannot reach, so without it the session expires silently and the tool list goes stale. It defaults to `false` because a few servers hang when the stream is opened. It has no effect with `transport_type: "sse"`. + When Docker Desktop is running, eligible OAuth discovery, registration, token exchange, refresh, and helper requests use its PAC adapter before environment proxy settings. It does not apply to remote MCP Streamable HTTP/SSE transport. Set `DOCKER_AGENT_DISABLE_DESKTOP_PROXY=1` (or `true`, `yes`, or `on`) to restore standard `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and `NO_PROXY` routing; `NO_PROXY` does not bypass Desktop PAC selection. Docker Agent does not evaluate PAC files or URLs directly—see [Docker Desktop proxy](../../tools/fetch/index.md#docker-desktop-proxy). > [!NOTE] @@ -90,7 +90,7 @@ When Docker Desktop is running, eligible OAuth discovery, registration, token ex > - **Silent refresh:** when a refresh token is available, Docker Agent silently exchanges it for a new access token and replays the request — no user interaction required. > - **Re-authentication prompt:** when the refresh token is absent or has also expired, the toolset transitions to a "needs re-auth" state and surfaces an OAuth prompt on your next message (exactly like the first-time flow). > -> Either way, the agent never burns 5 reconnect attempts on an auth failure — it fails fast and either refreshes silently or defers to interactive re-auth. If you want to trigger re-auth immediately without waiting for the next message, run `/toolset-restart ` from the TUI. +> To trigger re-auth immediately without waiting for the next message, run `/toolset-restart ` from the TUI. ### OAuth for servers without Dynamic Client Registration @@ -307,4 +307,4 @@ agents: > [!NOTE] > **Growing list** > -> This list is updated as more services add MCP support. If a service you use isn't listed, check their documentation — many providers are adding MCP endpoints regularly. +> For services not listed here, check their documentation for an MCP endpoint. diff --git a/_vendor/github.com/docker/docker-agent/docs/features/sessions/index.md b/_vendor/github.com/docker/docker-agent/docs/features/sessions/index.md index b89b69a2bab1..c6c11db6d8e5 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/sessions/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/sessions/index.md @@ -160,11 +160,6 @@ models: An all-zero `cost:` table means "priced, free" — distinct from a model with no `cost:` at all, which falls back to the catalogue (and bills $0 for models the catalogue doesn't know). -> [!NOTE] -> **Cost never decreases** -> -> A session's cumulative cost is a running total updated after every *tracked* model call — the same main conversation turns and compaction calls described above. Compacting the conversation (manually with `/compact`, or automatically — see the agent's `session_compaction`/`compaction_threshold` fields in the [Agent Config reference](../../configuration/agents/index.md)) reshapes the message history sent back to the model, but never touches this running total. Auxiliary one-shot calls such as automatic session-title generation are not tracked and are not reflected in this total: `/cost` covers everything the session's tracked calls have spent, not literally every model call the runtime makes on your behalf. - ## Resuming Into a Worktree A session created during a `--worktree` run remembers which worktree it used. Resuming it with `--session` reattaches to the same worktree directory and branch automatically — you don't need to pass `--worktree` again. See [`--worktree`](../cli/index.md#docker-agent-run) in the CLI reference for the full worktree lifecycle. 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 530fcbfad81b..620a5e937667 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 @@ -25,9 +25,6 @@ agents: skills: true ``` -> [!TIP] -> Skills are perfect for encoding team-specific workflows (PR review, deployment, coding standards) that apply across projects. - ## Filtering Skills The `skills` field also accepts a list, letting you restrict the agent to a specific subset of skills instead of exposing every discovered one. List items are classified automatically: diff --git a/_vendor/github.com/docker/docker-agent/docs/features/snapshots/index.md b/_vendor/github.com/docker/docker-agent/docs/features/snapshots/index.md index bc624bf89123..a5075fbfb591 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/snapshots/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/snapshots/index.md @@ -6,8 +6,6 @@ weight: 20 canonical: https://docs.docker.com/ai/docker-agent/features/snapshots/ --- -_Shadow-git snapshots capture your workspace at turn boundaries so you can review what an agent changed and undo it without touching your real git history._ - ## Overview When snapshots are enabled, Docker Agent records the state of your working 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 adb982769f95..7d3ea4ee4e88 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 @@ -13,7 +13,14 @@ _Docker Agent's default interface is a rich, interactive terminal UI with file a ## Launching the TUI -Both the full TUI and the lean TUI display a centered ASCII art Docker Agent banner on startup when the chat is empty. The banner is automatically hidden once the agent starts responding or when a custom welcome message is configured. You can disable the banner entirely from the **Appearance** tab of `/settings`, or by setting `show_banner: false` in your [user settings](../../configuration/user-settings/index.md). +Both the full TUI and the lean TUI display a braille “Docker Agent” title on startup. It uses a violet-to-pink-to-apricot gradient on dark backgrounds and dark grey on light backgrounds, adjusted for contrast against the selected theme’s background. On supported TrueColor terminals, the full TUI draws a twisting stream of dots from the left edge of the chat pane into a cloud that settles into the title from left to right once at launch. Set `DOCKER_AGENT_REDUCE_MOTION=1` to skip the animation; the banner remains static. Terminals without detected TrueColor support, redirected output, and the lean TUI also use the static banner. In lean mode, the terminal's actual background may differ from the selected theme. + +- **Full TUI:** the banner is centered in the empty chat pane. It is not drawn if the pane is narrower than 76 columns or shorter than 6 rows, and it disappears as soon as the conversation has content: when you send a message, when the agent starts responding, or when the agent's `welcome_message` is shown (which replaces the banner as soon as the agent info arrives). +- **Lean TUI:** the banner is printed left-aligned at the start of the transcript, above the resumed session if any, and stays in the scrollback as messages arrive. + +The lean TUI does not change the terminal's background. Choose a theme that matches it: for example, use `--theme default` on a dark terminal or `--theme default-light` on a light terminal. `--theme auto` detects the background at startup when the terminal supports it, falling back to dark when it cannot. A mismatched theme may make text hard to read. + +You can disable the banner entirely from the **Appearance** tab of `/settings`, or by setting `show_banner: false` in your [user settings](../../configuration/user-settings/index.md). ```bash # Launch with a config @@ -65,6 +72,14 @@ The lean TUI supports **steering** and **follow-ups** while the agent is running The lean TUI supports a focused set of slash commands: `/new`, `/sessions`, `/compact`, `/model`, `/effort`, `/copy`, `/clear`, `/settings`, `/help`, `/exit` (alias: `/quit`), plus any agent-defined commands. Type `/model` (or `/model `) to switch the active model inline — the command opens a fuzzy-searchable list of available models. If what you type after `/` doesn't match any command, the autocomplete menu automatically falls back to fuzzy-matching it against available models (by name, provider, or ID) instead of dismissing — selecting a match switches the model just like `/model` would, without needing to type `/model` first; this fallback is unavailable when `/model` itself is disabled via `--disable-commands`. Type `/sessions` (or `/sessions `) to browse and resume past sessions from the current working directory. Type `/copy` to copy the last assistant response to the clipboard. Type `/settings` to open the lean TUI's inline settings panel — see [User Settings](../../configuration/user-settings/index.md) for the fields it exposes. +MCP elicitations and OAuth prompts appear inline in the lean TUI, in place of the editor, so a tool that asks for input no longer blocks the run with nothing on screen: + +- **Forms** (from MCP servers or the [`user_prompt`](../../tools/user-prompt/index.md) tool) support text, number/integer, boolean, single- and multi-select fields, and masked password fields, plus free-form answers. Single-select fields start on the schema `default` when one is set, instead of always the first option. The full TUI dialog behaves the same way and shares the same validation. +- **URL prompts:** press y when done, n to decline, o to open the browser, or Esc to cancel. +- **OAuth consent:** press y to authorize, or n/Esc to decline. A notice is shown when authorization completes. + +Concurrent requests are queued and shown oldest first. Ctrl+C cancels the prompt and interrupts the run. Starting a new conversation (`/new`), switching sessions, or reloading a tab cancels any elicitation still waiting from the previous conversation, in both the lean and full TUI, so the tool that raised it is not left waiting. + Prefix a message with `!` to run it as a shell command directly, without going through the agent — for example `!git status`. The command runs in your default shell and its output is shown inline in the transcript. Bang commands are disabled in read-only sessions. Type `@` to open a fuzzy-searchable file completion menu (respects `.gitignore`); press Tab or Enter to insert the selected file's path into the message text. @@ -93,7 +108,7 @@ Type `/` during a session to see available commands, or press Ctrl+`, or `/effort` alone to pick from the supported levels; reasoning models only). Press Tab after `/effort` and a space to complete a level the current model supports | +| `/effort` | Set the current model's reasoning-effort level (`/effort `, or `/effort` alone to pick from the supported levels; reasoning models and `claude-code` / `command-code` harnesses only). Press Tab after `/effort` and a space to complete a level the current model supports | | `/settings` | Manage appearance, behavior, and notification preferences | | `/yolo` | Toggle automatic tool call approval | | `/title` | Set or regenerate session title | @@ -177,7 +192,7 @@ The title is rendered in the agent's accent color. Sections appear in this order - **Execution capabilities** — native versus harness execution, tool execution/approval ownership, and support for budgets, native compaction, mid-turn steering and prompt-hook context. Support is not an enabled setting; budget support requires runtime configuration. Harness actions are reported, not approved by Docker Agent. Omitted when the server has not supplied a profile. - **Model / Fallback / Thinking** — the `provider/model`, any fallback models, and the gauge + value thinking line (omitted for models with no selectable thinking, e.g. harness-backed agents). - **Context** — the agent's latest known context usage, e.g. `Context: 12.8K of 128.0K tokens (10%)` (a bare token count when the context limit is unknown; omitted until the agent has run). Sub-agent and background-agent runs are accounted for. When a dedicated `compaction_model` caps the effective limit below the primary model's own window, the token-usage line also shows a short "⚠ capped" marker (see `/context` for the model and figure). -- **Cost** — the agent's cumulative cost across all runs in the session tree. Repeated session snapshots are not double-counted. Omitted until the agent has run. +- **Cost** — the agent's cumulative cost across all runs in the session tree. Omitted until the agent has run. - **Sub-agents (N) / Handoffs (N) / Skills (N)** — compact, inline, comma-separated lists wrapped to the dialog width. - **Limits** — the configured per-agent limits that are set, e.g. `Limits: max-iter 50 · history 40 · max-tool-calls 5`. - **Options** — the enabled option flags, e.g. `Options: add-date · add-environment-info · redact-secrets`. @@ -200,9 +215,9 @@ The thinking state of each model is shown with a gauge + value on the card and a | Disabled (capable) | `thinking ▱▱▱▱▱▱ off` (dimmed) | `▱▱▱▱▱▱` (empty gauge) | | Not reasoning-capable | _(omitted)_ | _(omitted)_ | -The **effort gauge** is a fixed-width six-cell indicator (`▰` filled, `▱` empty) so the badge column stays aligned. It maps the six selectable levels one-to-one onto filled-cell counts — `minimal` → `▰▱▱▱▱▱`, `low` → `▰▰▱▱▱▱`, `medium` → `▰▰▰▱▱▱`, `high` → `▰▰▰▰▱▱`, `xhigh` → `▰▰▰▰▰▱`, `max` → `▰▰▰▰▰▰` — so the cell count alone is lossless, with a low→high color ramp as a secondary cue. A capable-but-disabled model shows a dim empty gauge (`▱▱▱▱▱▱` `off`), adaptive budgets show `auto`, and token budgets keep `◉ `. The same gauge + value renders on the focus card, the Agent Inspector, and the row. +The **effort gauge** is a fixed-width six-cell indicator (`▰` filled, `▱` empty) so the badge column stays aligned. It maps the six selectable levels one-to-one onto filled-cell counts — `minimal` → `▰▱▱▱▱▱`, `low` → `▰▰▱▱▱▱`, `medium` → `▰▰▰▱▱▱`, `high` → `▰▰▰▰▱▱`, `xhigh` → `▰▰▰▰▰▱`, `max` → `▰▰▰▰▰▰` — with a low→high color ramp as a secondary cue. A capable-but-disabled model shows a dim empty gauge (`▱▱▱▱▱▱` `off`), adaptive budgets show `auto`, and token budgets keep `◉ `. The same gauge + value renders on the focus card, the Agent Inspector, and the row. -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). +Harness-backed agents (e.g. `claude-code`) show the harness type as their model. `claude-code` and `command-code` harnesses show their `effort` on the gauge, or `auto` while the CLI picks it; other harnesses show 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 @@ -299,7 +314,7 @@ Unsupported or syntactically invalid LaTeX expressions fall back to displaying t The TUI fetches and renders images referenced in agent responses using the Kitty graphics protocol. When an assistant message contains a standard Markdown image reference, the TUI downloads the image in the background and displays it inline at the point of the reference. While the image is loading a placeholder is shown; once loaded, the message re-renders with the image in place. -Only `http://`, `https://`, and `data:image/…;base64,…` URIs are resolved. `file://`, `sandbox://`, and any other URI scheme are rejected as a security measure against prompt-injection attacks that could otherwise read local files. Bare relative paths (e.g. `./output.png`, used for agent-generated images) are read via the local filesystem. Images that fail to load are silently dropped — the surrounding message text is unaffected. Image rendering requires a terminal that supports the Kitty graphics protocol; it is automatically disabled when the terminal does not support it. Support is checked before the TUI starts; an unanswered probe waits up to 300 ms. You can disable rendering and skip this check via `render_images: false` in `~/.config/cagent/config.yaml` or the **Render images** toggle in `/settings`. Disabling and re-enabling images applies immediately when startup confirmed support. If the startup check was skipped, enabling images takes effect on the next launch. +Only `http://`, `https://`, and `data:image/…;base64,…` URIs are resolved. `file://`, `sandbox://`, and any other URI scheme are rejected as a security measure against prompt-injection attacks that could otherwise read local files. Bare relative paths (e.g. `./output.png`, used for agent-generated images) are read via the local filesystem. Images that fail to load are silently dropped — the surrounding message text is unaffected. Image rendering requires a terminal that supports the Kitty graphics protocol; it is automatically disabled when the terminal does not support it. Support is checked before the TUI starts. Terminals without Kitty graphics answer right away; only a terminal that answers nothing at all waits out the 300 ms timeout. You can disable rendering and skip this check via `render_images: false` in `~/.config/cagent/config.yaml` or the **Render images** toggle in `/settings`. Disabling and re-enabling images applies immediately when startup confirmed support. If the startup check was skipped, enabling images takes effect on the next launch. ### Snapshots, `/undo`, and `/snapshots` @@ -454,7 +469,7 @@ The picker's catalog entries come from [models.dev](https://models.dev) and are ## Editable Messages -Edit any previous user message to branch the conversation. Hover a past user message and click **✎ edit** (or select it with the keyboard and press e) to modify it — the agent will re-process from that point, while the original session history is preserved. This is great for exploring alternative approaches without losing your work. +Edit any previous user message to branch the conversation. Hover a past user message and click **✎ edit** (or select it with the keyboard and press e) to modify it — the agent will re-process from that point, while the original session history is preserved. Hovering a user or assistant message also reveals a **⎘ copy** button that copies the message text to the clipboard (c when a message is selected). @@ -462,7 +477,7 @@ Hovering a user or assistant message also reveals a **⎘ copy** button that cop When an agent turn fails (fatal model error, hook block, loop detection, tool-setup failure), the TUI displays the error in the message stream and persists it to the session store. Errors survive a reload and are shown exactly where they occurred, making them visible in shared or remote sessions. -Each error message includes a clickable **↻ retry** button. Clicking it resumes the conversation from the point of failure — without retyping your last message. This lets you recover from transient failures (rate limits, network blips, model API errors) in one click. +Each error message includes a clickable **↻ retry** button. Clicking it resumes the conversation from the point of failure — without retyping your last message. ## Session Management @@ -581,19 +596,6 @@ Run `/settings` to open the settings dialog. Click a category tab, or use T > > This section covers the `/settings` dialog. For the complete list of `settings:` fields (including ones with no dialog UI, like `permissions`, `hooks`, and `keybindings`) and how they interact with CLI flags and aliases, see [User Settings](../../configuration/user-settings/index.md). -The **Appearance** tab selects the theme and customizes the layout. Layout changes apply immediately to the UI behind the dialog. On wide terminals, a schematic preview appears beside the controls without reducing the space available to the settings list: - -- **Sidebar position**: `Right` (default), `Left`, `Top`, or `Bottom`. Left/right keep the full vertical sidebar next to the chat; top/bottom render it as a compact horizontal band above or below the chat (session title, working directory, token usage, plus a one-line summary of the current agent and its model; in multi-agent configurations all team agents are listed by name after the current agent). -- **Sidebar info mode**: `Compact` (default) or `Detailed`. Controls how the Agents panel renders agent rows — see [Agents Panel](#agents-panel) for details. Persisted as `settings.layout.sidebar_info_mode: detailed`; compact is the default and omitted from the config. -- **Section spacing**: `Compact`, `Normal` (default), or `Relaxed`, the number of blank lines between the sidebar sections (1, 2, or 3). -- **Sidebar sections**: toggle the visibility of the **Session path** (the working directory line, including its git branch) and the **Token usage**, **Agents**, **Tools**, **Plans**, and **Todos** sections. All are visible by default except [Plans](#plans-sidebar), which is opt-in. The session title is always shown. - -Appearance also controls split-diff rendering, expanded thinking, whether tool results are hidden by default, and **Show startup banner** — the ASCII-art banner drawn on an empty conversation (persisted as `settings.show_banner: false` when turned off, and honored by the lean TUI too). Select **Theme** to open the theme picker. - -The **Behavior** tab controls busy-message handling, the auto-approve default, tab restoration, automatic snapshots, lean UI, and the maximum tab-title length. Restore-tabs and lean-UI changes take effect on the next launch. Enabling auto-approve requires confirmation. - -The **Notifications** tab enables completion sounds and sets the minimum task duration before a sound plays. - Press Enter to apply and persist, or Escape to cancel and restore the previous layout. The settings are saved globally in `~/.config/cagent/config.yaml`: ```yaml @@ -636,7 +638,7 @@ settings: theme_light: default-light # optional, theme used on light backgrounds (default: default-light) ``` -At startup the terminal background is queried (OSC 11) to pick the dark or light theme of the pair; non-interactive runs (pipes, CI) fall back to the dark theme. In terminals that report appearance changes (DEC mode 2031 — Ghostty, kitty, contour, …), flipping the OS or terminal appearance while Docker Agent is running switches the theme live. Terminals without that mode re-sync when the window regains focus. +At startup the terminal background is queried (OSC 11) to pick the dark or light theme of the pair; when detection is unavailable, the dark theme is used. In the full TUI, terminals that report appearance changes (DEC mode 2031 — Ghostty, kitty, contour, …) switch the theme live when the OS or terminal appearance changes. Terminals without that mode re-sync when the window regains focus. The lean TUI selects its auto theme at startup and does not update it live. ### Custom Themes @@ -696,7 +698,7 @@ settings: > [!TIP] > **Hot Reload** > -> Custom themes auto-reload when you save changes to the file — no restart needed. This makes it easy to tweak colors in real-time. +> Custom themes reload when you save changes to the file. > [!WARNING] > **Partial overrides** @@ -711,7 +713,7 @@ When an agent calls a tool, Docker Agent shows a confirmation dialog by default. - **Always allow** — Permanently approve this tool/command for the session - **Deny** — Reject the tool call -**Granular permissions:** The permission system supports pattern-based matching. When you “Always allow” a specific tool command, only that exact pattern is auto-approved — other commands from the same tool still require confirmation. This lets you auto-approve safe, read-only operations while maintaining control over destructive ones. +**Granular permissions:** The permission system supports pattern-based matching. When you “Always allow” a specific tool command, only that exact pattern is auto-approved — other commands from the same tool still require confirmation. > [!TIP] > **YOLO mode** @@ -727,5 +729,3 @@ The TUI displays transient notification banners for agent warnings, errors, and | Hover | Pauses auto-dismiss; the notification stays visible until the mouse moves away | | Click | Copies the notification text to the clipboard | | × (close) | Dismisses immediately; the glyph turns red when hovered | - -Hint text in the top-left corner of the notification border shows the available actions at a glance. diff --git a/_vendor/github.com/docker/docker-agent/docs/getting-started/installation/index.md b/_vendor/github.com/docker/docker-agent/docs/getting-started/installation/index.md index 0915b20ea64d..878719e468e1 100644 --- a/_vendor/github.com/docker/docker-agent/docs/getting-started/installation/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/getting-started/installation/index.md @@ -6,8 +6,6 @@ weight: 20 canonical: https://docs.docker.com/ai/docker-agent/getting-started/installation/ --- -_Get Docker Agent running on your system in minutes._ - ## Prerequisites - Access to a model through a provider API key, an account login, [Docker Model Runner](../../providers/dmr/index.md), or a [coding harness](../../features/harnesses/index.md) @@ -91,7 +89,7 @@ For the latest features, or to contribute, build from source: ### Prerequisites -- [Go 1.27](https://go.dev/dl/) or higher +- [Go 1.27.4](https://go.dev/dl/) or higher - [Task](https://taskfile.dev/installation/) (build tool) - [golangci-lint](https://golangci-lint.run/docs/welcome/install/local/) (for linting) diff --git a/_vendor/github.com/docker/docker-agent/docs/getting-started/introduction/index.md b/_vendor/github.com/docker/docker-agent/docs/getting-started/introduction/index.md index 0ade379b873c..aa79184d6f9b 100644 --- a/_vendor/github.com/docker/docker-agent/docs/getting-started/introduction/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/getting-started/introduction/index.md @@ -6,8 +6,6 @@ weight: 10 canonical: https://docs.docker.com/ai/docker-agent/getting-started/introduction/ --- -_Docker Agent is a multi-agent runtime that lets you build, run, and share AI agents with a YAML or HCL config — no glue code required._ - ## What is Docker Agent? Docker Agent is an open-source tool from Docker that orchestrates AI @@ -65,9 +63,6 @@ agents: $ docker agent run agent.yaml ``` -> [!TIP] -> Jump straight to the [Quick Start](../quickstart/index.md) if you want to build your first agent right away. - ## What's next? - [**Installation**](../installation/index.md) — install Docker Agent on macOS, Linux, or Windows. diff --git a/_vendor/github.com/docker/docker-agent/docs/getting-started/quickstart/index.md b/_vendor/github.com/docker/docker-agent/docs/getting-started/quickstart/index.md index ba2e9cc90338..1ab171711e89 100644 --- a/_vendor/github.com/docker/docker-agent/docs/getting-started/quickstart/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/getting-started/quickstart/index.md @@ -8,8 +8,6 @@ aliases: - /ai/docker-agent/tutorial/ --- -_Get up and running with Docker Agent in under 5 minutes. Pick whichever path suits you best._ - ## Option A: Run the Default Agent The fastest way to try Docker Agent — no config file needed: @@ -19,8 +17,6 @@ The fastest way to try Docker Agent — no config file needed: $ docker agent run ``` -This starts a general-purpose assistant with sensible defaults. Just start chatting. - > [!NOTE] > This needs a model: a cloud provider API key, or a local model pulled through Docker Model Runner. [Set Up a Model](../set-up-a-model/index.md) walks through both paths. @@ -71,13 +67,6 @@ agents: - type: think ``` -This gives your agent: - -- **Claude Sonnet 4.5** as the underlying model -- **Filesystem access** to read and write files -- **Shell access** to run commands -- **Think tool** for step-by-step reasoning - This config needs `ANTHROPIC_API_KEY` set. See [Set Up a Model](../set-up-a-model/index.md) for where to put it, or use a local `dmr/...` model that needs no key. ```bash @@ -120,7 +109,7 @@ Use `docker agent run --exec` for one-shot tasks: $ docker agent run --exec agent.yaml "Create a Dockerfile for a Node.js app" # Pipe input -$ cat error.log | docker agent run --exec agent.yaml "What's wrong in this log?" +$ { printf "What's wrong in this log?\n\n"; cat error.log; } | docker agent run --exec agent.yaml - ``` ## Add More Power @@ -146,7 +135,7 @@ agents: > [!NOTE] > **Docker MCP Tools** > -> The `ref: docker:duckduckgo` syntax runs the DuckDuckGo MCP server in a Docker container. This is the recommended way to use MCP tools — secure, isolated, and easy to configure. Requires Docker Desktop. +> The `ref: docker:duckduckgo` syntax runs the DuckDuckGo MCP server in a Docker container. Requires Docker Desktop. ## What's Next? diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/compaction/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/compaction/index.md index 67027ff65c03..7cdfd705f30c 100644 --- a/_vendor/github.com/docker/docker-agent/docs/guides/compaction/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/guides/compaction/index.md @@ -58,12 +58,22 @@ models: model: claude-haiku-4-5 ``` +> [!NOTE] +> **Unknown context window** +> +> Compaction needs the summary model's context window. Models outside the models.dev catalogue (custom endpoints, local models) have none unless you declare one. If compaction reports that a model "has no known context window", add `context_window` to that model's entry in the `models` section (for example `context_window: 200000`). See [Context Window](../../configuration/models/index.md#context-window). + +> [!NOTE] +> **Declared windows and thresholds** +> +> A model's `context_window` (see [Context Window](../../configuration/models/index.md#context-window)) is the capacity the threshold is a fraction of. Setting it does not add a fixed-token trigger: with `context_window: 128000` and the default `0.9`, compaction fires above 115,200 tokens, and the `compaction_threshold` on the model or agent scales that fraction. + > [!IMPORTANT] > **Context window mismatch** > > If `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 model with a compaction model whose window is at least as large to keep the proactive trigger aligned with the primary model's window. > -> The `/context` header and the sidebar's context gauge surface this cap when it applies: the `/context` header shows a second line reading "compaction cap: `` • `` tokens", and the sidebar shows a short "⚠ capped" marker. Live-sessions rows do not carry cap wording; the sidebar marker deliberately doesn't repeat the model name or figure — the `/context` header is the sole authority on why the reported limit is smaller than the primary model's own window. +> The `/context` header and the sidebar's context gauge surface this cap when it applies: the `/context` header shows a second line reading "compaction cap: `` • `` tokens", and the sidebar shows a short "⚠ capped" marker. Disable compaction only when you specifically want a session to keep full, unabridged history and are willing to risk hitting the context limit: @@ -85,7 +95,7 @@ You don't have to wait for the automatic threshold. Two TUI commands give you di - **`/compact`** — summarize and compact the current session's history right now, regardless of how full the context window is. Useful before starting a new phase of work that doesn't need the earlier detail. - **`/context`** — open a context-window breakdown: estimated tokens per category (system prompt, tool definitions, prompt files, messages, tool results, compaction summary), a **Live sessions** view listing the current session plus every running sub-agent session with its own context budget, and a per-file inventory of attachments and prompt files. When a compaction has occurred, the dialog also displays the verbatim text of the most recent compaction summary, preserving hard newlines and soft-wrapping long lines to the dialog width. -From `/context`, select any live session with the arrow keys and press Enter to explicitly compact it — including a sub-agent's session, not just the main one. This is the only way cross-agent compaction happens: there's no idle-triggered automatic compaction of sub-agent sessions, so a long-running background agent stays under your control. The request is queued onto the target session's own run loop and applied at the next safe point between model turns, so it never corrupts an in-flight turn. +From `/context`, select any live session with the arrow keys and press Enter to explicitly compact it — including a sub-agent's session, not just the main one. The request runs at the next safe point between model turns. ```bash $ docker agent run agent.yaml @@ -146,4 +156,4 @@ Compaction summarizes history, but it never resets what a session has actually c ## Related: deferred tool loading -Compaction and result trimming manage context that's already in the session. If large toolsets are inflating your **starting** context instead — many MCP servers, hundreds of tools — look at [deferred tool loading](../../configuration/tools/index.md#deferred-tool-loading), which registers a toolset's tools lazily instead of eagerly at startup. +Compaction and result trimming manage context that's already in the session. If large toolsets are inflating your **starting** context instead — many MCP servers, hundreds of tools — look at [deferred tool loading](../../configuration/tools/index.md#deferred-tool-loading), which exposes tool definitions to the model only when needed. The underlying toolsets still start normally. 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 2c6a68719976..dfe089537fdf 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 @@ -6,8 +6,6 @@ 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._ - ## Overview Docker Agent can be used as a Go library, allowing you to build AI agents directly into your Go applications. This gives you full programmatic control over agent creation, tool integration, and execution. @@ -135,12 +133,30 @@ The CLI uses this helper for both its initial runtime and TUI-spawned runtimes. The HTTP API wires the same manifest budgets into its native runtimes; other serving adapters retain their existing wiring and budget behavior. +## Remote execution + +Remote HTTP/SSE execution lives in `pkg/runtime/remote`: + +```go +client, err := remote.NewClient(serverURL) +if err != nil { + return err +} +rt, err := remote.NewRuntime(client) +``` + +Import `github.com/docker/docker-agent/pkg/runtime/remote` for these constructors. +Shared interfaces and events remain in `pkg/runtime` (`runtime.Runtime`, +`runtime.Event`, and the concrete event types). The remote implementation imports +those types; local execution does not import remote transport. There are no +compatibility re-exports of remote clients or constructors in `pkg/runtime`. + ## Execution Capability Inspection `(*runtime.LocalRuntime).AgentExecutionCapabilities(name)` returns a static native/harness profile without starting tools, constructing drivers or initializing budget counters. Unknown agents return nil. The same optional -profile is available on `runtime.AgentConfigInfo`, `runtime.AgentDetails` in +profile is available on `inspection.AgentConfigInfo`, `runtime.AgentDetails` in `team_info`, and local startup/refresh `runtime.AgentInfoEvent` values. See [Execution capabilities](../../features/api-server/index.md#execution-capabilities) for field meanings and unknown/remote behavior. @@ -275,7 +291,7 @@ For anything beyond that, call `chat.Runtime()` to access the underlying `runtim > 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 +> `runtime.LocalRuntime`/`remote.Runtime`), 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 @@ -325,7 +341,7 @@ if err != nil { ts := ragtool.New(mgr, mgr.ToolName(), ragtool.WithIndexingTimeout(ragCfg.GetIndexingTimeout())) ``` -`cmd/wasm/toolsets.go` registers exactly this as the browser's `type: rag` creator, fed by `createSession`'s `documents` option. +With `-tags docker_agent_wasm_rag`, `cmd/wasm/rag.go` registers this as the browser's `type: rag` creator, fed by `createSession`'s `documents` option. RAG is excluded from the default WASM build. ## Loading YAML with Hand-Picked Registries (lean embedding) @@ -360,6 +376,8 @@ team, err := teamloader.Load(ctx, ocisource.New("myorg/agent:v1"), runConfig, - **Agent sources**: `config.NewFileSource` / `config.NewBytesSource` / `config.NewURLSource` live in `pkg/config`; the OCI source lives in `pkg/config/ocisource`; HCL support is a source decorator, `hcl.NewSource(inner)`, in `pkg/config/hcl`. `pkg/config/sources` resolves any reference (files, directories, URLs, OCI, user aliases, built-in agents) at the cost of linking all of them. Sub-agents referencing external agents (`sub_agents: [myorg/reviewer]`) need a `teamloader.WithSourceResolver` that wraps `sources.Resolve` (as `loaderdefaults.Opts()` does) — or your own resolver. - **Optional loader features**: everything the loader used to link unconditionally is now an option, so `pkg/teamloader` adds no module over `pkg/runtime`. Enable what your configs use: `teamloader.WithExpander(js.NewJsExpander)` for `${...}` JavaScript in instructions/commands (the default only resolves `${env.NAME}`; also call `jscommands.Register()` for slash commands), `teamloader.WithCodeMode(codemode.Wrap)` for `code_mode_tools`, `teamloader.WithToon(toon.Wrap)` for the `toon` field, `teamloader.WithDeferredTools(deferred.New)` for `defer`, and `runtime.RegisterHarness(codingharness.Factory)` for `harness:` agents. A config that uses a feature you did not enable fails to load with an error naming the option. - **Strict mode**: `teamloader.WithStrict(features...)` fails the load with a `*config.UnsupportedError` listing **every** provider type, toolset type and optional feature the config relies on that you did not enable, with the config locations that need them. Optional features are `config.FeatureHooks`, `config.FeatureHarness`, `config.FeatureAgentRouting`, `config.FeatureSkills`, `config.FeatureExternalAgents`, `config.FeatureCodeMode`, `config.FeatureToon` and `config.FeatureDeferredTools`; none is enabled unless listed. Agents on the `auto` model are resolved eagerly so the provider they land on is checked too. Without `WithStrict`, unknown toolset types stay load-time warnings and unknown providers fail when their model is built. +- **Template-based hooks**: the `add_context` builtin and `type: model` hooks render Go templates. `text/template` looks methods up by name at run time, so linking it makes the Go linker keep every exported method of every reachable type, which roughly doubles a WASM binary. Build with `-tags docker_agent_no_hook_templates` to drop it; those two hooks then fail with `hooks.ErrHookTemplatesDisabled`. Hosts that load with `WithStrict()` and don't enable `config.FeatureHooks` lose nothing. +- **JavaScript expansion**: `pkg/js` evaluates `${...}` with goja, which exposes Go methods to scripts by reflection and has the same effect on the linker as `text/template`. The toolsets that expand placeholders through it (`mcp`, `fetch`, `api`, `openapi`, `a2a`, `webhook`, `open_url`) link it even when the loader's expander is the default one. Build with `-tags docker_agent_no_js_expansion` to swap the engine out: `${env.NAME}` and bound `${name}` placeholders still resolve, and any other expression is left as text. `code_mode_tools` needs goja regardless, so leave `teamloader.WithCodeMode` out too. `cmd/wasm`'s small profile combines both tags. `config.Requires(cfg)` exposes the same audit for your own checks. `pkg/embeddedchat` accepts all of this through `Config.LoadOpts`. A complete example lives in [examples/golibrary/yamlstrict](https://github.com/docker/docker-agent/tree/main/examples/golibrary/yamlstrict). @@ -370,6 +388,63 @@ team, err := teamloader.Load(ctx, ocisource.New("myorg/agent:v1"), runConfig, > > If you call `teamloader.Load` without `loaderdefaults.Opts()`, JavaScript expansion, code mode, TOON, deferred tools and harness agents are now off until you enable them (see *Optional loader features* above). Code-built teams that use `harness:` agents must call `runtime.RegisterHarness(codingharness.Factory)`; `codingharness.Label` moved into the runtime. +### Optional YAML history and embedded model catalog + +The core packages do not link historical YAML schemas or a model catalog snapshot. +Both capabilities are independent opt-ins; the CLI and the shipped WASM demo enable +both to preserve their existing behavior. + +`config.Load` and `teamloader.Load` accept only the current schema by default +(version omitted or `latest.Version`). To accept historical YAML, import +`pkg/config/legacy` and pass its registrar: + +```go +cfg, err := config.Load(ctx, source, config.WithVersions(legacy.Register)) + +team, err := teamloader.Load(ctx, source, runConfig, + teamloader.WithConfigVersions(legacy.Register), + // ...provider and toolset registries... +) +``` + +This retains the usual strict parsing, validation, flavor patches and migrations. +The selection is per load and inherited by external sub-agents. `loaderdefaults` +already includes it. Without it, old versions fail with an unsupported-version +error; historical syntax hints are only available when history is selected. + +`modelsdev.NewStore` still uses its disk cache and the live models.dev API, but a +cache/network miss returns an empty catalog unless a fallback is supplied. To +include the optional embedded data, import `pkg/modelsdev/embedded`: + +```go +store, err := modelsdev.NewStore(modelsdev.WithFallback(embedded.Snapshot)) + +// Or configure the shared store used by a team and its runtime: +runConfig := &config.RuntimeConfig{ + ModelsDevFallback: embedded.Snapshot, +} + +// Entirely in-memory; no cache or network discovery: +store = modelsdev.NewDatabaseStore(embedded.Snapshot()) +``` + +`runtime.WithModelsDevFallback(embedded.Snapshot)` configures a standalone +runtime's lazy default store. An explicit `runtime.WithModelStore` or the store +carried by its model-switcher configuration takes precedence. A fallback callback +runs only when needed and is not cached as authoritative, so live discovery can +recover after a failed request. Callback results are shared; treat them as read-only +and make callbacks safe for concurrent use across stores. + +For a small offline host, use an empty in-memory store instead and omit the +`embedded` import. No metadata means no reliable catalog pricing or capability +inference; specify model limits and capabilities when required. Removing the +snapshot alone does not disable network discovery in a normal `NewStore`. + +**Go API migration:** `modelsdev.EmbeddedSnapshot()` is now `embedded.Snapshot()`; +`modelsdev.SnapshotDate()` is now `embedded.SnapshotDate()`. Existing applications +loading old YAML must opt in with `legacy.Register`. No build tags or process-wide +registration are needed for either capability. + ### Per-runtime feature configuration Prefer instance options over `runtime.RegisterHarness` and @@ -904,7 +979,6 @@ embedding, context-discovery or compaction capabilities. | Caller | Clone failure behavior | | --- | --- | | Session title | Tries the next configured candidate; exhaustion does not interrupt chat. | -| MCP sampling, with or without tools | Returns the actionable clone error before inference. | | LLM compaction | Reports failure and leaves the session history intact. | | Compaction window resolution | The checked resolver returns zero plus the error; the LLM compaction path reports it. UI gauges remain best-effort. | diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/headless/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/headless/index.md index 1a80c3100e47..be4334541a3c 100644 --- a/_vendor/github.com/docker/docker-agent/docs/guides/headless/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/guides/headless/index.md @@ -97,7 +97,7 @@ Hooks run asynchronously and are never waited on: each is spawned detached from ## Running Unattended in CI -Interactively, the TUI prompts for confirmation before a tool call runs unless it's covered by an `allow` permission pattern. There's no one to answer that prompt in CI, so an unattended `--exec` run needs an explicit policy for what may run without asking — otherwise every tool call the model attempts is rejected outright (there's no stdin to prompt, so `--exec` without one just answers "no" on your behalf; see [`--json`'s auto-reject behavior](#structured-output-for-machines) above). +Under the default policy, read-only tools run without confirmation and other calls prompt for approval unless a permission rule overrides that decision. An interactive `--exec` run can still prompt for tool approval; it does not inherently mean unattended execution. In CI, configure an explicit safety mode and permission rules for the calls that must run without asking. With `--json` or `--last`, pending confirmations are always declined; plain-text exec output redirected to a pipe or file also declines them. See [structured output behavior](#structured-output-for-machines) above. Two different questions come up here, and it's worth keeping them separate: @@ -106,7 +106,7 @@ Two different questions come up here, and it's worth keeping them separate: ### `--sandbox`: the isolation boundary -For an untrusted or autonomous agent — anything acting without a human watching approvals — **`--sandbox` is the isolation boundary to reach for**, not a cleverer allow-list. It runs the entire agent, shell calls included, inside a VM managed by [`sbx`](https://docs.docker.com/ai/sandboxes/): a misbehaving or successfully-prompt-injected agent can't touch anything outside the mounted working directory or reach other host/CI state, regardless of which command it runs. That VM isn't disposable or ephemeral — a sandbox matching the current workspace and mount set is retained and reused across subsequent runs rather than torn down when the session ends (see [How It Works](../../configuration/sandbox/index.md#how-it-works)). See [Sandbox Mode](../../configuration/sandbox/index.md) for the full flag reference, `sbx` requirement, network allowlist, and kit staging behavior. +For an untrusted or autonomous agent — anything acting without a human watching approvals — **`--sandbox` is the isolation boundary to reach for**, not a cleverer allow-list. It runs the entire agent, shell calls included, inside a VM managed by [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/), using standalone `sbx` or the `docker sandbox` plugin. The working directory is mounted read-write; configuration directories and staged kits may also be exposed read-only. Treat every mounted file and configured network destination as accessible to the agent, and mount only what the task needs. That VM isn't disposable or ephemeral — a sandbox matching the current workspace and mount set is retained and reused across subsequent runs rather than torn down when the session ends (see [How local sandbox mode works](../../configuration/sandbox/index.md#how-local-sandbox-mode-works)). See [Sandbox Mode](../../configuration/sandbox/index.md) for the full flag reference, `sbx` requirement, network allowlist, and kit staging behavior. ```bash $ docker agent run --sandbox --exec agent.yaml --json "Fix the failing test" diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/secrets/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/secrets/index.md index 7accef7fce3d..99470b8db523 100644 --- a/_vendor/github.com/docker/docker-agent/docs/guides/secrets/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/guides/secrets/index.md @@ -6,8 +6,6 @@ weight: 30 canonical: https://docs.docker.com/ai/docker-agent/guides/secrets/ --- -_How to securely provide API keys and credentials to Docker Agent._ - ## Overview Docker Agent needs API keys to talk to model providers (OpenAI, Anthropic, etc.) and MCP tool servers (GitHub, Slack, etc.). Avoid putting literal secrets in agent configuration fields such as `env`, headers, or URLs. Docker Agent can resolve them at runtime through a chain of secret providers, checked in order (see `pkg/environment/default.go`): @@ -18,7 +16,7 @@ Docker Agent needs API keys to talk to model providers (OpenAI, Anthropic, etc.) | 2 | [Docker Compose secrets](#docker-compose-secrets) | Files in `/run/secrets/` | | 3 | [Docker Agent env file](#docker-agent-env-file) | `~/.config/cagent/.env`, written by `docker agent setup` | | 4 | [ChatGPT login](../../providers/chatgpt/index.md) | `CHATGPT_OAUTH_TOKEN` from the account login created by `docker agent setup` | -| 5 | [Credential helper](#credential-helper) | Custom command declared in `~/.config/cagent/config.yaml` under `credential_helper:` | +| 5 | [Credential helper](#credential-helper) | Custom command declared in `~/.config/cagent/config.yaml` under `credential_helper:`; supplies `DOCKER_TOKEN` only | | 6 | [Docker Desktop](#docker-desktop) | Secrets stored by the Docker Desktop backend (no setup on a Desktop install) | The first provider that has a value wins. You can mix and match — for example, use environment variables for one key and the Docker Agent env file for another. @@ -26,7 +24,7 @@ The first provider that has a value wins. You can mix and match — for example, > [!NOTE] > Older Docker Agent versions could also read secrets from the macOS Keychain and the `pass` password manager. These sources are no longer consulted: migrate any keys stored there to one of the sources above, e.g. by re-running `docker agent setup`. -Whatever provider returns the value, if that value looks like a [1Password secret reference](#1password-references) (it starts with `op://`), Docker Agent resolves it through the `op` CLI before handing it to a model provider or tool. +Whatever provider returns the value, if that value looks like a [1Password secret reference](#1password-references) (it starts with `op://`), Docker Agent resolves it through the `op` CLI before handing it to a model provider or tool. This applies to every variable, API keys included, and needs no credential helper: `ANTHROPIC_API_KEY=op://Personal/Anthropic/api-key` in any source above is enough. When Docker Agent runs an agent with `--sandbox` and a Docker AI gateway is configured, the sandbox proxy authenticates gateway requests itself: it injects your Docker login token into HTTPS requests to the gateway host (docker.com domains only). The token never enters the sandbox — inside it, `DOCKER_TOKEN` is a proxy-managed placeholder. @@ -52,6 +50,26 @@ toolsets: GITHUB_PERSONAL_ACCESS_TOKEN: $GITHUB_PERSONAL_ACCESS_TOKEN ``` +### Docker Agent-only variables + +Other tools read the same variables: Claude Code reads `ANTHROPIC_API_KEY`, Codex reads `OPENAI_API_KEY`. To give Docker Agent its own value, prefix the name with `DOCKER_AGENT_ENV_`. Docker Agent looks up `DOCKER_AGENT_ENV_` before ``, and other tools ignore it: + +```bash +export ANTHROPIC_API_KEY=sk-ant-... # used by other tools +export DOCKER_AGENT_ENV_ANTHROPIC_API_KEY="op://Personal/Anthropic/api-key" # used by Docker Agent +docker agent run agent.yaml +``` + +- The prefix works for every variable Docker Agent resolves through its secret chain: provider API keys, `${VAR}` references in MCP `env`, `DOCKER_TOKEN`, and the OpenAI key used by `/speak`. +- `DOCKER_AGENT_ENV_` wins over `` across all [sources](#overview) and `--env-from-file`: an override in the Docker Agent env file beats a plain shell export. +- An empty override is ignored: `export DOCKER_AGENT_ENV_ANTHROPIC_API_KEY=` falls back to an override in a later source, then to `ANTHROPIC_API_KEY`. +- Docker Agent's own settings (`DOCKER_AGENT_*`) are never overridden this way. +- The value can be a [1Password reference](#1password-references). +- `docker agent doctor` shows which name supplied each credential. + +> [!NOTE] +> With `--sandbox`, the provider API keys that the sandbox proxy injects itself (such as `OPENAI_API_KEY` and `ANTHROPIC_API_KEY`) are not read through Docker Agent, so neither the prefix nor `op://` references apply to them. Other variables are resolved on the host, prefix included, and forwarded under their plain name. + ## Env Files For convenience, you can store secrets in a `.env` file and pass it to Docker Agent with `--env-from-file`: @@ -158,7 +176,17 @@ secrets: ## Credential Helper -Docker Agent can shell out to an external credential helper you define in your user config. This is useful when your organisation already has a secrets daemon you want to reuse (HashiCorp Vault, 1Password CLI, `bitwarden-cli`, etc.). +Docker Agent can shell out to an external credential helper you define in your user config to obtain the **Docker token** (`DOCKER_TOKEN`) used by the [Docker models gateway](../../configuration/models/index.md). This is useful when your organisation already keeps that token in a secrets daemon (HashiCorp Vault, 1Password CLI, `bitwarden-cli`, etc.). + +> [!IMPORTANT] +> **The credential helper does not serve API keys.** It is consulted for `DOCKER_TOKEN` only. To load provider API keys or MCP tokens from 1Password, store an `op://` reference in any other source instead, for example in the [Docker Agent env file](#docker-agent-env-file): +> +> ```bash +> # ~/.config/cagent/.env +> ANTHROPIC_API_KEY=op://Personal/Anthropic/api-key +> ``` +> +> See [1Password References](#1password-references). Declare the helper in `~/.config/cagent/config.yaml`: @@ -166,10 +194,10 @@ Declare the helper in `~/.config/cagent/config.yaml`: # ~/.config/cagent/config.yaml credential_helper: command: op - args: ["read", "op://Personal/docker-agent"] + args: ["read", "op://Personal/Docker/token"] ``` -The command is invoked with the variable name appended as the final argument, and must print the secret value to stdout. +The command is run exactly as configured, with no extra arguments, and must print the token to stdout. ## Docker Desktop @@ -177,7 +205,16 @@ On machines where Docker Desktop is installed, Docker Agent queries Docker Deskt ## Docker Authentication -Routing model traffic through the [Docker models gateway](../../configuration/models/index.md) needs a Docker token. Docker Desktop hands out one that is valid for 15 minutes and cannot be renewed by Docker Agent, so when Desktop has nothing usable to offer — it is signed out, not running, or its own refresh is stuck — Docker Agent exchanges the long-lived access token that `docker login` left in your credential store for a fresh Docker token, the same exchange `docker login` itself performs. Signing in with `docker login` is therefore enough; Docker Desktop is not required. +Routing model traffic through the [Docker models gateway](../../configuration/models/index.md) needs a Docker token. A `DOCKER_TOKEN` you provide yourself — an environment variable, a Compose secret, an env file or a credential helper, as is common in CI — always takes precedence, and none of the sources below are consulted. + +Otherwise, Docker Agent tries these sources in order and uses the first token that is not expired or about to expire: + +1. **The Docker secrets engine**, which Docker Desktop serves on a local socket and which holds the session of the account signed in to Desktop. It is skipped when it is unavailable (Docker Desktop is not installed or not running, or predates the engine), holds no session, or holds a session that is incomplete: an access token that is missing or not a JWT, or no account or expiry. A request waits for the engine for at most five seconds, and never more than half of its own time limit, so the other sources still get a turn. An engine that fails or does not answer is skipped for the next 30 seconds. Production sessions are read unless `DOCKER_AGENT_HUB_LOGIN_URL` points at a Docker Hub staging host, such as `hub-stage.docker.com`; staging sessions are read instead. Docker Agent cannot tell which environment Docker Desktop is signed in to, so set that variable when Desktop is signed in to staging. +2. **Docker Desktop's backend.** +3. **The access token `docker login` stored.** Docker Agent exchanges the long-lived access token in your credential store for a fresh Docker token, the same exchange `docker login` itself performs. Signing in with `docker login` is therefore enough; Docker Desktop is not required. +4. **A refresh of Docker Desktop's session**, as a last resort. + +The tokens Docker Desktop hands out are valid for 15 minutes, and only Desktop can renew them. That is why the exchange exists: it keeps Docker Agent working when Desktop has nothing usable to offer because it is signed out, not running, or its own refresh is stuck. Tokens are looked up again as they near expiry, so a long-running session keeps working. Only Docker access tokens are exchanged — the `dckr_…` secrets `docker login` stores — never an account password, and the exchange goes to Docker Hub over HTTPS. The resulting bearer token is cached in a private file under Docker Agent's cache directory so sibling processes reuse it instead of minting their own, and it stops being used within seconds of a `docker logout` or an account switch. Run `docker agent debug auth` to see which token is in use and where it came from. @@ -201,6 +238,9 @@ References follow the `op:////` format. Make sure the `op` C > > If the value starts with `op://` but the `op` CLI is not installed, or the reference cannot be read (not signed in, wrong path, locked vault), Docker Agent logs a warning and uses an **empty value** — it never forwards the raw `op://` reference to a model provider or tool. Resolved references (and deterministic failures) are cached for the lifetime of the run; transient failures such as a cancelled lookup are not cached, so a later attempt can retry. +> [!TIP] +> Other tools that read the same variables (Claude Code, Codex, provider SDKs) do not understand `op://` values. To keep references out of your shell, put them in the [Docker Agent env file](#docker-agent-env-file), which only Docker Agent reads, or point a model at a dedicated variable with [`token_key`](../../configuration/models/index.md). + ## Choosing a Method | Method | Best for | Setup effort | @@ -209,7 +249,7 @@ References follow the `op:////` format. Make sure the `op` C | Env files | Team projects, multiple keys | Low | | Docker Agent env file | Keys used across all projects, written by `docker agent setup` | Low | | Docker Compose secrets | Containerized deployments, CI/CD | Medium | -| Credential helper | Reusing an existing secrets daemon (Vault, 1Password CLI, ...) | Medium | +| Credential helper | Fetching `DOCKER_TOKEN` from an existing secrets daemon (Vault, 1Password CLI, ...) | Medium | | 1Password references (`op://`) | Teams already using 1Password | Low | You can combine methods. For example, store long-lived provider keys in the Docker Agent env file and pass project-specific MCP tokens via env files. 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 bfe2b34d43ed..1d1e378b2092 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 @@ -24,10 +24,10 @@ Docker Agent exposes this through a single `thinking_budget` field on any named | Provider | Format | Values | Default | | ------------------- | ---------- | --------------------------------------------------------------------------------------- | ------------------ | | OpenAI | string | `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`; `xhigh` on gpt-5.2+, `max` on gpt-5.6+; API-level `none` on GPT-5.x from 5.6 onward and GPT-6 Sol/Luna, `minimal` dropped on gpt-5.6+ | `medium` (API default) | -| Anthropic | int or str | 1024–32768 tokens, or `minimal`–`max`, `adaptive`, `adaptive/`, `none` | off | +| Anthropic | int or str | Fixed budgets: ≥1024 and less than `max_tokens`; or `minimal`–`max`, `adaptive`, `adaptive/`, `none` | Model-dependent; Claude 5.x defaults to adaptive | | 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) | -| AWS Bedrock | int or str | 1024–32768 tokens (`minimal`–`max` mapped to tokens); `adaptive`, `adaptive/` for Opus 4.6+ (rejected by older Claude models) | off | +| AWS Bedrock | int or str | Fixed budgets: ≥1024 and less than `max_tokens`; `minimal`–`max` mapped to tokens on older models; adaptive on supported newer Claude models | Model-dependent; Claude 5.x defaults to adaptive | | Docker Model Runner | int or str | token count, `minimal`–`max` (mapped to tokens), `adaptive` (unlimited), `none` | engine default | String values are case-insensitive. The full set of accepted strings is `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `adaptive`, and `adaptive/` — but each provider only honors the subset listed above. Unsupported values either fail at request time (OpenAI) or are mapped/ignored as described per provider below. @@ -71,7 +71,7 @@ Anthropic Claude supports two thinking modes: a **token budget** (older models) ### Token budget (Claude 4 and earlier) -Set an explicit number of thinking tokens (1024–32768). This must be less than `max_tokens`: +Set an explicit number of thinking tokens (at least 1024). This must be less than `max_tokens` and within the model's supported range: ```yaml models: @@ -85,7 +85,7 @@ Docker Agent auto-adjusts `max_tokens` when you set a thinking budget but leave ### Adaptive thinking (Opus 4.6+ and Sonnet 4.6) -Newer Claude models support adaptive thinking, where the model decides how much to think. **Claude Opus 4.6, 4.7, 4.8, and Sonnet 4.6 only support adaptive thinking** — they reject token-based budgets. Use `adaptive`, `adaptive/`, or a bare effort level — on Anthropic, a bare effort level like `high` is shorthand for adaptive thinking at that effort: +Newer Claude models support adaptive thinking, where the model decides how much to think. **Claude Opus 4.6, 4.7, and 4.8 only support adaptive thinking** — they reject token-based budgets. Sonnet 4.6 supports both token budgets and adaptive thinking. Use `adaptive`, `adaptive/`, or a bare effort level — on Anthropic, a bare effort level like `high` is shorthand for adaptive thinking at that effort: ```yaml models: @@ -118,9 +118,9 @@ models: `minimal` is treated as `low` (bare form only). `high` is the default when `adaptive` is used without an effort level. > [!WARNING] -> **Effort strings require adaptive-capable models** +> **Effort strings are adapted to the model** > -> Every string effort value on Anthropic is sent as adaptive thinking (`output_config.effort`), which only newer Claude models (Opus 4.6+, Sonnet 4.6) accept. For older models like Sonnet 4.5, use an integer token budget instead. Conversely, models that _only_ support adaptive thinking (Opus 4.6, 4.7, 4.8, Sonnet 4.6) automatically have token budgets coerced to `adaptive` (a warning is logged). +> On adaptive-capable Claude models, effort strings use adaptive thinking (`output_config.effort`). For older models such as Sonnet 4.5 and Haiku 4.5, Docker Agent converts effort strings, including `adaptive/`, into fixed token budgets and logs a warning. Models that only support adaptive thinking have positive token budgets converted to `adaptive` instead. ### Disabling thinking (Claude) @@ -128,6 +128,10 @@ models: thinking_budget: none # or 0 ``` +Models that support disabling thinking honor this setting. Claude models that +require thinking use adaptive thinking with low effort instead. Claude 5.x +models think adaptively by default; see the [per-model rules](../../providers/anthropic/index.md#claude-5x-models). + ### Interleaved thinking Interleaved thinking lets the model reason between tool calls — useful for complex agentic tasks. Docker Agent auto-enables it whenever a thinking budget is configured on a Claude model, so you only need to set it explicitly to turn it off: @@ -308,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 through gpt-5.5, GPT-6 Astra, Gemini 3) then fall back to the API's default behavior and still reason internally; GPT-5.x from 5.6 onward and GPT-6 Sol/Luna send `none` as a real API value that genuinely disables reasoning. +On OpenAI o-series, gpt-5 through gpt-5.5, GPT-6 Astra, and Gemini 3, `none` and `0` clear the local budget and leave the API's default reasoning behavior in effect. GPT-5.x from 5.6 onward and GPT-6 Sol/Luna instead send `none` as an API value that disables reasoning. Claude models follow the [model-specific rules above](#disabling-thinking-claude). Local models and other OpenAI-compatible backends may reason by default even when `thinking_budget` is cleared. Use @@ -331,14 +335,24 @@ support that field. ## 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`). Running `/effort` without an argument opens a picker listing the levels the current model supports: +Adjust reasoning effort in the TUI without editing your YAML: + +| Control | Action | +| --- | --- | +| Shift + Tab | Cycle through supported levels, wrapping back to the first. | +| `/effort` | Open a picker of supported levels. | +| `/effort high` | Set a level directly. | +| `/effort` + Space + Tab | Autocomplete a supported level. | + +The sidebar shows the current effort next to the model name. Available levels +depend on the model; for older Claude models, Docker Agent maps levels to fixed +token budgets. + +**Changes last for the current session only.** The next session uses the effort +configured in your YAML. -- 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. -- `/effort` only accepts levels the current model supports; requesting an unsupported level shows the model's supported list. Like Shift+Tab, it is unavailable for non-reasoning models and remote runtimes. -- Press Tab after `/effort` and a space to complete a level from the current model's supported range; it lists the same levels the picker shows (and, like the picker, offers no candidates for non-reasoning models or remote runtimes). +These controls require a reasoning-capable model and are unavailable with remote +runtimes. ## Sharing Thinking Config Across Models diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/tips/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/tips/index.md index f84803d49cbe..5f0ecc44e7e0 100644 --- a/_vendor/github.com/docker/docker-agent/docs/guides/tips/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/guides/tips/index.md @@ -8,8 +8,6 @@ aliases: - /ai/docker-agent/best-practices/ --- -_Expert guidance for building effective, efficient, and secure agents._ - ## Configuration Tips ### Auto Mode for Quick Start @@ -57,23 +55,28 @@ agents: ### Model Aliases Are Auto-Pinned -Docker Agent automatically resolves model aliases to their latest pinned versions. This ensures reproducible behavior: +Docker Agent resolves named-model aliases to dated IDs when a matching pinned model exists in its model catalog. Inline `provider/model` references and models with a custom `base_url` are left unchanged: ```yaml -# You write: -model: anthropic/claude-sonnet-4-5 +models: + claude: + provider: anthropic + model: claude-sonnet-4-5 # resolves to a matching dated ID from the catalog -# docker-agent resolves to: -# anthropic/claude-sonnet-4-5-20250929 (or latest available) +agents: + root: + model: claude ``` -To use a specific version, specify it explicitly in your config. +To guarantee the same version across catalog updates, specify a dated model ID explicitly in your config. ## Performance Tips -### Defer Tools for Faster Startup + -Large MCP toolsets can slow down agent startup. Use `defer` to load tools on-demand: +### Defer Tools to Reduce Prompt Size + +Large MCP toolsets add tool definitions to the model's context. Use `defer` to expose those definitions on demand and reduce prompt size. The MCP servers still start normally: ```yaml agents: @@ -429,6 +432,19 @@ settings: If a sound is enough, set `settings: { sound: true }` instead — Docker Agent plays a failure sound when a task errors, and a success sound when a task that ran longer than `sound_threshold` seconds (default 10) completes. +### Keep the machine awake + +Enable **Keep machine awake** in `/settings` in either TUI to prevent idle system sleep while an agent is running. It is disabled by default, and changes apply to the next agent run. The display can still turn off; the inhibitor is released when the run finishes, errors, or is canceled. + +You can also enable it in your user configuration: + +```yaml +settings: + keep_awake: true +``` + +This uses native macOS and Windows power APIs, or systemd-logind over D-Bus on Linux, with no helper executables required. Linux requires a running system bus and logind with permission to inhibit sleep. If acquisition fails, the hook reports the error without stopping the agent. It does not guarantee protection against deliberate sleep, lid closure, or administrator policy. + See the [Hooks documentation](../../configuration/hooks/index.md) for the full list of events, their payloads, and per-hook options (`env`, `working_dir`, `timeout`). ### Inject the Current Session ID with Hooks diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/troubleshooting/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/troubleshooting/index.md index a38c4cf9dedd..d8ca80b8359e 100644 --- a/_vendor/github.com/docker/docker-agent/docs/guides/troubleshooting/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/guides/troubleshooting/index.md @@ -8,8 +8,6 @@ aliases: - /ai/docker-agent/community/troubleshooting/ --- -_Common issues and how to resolve them when working with Docker Agent._ - ## Common Errors ### Context Window Exceeded @@ -144,6 +142,19 @@ Model names must match the provider's naming exactly. Common mistakes: - Using a deprecated model name (e.g. `gpt-4` instead of `gpt-5-mini` or `gpt-4o`) - Model references are case-sensitive: `openai/gpt-5-mini` ≠ `openai/GPT-5-mini` +### Conversation ends without a final reply + +A model can end a turn after using tools without returning an answer, or return +only reasoning. This can happen with thinking models such as Claude Fable 5.2. +Docker Agent emits a warning with the model and stop reason; `--exec --json` +includes it as a `warning` event. An empty `stop` does not prove that the task +finished or that the request was rate-limited. + +Check the preceding tool results before sending a follow-up: tools may already +have changed files or created commits. Docker Agent does not automatically retry +these turns. Use `--session ` to continue the session. When reporting +an unexplained stop, include the warning and sanitized `--debug` logs. + ### Network connectivity If the agent hangs or times out, check that you can reach the provider's API endpoint. Firewalls, VPNs, or proxy settings may block requests. Docker Agent does not evaluate PAC files or URLs directly. When Docker Desktop is running, eligible requests use its PAC adapter before environment proxy settings; `NO_PROXY` does not bypass that selection. Set `DOCKER_AGENT_DISABLE_DESKTOP_PROXY=1` (or `true`, `yes`, or `on`) to restore `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and `NO_PROXY` routing per request; see [Docker Desktop proxy](../../tools/fetch/index.md#docker-desktop-proxy) for scope and SSRF behavior. @@ -182,7 +193,7 @@ MCP tools using stdio transport must complete the initialization handshake befor > [!NOTE] > **Startup tool-listing timeout** > -> At startup, Docker Agent queries each toolset for its tool list. If a toolset does not respond within 10 seconds (e.g. a wedged MCP stdio server that never answers `tools/list`), that toolset is skipped with a warning and the remaining toolsets load normally. The sidebar resolves showing whichever tools did load — no infinite spinner. Enable `--debug` to see the warning message, and use `/toolset-restart ` once the server becomes responsive. +> At startup, Docker Agent queries each toolset for its tool list. If a toolset does not respond within 10 seconds (e.g. a wedged MCP stdio server that never answers `tools/list`), that toolset is skipped with a warning and the remaining toolsets load normally. Enable `--debug` to see the warning message, and use `/toolset-restart ` once the server becomes responsive. If a toolset keeps crashing in a tight loop, tune the [`lifecycle`](../../configuration/tools/index.md#toolset-lifecycle) block on the toolset (e.g. raise `backoff.initial`, lower `max_restarts`, or switch to the `best-effort` profile) so a flaky dependency does not amplify into a restart storm. @@ -276,7 +287,7 @@ A few things that catch people out: ### Delegated task appears stalled before its first response -A direct `transfer_task` delegation automatically retries once when the child model stream is silent before sending any response payload. It emits the existing warning event, and the retry is immediate and applies once to the complete child run, including later turns and fallback models. Each nested native `transfer_task` starts a new child run with its own fresh retry allowance. The retry does not apply after partial output, to `background_agents`, or when cancellation or a run budget blocks it. +When a configured [stream idle timeout](../../configuration/models/index.md#stream-idle-timeout) expires before the child model sends any response payload, a direct `transfer_task` delegation automatically retries once. The idle timeout is disabled by default. It emits the existing warning event, and the retry is immediate and applies once to the complete child run, including later turns and fallback models. Each nested native `transfer_task` starts a new child run with its own fresh retry allowance. The retry does not apply after partial output, to `background_agents`, or when cancellation or a run budget blocks it. Run with `--debug` and look for `Delegated model stream idle before response; retrying immediately`. If the child still fails, check provider connectivity, fallback configuration, cancellation, and run-budget events; Docker Agent does not retry when the context is canceled or the run budget is exhausted. diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/anthropic/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/anthropic/index.md index 0f77d8206aa6..fad8dc03c16f 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/anthropic/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/anthropic/index.md @@ -125,11 +125,10 @@ make two endpoints interchangeable. | Bedrock runtime | `amazon-bedrock`; **`ConverseStream`** | Regional Bedrock runtime endpoint | AWS SigV4 credentials or Bedrock bearer token | Exact AWS model or inference-profile ID | | OpenAI-compatible aggregators | OpenAI client, Chat Completions for Claude | Alias/custom endpoint (e.g. OpenRouter, Vercel, Azure, OpenCode) | Host-specific key | Host's catalogue ID, not necessarily a Claude API ID | -These are existing adapter paths, not a guarantee of complete Claude 5.x -compatibility. Model-specific request rules, signed history, thinking and fallback -compatibility remain the subject of the planned [core work (#4583)](https://github.com/docker/docker-agent/issues/4583) -and [fallback work (#4584)](https://github.com/docker/docker-agent/issues/4584). -This guide does not mark those changes as implemented. +These are the adapter paths Docker Agent uses. Claude 5.x request rules, signed +history and thinking ([#4583](https://github.com/docker/docker-agent/issues/4583)) +and server-side fallback ([#4584](https://github.com/docker/docker-agent/issues/4584)) +are described in the sections below. - The built-in `opencode` alias is OpenAI-compatible; the [custom OpenCode Messages provider](../opencode-zen/index.md#anthropic-compatible-messages-api) @@ -167,12 +166,14 @@ limited Google access, but the audited Google directory has no dedicated model c | Sonnet 5.5 | `claude-sonnet-5-5` | Documented | Documented | Documented | | Fable 5 | `claude-fable-5` | Documented | Documented | Documented | | Fable 5.1 | `claude-fable-5-1` | Documented | Documented | Documented | +| Fable 5.2 | `claude-fable-5-2` | Documented | Documented | Documented | | Mythos 5 | `claude-mythos-5` | Documented, gated | Limited announcement | **Unsupported** (Mantle only) | | Mythos 5.1 | `claude-mythos-5-1` | Documented, gated | Limited announcement | Documented, gated (not Mantle) | +| Mythos 5.2 | `claude-mythos-5-2` | Documented, gated | Limited announcement | Documented, gated | -The audit found **24 corroborated native model/platform pairs** (9 Claude API + -7 Vertex + 8 Bedrock runtime), **2 limited-access Mythos/Google announcements** and -**1 explicitly unsupported Mythos 5/Converse pair**. This is not 26 implemented +The audit found **29 corroborated native model/platform pairs** (11 Claude API + +8 Vertex + 10 Bedrock runtime), **3 limited-access Mythos/Google announcements** and +**1 explicitly unsupported Mythos 5/Converse pair**. These are not implemented or live-tested successes. All documented rows still require model access for your account and chosen endpoint. An absent Google card proves neither unavailability nor entitlement. @@ -181,7 +182,10 @@ Sources: [Claude model overview](https://platform.claude.com/docs/en/models/over [Claude on Vertex](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai), [Google's Claude directory](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/partner-models/claude), [Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), -[Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview) and +[Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), +[Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), +[Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), +[Google Fable 5.2](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/partner-models/claude/fable-5-2) and [AWS endpoint availability](https://docs.aws.amazon.com/bedrock/latest/userguide/models-endpoint-availability.html). According to [model IDs and versions](https://platform.claude.com/docs/en/about-claude/models/model-ids-and-versions), @@ -205,8 +209,10 @@ For regional profiles, regions and access requirements, follow the linked card. | [Sonnet 5.5](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-sonnet-5-5.html) | `anthropic.claude-sonnet-5-5` | `global.anthropic.claude-sonnet-5-5` | | [Fable 5](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-fable-5.html) | `anthropic.claude-fable-5` | `global.anthropic.claude-fable-5` | | [Fable 5.1](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-fable-5-1.html) | `anthropic.claude-fable-5-1` | `global.anthropic.claude-fable-5-1` | +| [Fable 5.2](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-fable-5-2.html) | `anthropic.claude-fable-5-2` | `global.anthropic.claude-fable-5-2` | | [Mythos 5](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-mythos-5.html) | `anthropic.claude-mythos-5` (Mantle only) | None; no runtime access | | [Mythos 5.1](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-mythos-5-1.html) | `anthropic.claude-mythos-5-1` | `global.anthropic.claude-mythos-5-1` | +| [Mythos 5.2](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-mythos-5-2.html) | `anthropic.claude-mythos-5-2` | `global.anthropic.claude-mythos-5-2` | Do not copy one model's regional prefix set onto another. The bundled models.dev snapshot's prefix coverage differs from these cards in both directions; it is a @@ -255,19 +261,19 @@ Anthropic accepts either an integer token budget or a string effort value. When ### Claude 5.x models -Docker Agent recognizes nine Claude 5.x models by ID: `claude-haiku-5-5`, `claude-opus-5`, `claude-opus-5-5`, `claude-sonnet-5`, `claude-sonnet-5-5`, `claude-fable-5`, `claude-fable-5-1`, `claude-mythos-5` and `claude-mythos-5-1`. Bedrock (`us.anthropic.…`) and Vertex (`…@date`) spellings are recognized too. For these models: +Docker Agent recognizes eleven Claude 5.x models by ID: `claude-haiku-5-5`, `claude-opus-5`, `claude-opus-5-5`, `claude-sonnet-5`, `claude-sonnet-5-5`, `claude-fable-5`, `claude-fable-5-1`, `claude-fable-5-2`, `claude-mythos-5`, `claude-mythos-5-1` and `claude-mythos-5-2`. Bedrock (`us.anthropic.…`) and Vertex (`…@date`) spellings are recognized too. For these models: - Thinking is adaptive by default and accepts every effort level: `low`, `medium`, `high`, `xhigh` and `max`. -- With `thinking_budget` unset, Haiku 5.5, Opus 5.5, Sonnet 5.5 and Fable 5.1 are sent explicit adaptive thinking (summarized display, no effort) so the server can check replayed thinking blocks; the other five keep their API default. +- With `thinking_budget` unset, Haiku 5.5, Opus 5.5, Sonnet 5.5, Fable 5.1/5.2 and Mythos 5.2 are sent explicit adaptive thinking (summarized display, no effort) so the server can check replayed thinking blocks; the other five keep their API default. - An integer token budget becomes adaptive thinking with the model's default effort; `max_tokens` is not raised. - `temperature`, `top_p` and `top_k` are never sent. -- `thinking_budget: none` (or `0`) sends `thinking: disabled` on Haiku 5.5, Opus 5 and Sonnet 5. The other six cannot disable thinking: they get adaptive thinking with `low` effort, and Docker Agent logs a warning at startup. -- Server-side `fallbacks` involving any of these models are rejected at startup until [#4584](https://github.com/docker/docker-agent/issues/4584). +- `thinking_budget: none` (or `0`) sends `thinking: disabled` on Haiku 5.5, Opus 5 and Sonnet 5. The other eight cannot disable thinking: they get adaptive thinking with `low` effort, and Docker Agent logs a warning at startup. +- Server-side `fallbacks` work with these models on the Claude API, except Haiku 5.5, which has none (see [Server-Side Fallbacks](#server-side-fallbacks)). - A request that ends on an assistant message (a response prefill) is rejected before it is sent. Tool-mode structured output therefore fails after the first plain-text answer instead of retrying with a reminder. Other Claude IDs keep the existing name-based rules. -**Token budget** (1024–32768 on models that accept manual extended thinking): +**Token budget** (at least 1024 and less than `max_tokens`, within the supported range of a model that accepts manual extended thinking): ```yaml models: @@ -345,11 +351,78 @@ Object form (forward-compatible with future budget types): See the full schema on the [Model Configuration](../../configuration/models/index.md#task-budget) page. +## Fast Mode + +Set `provider_opts.speed` to `fast` to request Anthropic's [fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode), which runs the same model at up to 2.5× higher output tokens per second: + +```yaml +models: + fast-opus: + provider: anthropic + model: claude-opus-5-5 + provider_opts: + speed: fast +``` + +Fast mode is available on supported models such as Claude Opus 5.5 and Claude Fable 5.2, and in research preview on Claude Opus 5 and Claude Opus 4.8. See Anthropic's documentation for the current list. Docker Agent does not maintain a model allowlist: on an unsupported model, or when the separate fast-mode rate limit is exceeded, the API error is returned as-is. It applies to all requests using the configured model, including internal calls such as title generation, compaction, and reranking. + +Setting `fast` routes requests through the Beta Messages API, sends `speed: "fast"`, and attaches the `fast-mode-2026-02-01` beta header. Per Anthropic's documentation, only Opus 5 and Opus 4.8 require the beta header; Docker Agent sends it on every fast-mode request. `standard` and an empty value send nothing, leaving the API's default behavior unchanged, which lets a model override a `fast` default inherited from the provider configuration. Any other value, including a non-string, is rejected when the model is loaded. + +> [!WARNING] +> Fast mode is billed at premium pricing, has its own rate limit, and switching speed invalidates the prompt cache. It is a Claude API feature and is not supported on Amazon Bedrock; availability on Vertex AI and Microsoft Foundry differs, so check Anthropic's documentation before enabling it there. It cannot be combined with the Batch API or Priority Tier. + +Cost estimates use the **actual response speed** (`usage.speed`), not the requested one: a request for `fast` that the API serves as `standard` is priced at standard rates. Anthropic [publishes](https://platform.claude.com/docs/en/build-with-claude/fast-mode#pricing) fast input and output prices at exactly twice standard (for example Claude Fable 5.2 at $16/$80 and Claude Opus 5.5 at $8/$40 per million tokens). It publishes no separate cache prices for fast mode and states that prompt-caching multipliers apply on top, so cache reads and cache writes are doubled as well, matching the fast entries gateways list for Claude Opus. Each catalogue rate, including the rates of any long-context band, is therefore multiplied by 2 for a `fast` response, when the model is served by `provider: anthropic` at the default Anthropic endpoint. Cache writes use the catalogue's single cache-write rate. Any `base_url` or `ANTHROPIC_BASE_URL` override, including proxies, keeps catalogue pricing. The factor is derived from Anthropic's published fast-mode pricing at the time of writing and may drift if Anthropic changes it. + +> [!NOTE] +> Server-side fallback attempts retain standard pricing, because attempts do not report a speed, so a fast response that used fallbacks may be under-estimated. A request routed by a rule-based router is priced by the model that served it, under the rules above. Estimates do not include negotiated discounts. A model's [`cost` override](../../configuration/models/index.md#custom-token-pricing) replaces the entire price table and is never adjusted for fast mode. + +### Global default + +To enable fast mode without editing each agent file, set it in your user configuration (`~/.config/cagent/config.yaml`). A `providers` entry with `provider: anthropic` is a native Anthropic provider, so it needs no `base_url`. Select it with its name: + +```yaml +# ~/.config/cagent/config.yaml +providers: + fast-claude: + provider: anthropic + provider_opts: + speed: fast +``` + +```bash +docker agent run agent.yaml --model fast-claude/claude-opus-5-5 +``` + +Naming the entry `anthropic` instead applies it to every model whose provider is `anthropic`, whether it comes from `--model anthropic/...`, an agent file, or `first_available`. It fills only the options a model leaves unset, so credentials and the endpoint still come from the built-in defaults: + +```yaml +providers: + anthropic: + provider: anthropic # required; an entry without it is ignored with a warning + provider_opts: + speed: fast +``` + +Alternatively, `default_model` in its full form applies fast mode when a model resolves to `auto` (`--model auto` or `model: auto`). The `DOCKER_AGENT_DEFAULT_MODEL` environment variable only accepts `provider/model` and carries no options. + +```yaml +default_model: + provider: anthropic + model: claude-opus-5-5 + provider_opts: + speed: fast +``` + +A model-level `provider_opts.speed: standard` overrides the global value, and an agent file that defines its own `providers.anthropic` replaces the user-config entry entirely. A global entry named `anthropic` covers every Anthropic request, including sub-agents, title generation, and compaction, all at premium pricing. An invalid value fails when the first Anthropic model is created. + +See [`examples/anthropic-fast-mode.yaml`](https://github.com/docker/docker-agent/blob/main/examples/anthropic-fast-mode.yaml) for a complete example. + ## Server-Side Fallbacks -When the primary model refuses a request (stop reason `refusal`), Anthropic -can retry the request with backup models in a single round trip. Set -`fallbacks` in `provider_opts` to a list of model IDs, in priority order: +When the primary model refuses a request (stop reason `refusal`), the Claude +API can retry it on a fallback model in a single round trip. Set `fallbacks` +in `provider_opts` to `default`, to use the fallback Anthropic recommends for +the refusal's category: ```yaml models: @@ -357,25 +430,72 @@ models: provider: anthropic model: claude-opus-4-8 provider_opts: + fallbacks: default +``` + +Or list up to three distinct models, tried in order: + +```yaml fallbacks: - claude-opus-4-7 - claude-sonnet-4-6 ``` -> [!WARNING] -> **Not yet available with Claude 5.x** -> -> A fallback can change the serving model mid-response, which Docker Agent does not handle yet. A `fallbacks` list is rejected at startup when the primary model or any fallback is a Claude 5.x model (Haiku 5.5, Opus 5/5.5, Sonnet 5/5.5, Fable 5/5.1, Mythos 5/5.1). Support is tracked in [#4584](https://github.com/docker/docker-agent/issues/4584). - -Docker Agent automatically attaches the required -`server-side-fallback-2026-06-01` beta header and forwards the option as -`fallbacks: [{"model": "..."}]`. The response's `model` field reports which -model actually served the request. +When a model declines mid-response, the turn continues on the fallback model. +Docker Agent never runs a tool call the declining model made, stores the turn +under the model that served it, and replays it on the next request as the API +requires. The turn's cost adds up each model hop at its own rates, combining +all of that hop's server-tool iterations. The dispatched hop retains its +configured price override when the first marker echoes the requested model, +including an alias; fallback hops use their own catalogue prices. Sticky hops +never inherit the primary's override, including across server-tool iterations. +A declined hop that produced output is billed. Before-output refusals are billed +for `bio`, `frontier_llm`, and `reasoning_extraction`; other named categories and +an explicit JSON-null category are unbilled. This also applies to the final +refusal if the fallback chain is exhausted. Missing or invalid categories, or +markers that cannot be matched to the usage hops in model order, remain billed +conservatively. The top-level usage is not added again. + +Docker Agent sends the `server-side-fallback-2026-07-01` beta header, which +accepts both forms, through the beta Messages API. The response's `model` +field reports which model actually served the request. + +For sticky routing without a handoff marker, Docker Agent uses a different +`message_start.model` provisionally when it matches an explicit fallback target +or a replayed handoff target. This preserves attribution on clean EOF before +final usage. A completed usage event clears the candidate unless a +`fallback_message` confirms fallback routing; an explicit handoff marker takes +precedence over both. Ordinary responses keep the configured model ID, display +name and cost override. A truncated alias that collides with a historical target +can still be attributed to that target; explicit fallback aliases without a +matching history marker have no early attribution. + +Rules checked at startup: + +- A list holds at most three models, each distinct and different from the + primary model. Any other value is a configuration error. +- Server-side fallback is a Claude API feature: `fallbacks` is rejected on + Vertex AI, Bedrock, a gateway, or a base URL (`base_url` or + `ANTHROPIC_BASE_URL`) whose host isn't `api.anthropic.com`. It isn't + available on the Message Batches API either. +- Claude Haiku 5.5 has no server-side fallback: a list is rejected, and + `default` only logs that it has no effect. +- The request must be valid for every listed model, or the API rejects it up + front. A configuration is rejected when a listed fallback (such as a Claude + 5.x model) refuses what the request sends: `temperature` or `top_p` (sent + only with thinking off), `top_k`, or token-budget thinking, including an + effort level that an older model without adaptive thinking turns into a + token budget. Fallback models receive the exact same request as the primary model (thinking configuration, task budget, beta features, ...), so list only -models that accept the same request shape. Not available on Bedrock, Vertex -AI, or the Message Batches API. +models that accept the same request shape. With `default` the server picks +the fallback, so per-model options such as `thinking_display` are checked +against the primary model only. The API makes one exception itself: when a Claude +Sonnet 5.5 request with `between_tools` thinking falls back to Claude Sonnet 5, +that attempt runs with thinking disabled ([fallback list rules](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#naming-your-own-fallback-models)). + +See [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback). ## Native Compaction @@ -396,9 +516,10 @@ and replaces the whole history with a signed compaction block. This first implementation is synchronous and compacts the whole history: it does not run in the background or preserve a recent tail. Legacy per-call hook extras are not included in the compaction snapshot; they are applied again on the next -normal turn. The block is persisted alongside a readable summary; the -Anthropic provider replays the block on later requests (including after a model -switch), while other providers receive the readable text. +normal turn. The block is persisted alongside a readable summary; Anthropic +models with `native_compaction` set replay the block on later requests +(including after a model switch), while other models, Vertex AI included, +receive the readable text. - The compaction request goes through the same `before_llm_call` hooks and message transforms as a regular model call, so builtins such as @@ -449,7 +570,7 @@ changed since: declared at the end of `tools` with `defer_loading: true` and surfaced by a `tool_addition`; - an effort change becomes a per-message `output_config.effort` on Claude - Opus 5, Fable 5.1 and Mythos 5.1; + Opus 5, Fable 5.1/5.2 and Mythos 5.1/5.2; - per-call system extras (environment information, prompt files and hook reminders) become text-only, turn-scoped system messages. They remain in history verbatim but stop applying at the next user turn. If the prompt ends @@ -475,8 +596,8 @@ Docker Agent attaches the `mid-conversation-tool-changes-2026-07-01`, that actually carry a tool change, a per-message effort or a turn-scoped reminder. -Supported on Claude Opus 4.8, Opus 5, Fable 5, Fable 5.1, Mythos 5 and -Mythos 5.1 (and their server-side fallbacks); Sonnet 5 and older models are +Supported on Claude Opus 4.8, Opus 5, Fable 5/5.1/5.2 and Mythos 5/5.1/5.2 +(and their server-side fallbacks); Sonnet 5 and older models are rejected at configuration time. Fallback models must also support the request's per-message effort features. The option requires the Beta Messages API. ## Thinking Display @@ -497,7 +618,7 @@ Valid values: - `summarized`: thinking blocks are returned with summarized thinking text (Docker Agent's default for adaptive/effort-based budgets). - `display`: thinking blocks are returned for display. Only accepted by pre-4.6 token-thinking models (e.g. Sonnet 4.5, Haiku 4.5); models from the adaptive-thinking generation onward (Opus/Sonnet 4.6+, Sonnet 5, Fable 5) reject it, and Docker Agent fails fast with a configuration error instead of sending a request the API would refuse. -- `updates`: short progress updates between tool calls, with reasoning text omitted. Available on Fable 5/5.1 and Mythos 5.1; automatically enables `thinking-display-updates-2026-08-18`. No explicit budget is required, and an unset effort keeps the model default. Other models (including configured fallbacks) are rejected locally. +- `updates`: short progress updates between tool calls, with reasoning text omitted. Available on Fable 5/5.1/5.2 and Mythos 5.1/5.2; automatically enables `thinking-display-updates-2026-08-18`. No explicit budget is required, and an unset effort keeps the model default. Other models (including configured fallbacks) are rejected locally. - `omitted`: thinking blocks are returned with an empty thinking field; the signature is still returned for multi-turn continuity. Useful to reduce time-to-first-text-token when streaming. Note: `thinking_display` applies to both `thinking_budget` with token counts and adaptive/effort-based budgets. For token-count budgets no default is applied (the API already defaults to `summarized`). Full thinking tokens are billed regardless of the `thinking_display` value. @@ -512,14 +633,20 @@ multiple thinking blocks, omitted thinking, redacted thinking and their signatur A hook or user edit invalidates raw replay so stale content cannot override it. When only the rest of the turn changed (for example a sanitized tool name or a redacted tool argument), its recorded thinking is still replayed in its original -place, with the current text and tool calls substituted. When the thinking itself changed, the turn loses it, -with a warning in the logs. If that turn belongs to the tool loop the next -request continues, and thinking is on, the API needs its original signed +place, with the current tool calls substituted. Unchanged text blocks retain their +contents and positions, including around fallback markers. Edited text can replace +a single original text block only when no thinking block follows it. New text can +be inserted before the first tool call (or at the end without tools) only when no +thinking block is at or after that position. Other text edits, including edits +spanning multiple blocks, cannot preserve the recorded thinking safely. When +thinking itself changed or text edits cannot be placed safely, the turn is sent +without thinking, with a warning in the logs. If that turn belongs to the tool +loop the next request continues, and thinking is on, the API needs its original signed thinking: Docker Agent refuses the request with an error instead, and a new user turn starts a fresh loop. On Claude models whose server checks thinking prefixes (Haiku 5.5, Opus 5.5, -Sonnet 5.5 and Fable 5.1), Docker Agent defaults to +Sonnet 5.5, Fable 5.1/5.2 and Mythos 5.2), Docker Agent defaults to `thinking.block_binding.prefix_mismatch_behavior: drop_block`: when earlier history changes, the API drops invalidated thinking instead of rejecting the request. Dropped blocks are reported in logs. Docker Agent does not default to @@ -531,6 +658,8 @@ history strictly anyway, set `provider_opts.thinking_prefix_mismatch: error`, an avoid compaction, handoffs, `num_history_items` and toolsets that start late. You can explicitly select `drop_block` on other supported Claude models too. Both modes attach `thinking-binding-controls-2026-08-01`; neither repairs corrupted signatures. +For the Bedrock Converse policy and observability limits, see the +[Bedrock guide](../bedrock/index.md#claude-5x-models). ## Strict Tool Arguments diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/api-route/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/api-route/index.md index 471983702252..68cf16e8358b 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/api-route/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/api-route/index.md @@ -6,8 +6,6 @@ weight: 23 canonical: https://docs.docker.com/ai/docker-agent/providers/api-route/ --- -_Use API Route models with Docker Agent._ - ## Overview [API Route](https://api-route.com) provides access to multiple model families diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/atlascloud/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/atlascloud/index.md index e25907c49d39..896056de06cc 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/atlascloud/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/atlascloud/index.md @@ -6,8 +6,6 @@ weight: 25 canonical: https://docs.docker.com/ai/docker-agent/providers/atlascloud/ --- -_Use Atlas Cloud models with Docker Agent._ - ## Overview Atlas Cloud provides access to multiple model families through an OpenAI-compatible API. Docker Agent includes built-in support for Atlas Cloud as an alias provider. @@ -39,8 +37,6 @@ Docker Agent splits only the first slash, so model IDs that include a model fami ### Named Model -For more control over parameters: - ```yaml models: atlas_qwen: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/baseten/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/baseten/index.md index e72407d6fabf..f62a94b5f25d 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/baseten/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/baseten/index.md @@ -6,8 +6,6 @@ weight: 40 canonical: https://docs.docker.com/ai/docker-agent/providers/baseten/ --- -_Use Baseten AI models with Docker Agent._ - ## Overview Baseten provides AI models through an OpenAI-compatible API. Docker Agent includes built-in support for Baseten as an alias provider. @@ -25,25 +23,21 @@ Baseten provides AI models through an OpenAI-compatible API. Docker Agent includ ### Inline Syntax -The simplest way to use Baseten: - ```yaml agents: root: - model: baseten/deepseek-ai/DeepSeek-V4-Pro + model: baseten/deepseek-ai/DeepSeek-V4-Pro-0813 description: Assistant using Baseten instruction: You are a helpful assistant. ``` ### Named Model -For more control over parameters: - ```yaml models: baseten_model: provider: baseten - model: deepseek-ai/DeepSeek-V4-Pro + model: deepseek-ai/DeepSeek-V4-Pro-0813 temperature: 0.7 max_tokens: 8192 @@ -58,12 +52,12 @@ agents: Baseten hosts various open models through its Model APIs. Check the [Baseten documentation](https://docs.baseten.co/) for the current model catalog. -| Model | Description | -| ------------------------------ | ------------------------------ | -| `deepseek-ai/DeepSeek-V4-Pro` | DeepSeek V4 Pro model | -| `moonshotai/Kimi-K2.5` | Moonshot Kimi K2.5 model | -| `openai/gpt-oss-120b` | GPT-OSS 120B model | -| `zai-org/GLM-5` | GLM-5 model | +| Model | Description | +| ------------------------------- | ------------------------- | +| `deepseek-ai/DeepSeek-V4-Pro-0813` | DeepSeek V4 Pro 0813 model | +| `moonshotai/Kimi-K3` | Moonshot Kimi K3 model | +| `openai/gpt-oss-120b` | GPT-OSS 120B model | +| `zai-org/GLM-5.3` | GLM-5.3 model | ## How It Works @@ -78,10 +72,10 @@ Baseten is implemented as a built-in alias in Docker Agent: ```yaml agents: coder: - model: baseten/deepseek-ai/DeepSeek-V4-Pro + model: baseten/deepseek-ai/DeepSeek-V4-Pro-0813 description: Code assistant using DeepSeek instruction: | - You are an expert programmer using DeepSeek V4 Pro. + You are an expert programmer using DeepSeek V4 Pro 0813. Write clean, well-documented code. Follow best practices for the language being used. toolsets: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/bedrock/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/bedrock/index.md index 6d1e4c249854..d336650ef018 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/bedrock/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/bedrock/index.md @@ -126,7 +126,7 @@ Claude 5.x profile in this audit; do not generate IDs by copying prefixes. ## Thinking Budget (Claude on Bedrock) -Bedrock Claude models support extended thinking — an internal reasoning phase before the model produces its response. Set `thinking_budget` to a token count (1024–32768) or an effort level string that maps automatically: +Bedrock Claude models support extended thinking — an internal reasoning phase before the model produces its response. On models that accept fixed token budgets, set `thinking_budget` to at least 1024 and less than `max_tokens`, or use an effort level string that maps automatically: | Effort level | Token budget | | ------------ | ------------ | @@ -140,7 +140,7 @@ Bedrock Claude models support extended thinking — an internal reasoning phase models: bedrock-claude-thinking: provider: amazon-bedrock - model: global.anthropic.claude-sonnet-5 + model: global.anthropic.claude-sonnet-4-5-20250929-v1:0 thinking_budget: 8192 # tokens, or use an effort string like "medium" max_tokens: 16384 # must be > thinking_budget provider_opts: @@ -172,18 +172,30 @@ Docker Agent recognizes these models (including Bedrock-style IDs) and transpare ### Claude 5.x models -The nine Claude 5.x models listed in the [Anthropic provider guide](../anthropic/index.md#claude-5x-models) follow the same rules on Bedrock, including Bedrock-style IDs such as `us.anthropic.claude-sonnet-5-5-v1:0`: +The eleven Claude 5.x models listed in the [Anthropic provider guide](../anthropic/index.md#claude-5x-models) follow the same rules on Bedrock, including Bedrock-style IDs such as `us.anthropic.claude-sonnet-5-5-v1:0`: - Effort levels and `adaptive` are sent as adaptive thinking. An integer token budget becomes adaptive thinking with the model's default effort. - `temperature`, `top_p` and `top_k` are never sent. -- `thinking_budget: none` sends `thinking: {"type": "disabled"}` on Haiku 5.5, Opus 5 and Sonnet 5. The other six get adaptive thinking with `low` effort and a startup warning. +- `thinking_budget: none` sends `thinking: {"type": "disabled"}` on Haiku 5.5, Opus 5 and Sonnet 5. The other eight get adaptive thinking with `low` effort and a startup warning. - Reasoning blocks are stored and replayed exactly as Bedrock returned them, in order: signed thinking (including signature-only thinking, the default display on these models), redacted thinking and the text and tool calls around them. If a message changed after it was received but its reasoning did not (for example a sanitized tool name or a redacted tool argument), its recorded reasoning is still replayed in its original place, with the current text and tool calls substituted. If the reasoning itself changed, it is sent without it, with a warning in the logs; inside the tool loop the next request continues, with thinking on, the request is refused instead, and a new user turn starts a fresh loop. Sessions saved by older versions keep that flattened replay; older versions ignore the stored blocks. - Mythos 5 is refused at startup: AWS serves it only through Bedrock Mantle, which Docker Agent does not support. Use Mythos 5.1, which is available on Converse, or the Claude API. +For Haiku 5.5, Opus 5.5, Sonnet 5.5, Fable 5.1/5.2 and Mythos 5.2, +Converse uses adaptive thinking with the `thinking-binding-controls-2026-08-01` +beta and `thinking.block_binding.prefix_mismatch_behavior: drop_block` by default. +This lets AWS drop invalidated thinking blocks when compaction, handoffs or other +history edits change their prefix. Set `provider_opts.thinking_prefix_mismatch` +to `error` to reject such requests instead, or `drop_block` to select the default +explicitly. This option is only applied to the listed models while thinking is on; +invalid option values are rejected. Neither behavior repairs corrupted signatures. +Unlike the Claude API integration, the Bedrock client does not report dropped +blocks: Converse stream transformation reporting has not been verified. +See [AWS preserved thinking documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/claude-messages-thinking-block-binding.html). + > [!NOTE] > **Not yet verified live** > -> The `disabled` value follows the Claude Messages contract; it has not yet been verified against live Bedrock Converse. +> The `disabled` value and prefix-binding controls follow the documented Claude Messages contract; they have not yet been verified against live Bedrock Converse. ## Interleaved Thinking (Claude on Bedrock) diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/cerebras/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/cerebras/index.md index bf0dba14c912..84a763650747 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/cerebras/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/cerebras/index.md @@ -6,8 +6,6 @@ weight: 50 canonical: https://docs.docker.com/ai/docker-agent/providers/cerebras/ --- -_Use Cerebras models with Docker Agent._ - ## Overview [Cerebras](https://www.cerebras.ai/) serves open-weight models such as GPT-OSS @@ -29,8 +27,6 @@ Cerebras as an alias provider. ### Inline Syntax -The simplest way to use Cerebras: - ```yaml agents: root: @@ -41,8 +37,6 @@ agents: ### Named Model -For more control over parameters: - ```yaml models: cerebras_model: 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 index 7394783fcb4f..e24de5744738 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/chatgpt/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/chatgpt/index.md @@ -6,8 +6,6 @@ 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 diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/cloudflare-ai-gateway/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/cloudflare-ai-gateway/index.md index 35b0eb5934fb..0697f2b0a725 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/cloudflare-ai-gateway/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/cloudflare-ai-gateway/index.md @@ -6,8 +6,6 @@ weight: 60 canonical: https://docs.docker.com/ai/docker-agent/providers/cloudflare-ai-gateway/ --- -_Use Cloudflare AI Gateway models with Docker Agent._ - ## Overview [Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/) is a @@ -54,8 +52,6 @@ agents: ### Named Model -For more control over parameters: - ```yaml models: cloudflare_model: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/cloudflare-workers-ai/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/cloudflare-workers-ai/index.md index 68477296aee6..4c5b228f32d9 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/cloudflare-workers-ai/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/cloudflare-workers-ai/index.md @@ -6,8 +6,6 @@ weight: 70 canonical: https://docs.docker.com/ai/docker-agent/providers/cloudflare-workers-ai/ --- -_Use Cloudflare Workers AI models with Docker Agent._ - ## Overview [Cloudflare Workers AI](https://developers.cloudflare.com/workers-ai/) runs @@ -47,8 +45,6 @@ agents: ### Named Model -For more control over parameters: - ```yaml models: cloudflare_model: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/cloudgpu/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/cloudgpu/index.md new file mode 100644 index 000000000000..59ed6fec728a --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/cloudgpu/index.md @@ -0,0 +1,110 @@ +--- +title: "CloudGPU" +description: "Use CloudGPU models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, cloudgpu +weight: 26 +canonical: https://docs.docker.com/ai/docker-agent/providers/cloudgpu/ +--- + +## Overview + +[CloudGPU](https://cloudgpu.app/api/docs) serves DeepSeek, Kimi, GLM and MiniMax +models through an OpenAI-compatible API. Docker Agent includes built-in support +for CloudGPU as an alias provider. Current model IDs are on the live +[model list](https://cloudgpu.app/v1/models). + +## Setup + +1. Create an API key in the [CloudGPU console](https://cloudgpu.app/) +2. Set the environment variable: + + ```bash + export CLOUDGPU_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +Use a CloudGPU model by prefixing its model ID with `cloudgpu/`: + +```yaml +agents: + root: + model: cloudgpu/deepseek-v4.1-flash + description: Assistant using CloudGPU + instruction: You are a helpful assistant. +``` + +### Named Model + +```yaml +models: + cloudgpu_kimi: + provider: cloudgpu + model: kimi-k3 + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: cloudgpu_kimi + description: Assistant using CloudGPU + instruction: You are a helpful assistant. +``` + +When CloudGPU is selected automatically from available credentials, the default +model is `deepseek-v4.1-flash`. + +## Available Models + +Some chat model IDs CloudGPU serves: + +| Model ID | Model | +| --- | --- | +| `deepseek-v4.1-flash` | DeepSeek V4.1 Flash (default) | +| `deepseek-v4-pro` | DeepSeek V4 Pro | +| `kimi-k3` | Kimi K3 | +| `glm-5.2` | GLM 5.2 | +| `minimax-m3` | MiniMax M3 | + +Model IDs are case-sensitive. The live [`/v1/models` endpoint](https://cloudgpu.app/v1/models) +lists current IDs, and the [API docs](https://cloudgpu.app/api/docs) describe +the endpoints. A listing does not guarantee that inference is currently available. + +CloudGPU is absent from the embedded models.dev catalog. Docker Agent does not +import context limits or attachment capabilities from CloudGPU's model list. +Attachment capabilities fall back to text-only, so image and PDF attachments +are dropped, with a warning logged once per model. + +If you have verified that your chosen model accepts a particular attachment +type, set `models..capabilities` to override detection. See +[Attachment Capability Overrides](../../configuration/models/index.md#attachment-capability-overrides) +for all supported flags. + +## How It Works + +CloudGPU is a built-in alias in Docker Agent: + +- **API type:** OpenAI-compatible Chat Completions (`openai_chatcompletions`) +- **Base URL:** `https://cloudgpu.app/v1` +- **Token variable:** `CLOUDGPU_API_KEY` + +Some models CloudGPU serves require a single leading system message, so Docker +Agent coalesces consecutive system messages into one. + +## Example: Code Assistant + +```yaml +agents: + coder: + model: cloudgpu/deepseek-v4.1-flash + description: Code assistant using CloudGPU + instruction: | + You are an expert programmer. + Write clean code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` 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 ee522a0e6a78..5a100b9f79f3 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 @@ -6,8 +6,6 @@ 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._ - ## Overview The `providers` section in your agent YAML lets you define named provider configurations that models can reference. This is useful for: @@ -166,6 +164,51 @@ agents: > > Models that stream reasoning under `delta.reasoning` (e.g. Qwen3 served via OVHcloud AI Endpoints, OpenRouter, or a self-hosted vLLM / SGLang deployment) are fully supported. Docker Agent reads both the `delta.reasoning_content` and `delta.reasoning` fields from the stream, so thinking blocks are captured and shown in the TUI regardless of which field the server uses. +### Replaying reasoning on later turns + +Captured reasoning is sent back to the model on subsequent requests as a `reasoning_content` field on the assistant message. Servers that understand the field read it back, so the model sees its own earlier reasoning instead of re-deriving it after every tool call. Reasoning that is only useful to the model is not free: replaying it can multiply the size of a long request, so it is limited to turns the session keeps anyway (those with content or a tool call). + +Chat Completions reasoning replay defaults on. Because `reasoning_content` is a +non-standard extension, set `provider_opts.replay_reasoning: false` for a model +or provider whose endpoint rejects or must not receive it. An invalid, +non-boolean value also fails closed and disables replay. + +Set the opt-out on a model, or once on a provider and let its models inherit it. +A model that sets the option itself wins over the provider: + +```yaml +providers: + local_llm: + base_url: http://localhost:8000/v1 + provider_opts: + replay_reasoning: false # opt out every local_llm model + +models: + qwen_default: + provider: local_llm + model: qwen3 # inherits the opt-out + + qwen_replay: + provider: local_llm + model: qwen3 + provider_opts: + replay_reasoning: true # opts this model back in + +agents: + root: + model: qwen_default +``` + +This option is specific to the Chat Completions API and its `reasoning_content` +field. It is not the same as `preserve_reasoning`, which replays the encrypted +reasoning items of first-party OpenAI Responses sessions; neither option +applies to the other API. See [Reasoning state preservation](../openai/index.md#reasoning-state-preservation). + +The field is worth a look if you switch models mid-session or use fallbacks: +Docker Agent stores reasoning from every provider in one place, so a later Chat +Completions model may otherwise receive reasoning captured from another vendor. +Set `replay_reasoning: false` on that destination when this is undesirable. + ### API Router (Requesty, LiteLLM) ```yaml @@ -193,7 +236,7 @@ models: ### Anthropic Team Setup -Agents can use different models backed by the same named provider. Starting from the [Default Inheritance](#default-inheritance) example: +Agents can use different models backed by the same named provider. Keep the `providers` and `models` sections from the [Default Inheritance](#default-inheritance) example and replace its `agents` section with: ```yaml agents: @@ -270,6 +313,10 @@ that automatic model selection (`model: auto`) never picks a custom provider, so reference its models explicitly with `--model /` or `default_model`. +An entry with a native `provider` (such as `provider: anthropic`) needs no +`base_url` and can carry `provider_opts`; see +[Anthropic fast mode](../anthropic/index.md#global-default) for an example. + ## How It Works When you reference a provider: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/daoxe/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/daoxe/index.md index 5e72e059c40d..90ad502ad324 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/daoxe/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/daoxe/index.md @@ -6,8 +6,6 @@ weight: 245 canonical: https://docs.docker.com/ai/docker-agent/providers/daoxe/ --- -_Use DaoXE models with Docker Agent._ - ## Overview [DaoXE](https://daoxe.com) is a multi-model LLM gateway that serves models from diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/deepseek/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/deepseek/index.md index 197af4adb203..e45b653f2f22 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/deepseek/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/deepseek/index.md @@ -6,8 +6,6 @@ weight: 80 canonical: https://docs.docker.com/ai/docker-agent/providers/deepseek/ --- -_Use DeepSeek models with Docker Agent._ - ## Overview [DeepSeek](https://www.deepseek.com/) serves its frontier chat and reasoning @@ -28,8 +26,6 @@ alias provider. ### Inline Syntax -The simplest way to use DeepSeek: - ```yaml agents: root: @@ -40,8 +36,6 @@ agents: ### Named Model -For more control over parameters: - ```yaml models: deepseek_model: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/dmr/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/dmr/index.md index 40b16848c8cf..68c72b5c97f6 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/dmr/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/dmr/index.md @@ -6,18 +6,11 @@ weight: 90 canonical: https://docs.docker.com/ai/docker-agent/providers/dmr/ --- -_Run AI models locally with Docker — no API keys, no costs, full data privacy._ - ## Overview Docker Model Runner (DMR) lets you run open-source AI models directly on your machine. Models run in Docker, so there's no API key needed; with a local runner, prompts stay on your computer. -Docker Agent automatically discovers models you have already pulled from DMR. When no model is explicitly configured, auto-selection prefers a locally-installed model (choosing the model specified via the `model:` key in the agent YAML if it is already pulled locally, or otherwise the first available non-embedding model) rather than always defaulting to `ai/qwen3:latest` and triggering a pull prompt. - -> [!TIP] -> **No API key needed** -> -> With a local DMR endpoint, your data stays on your machine. Great for development, sensitive data, or offline use. +Docker Agent automatically discovers models you have already pulled from DMR. When no model is explicitly configured, auto-selection prefers a locally-installed model (choosing the model specified via the `model:` key in the agent YAML if it is already pulled locally, or otherwise the first available non-embedding model). ## Prerequisites @@ -106,7 +99,7 @@ Use only flags your Model Runner backend allows (see `docker model configure --h ## Context size -`max_tokens` controls the **maximum output tokens** per chat completion request. To set the engine's **total context window**, use `provider_opts.context_size`: +`max_tokens` controls the **maximum output tokens** per chat completion request. To set the engine's **total context window**, use `provider_opts.context_size`. This is the only setting that reconfigures the engine; the model-level [`context_window`](../../configuration/models/index.md#context-window) is metadata for docker-agent's accounting and never changes the engine: ```yaml models: @@ -115,25 +108,30 @@ models: model: ai/qwen3 max_tokens: 4096 # max output tokens (per-request) provider_opts: - context_size: 32768 # total context window (sent via _configure) + context_size: 32768 # total context window (sent via _configure) ``` -If `context_size` is omitted, Docker Agent queries the runner's completion +If `provider_opts.context_size` is omitted, Docker Agent queries the runner's completion configuration, then falls back to the packaged model's context window. This read-only discovery is cached briefly and drives context usage and automatic -compaction. An explicit `context_size` always takes precedence; `max_tokens` is +compaction. An explicit `provider_opts.context_size` always takes precedence over discovery, and a model-level `context_window` takes precedence over both; `max_tokens` is **not** used as the context window. Discovery is best-effort. Older or unreachable runners, gateways, and runtime flags that override context allocation may leave the window unknown. In those -cases, set `context_size` explicitly. Arbitrary `raw_runtime_flags` also disable +cases, set `provider_opts.context_size` explicitly. Arbitrary `raw_runtime_flags` also disable automatic context discovery. +A model-level `context_window` also works for DMR models. docker-agent then plans +compaction and context usage against that window and leaves the engine's +allocation untouched. Set `provider_opts.context_size` too, to the same value, +when the engine should be sized to match; the two must agree. + The model picker displays DMR's reported architecture, parameter count, quantization, size, and packaged context window when available. The packaged window can differ from a running model's configured context size. -Docker Agent's auto-compaction scales its summary and keep-tail token budgets proportionally to `context_size`. This ensures compaction works correctly even for small context windows — for example, an 8k-token local model will not have its session history wiped during compaction. +Docker Agent's auto-compaction scales its summary and keep-tail token budgets proportionally to the context window. ## Thinking / reasoning budget @@ -196,6 +194,14 @@ Accepted values: any Go duration string (`"30s"`, `"5m"`, `"1h"`, `"2h30m"`), `" In multi-agent setups where two DMR models can't fit in GPU memory simultaneously, wire the [`unload`](../../configuration/hooks/index.md#available-built-ins) built-in hook into each agent's `on_agent_switch` chain. Every time the active agent transfers control, the runtime POSTs to the engine's `_unload` endpoint to free the previous model's resources before the next one is loaded: ```yaml +models: + qwen3-large: + provider: dmr + model: ai/qwen3 + qwen3-coder: + provider: dmr + model: ai/smollm2 + agents: coder: model: qwen3-large diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/fireworks/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/fireworks/index.md index 264d70f10803..f55d41ad8a93 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/fireworks/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/fireworks/index.md @@ -6,8 +6,6 @@ weight: 100 canonical: https://docs.docker.com/ai/docker-agent/providers/fireworks/ --- -_Use Fireworks AI models with Docker Agent._ - ## Overview [Fireworks AI](https://fireworks.ai/) is a fast inference host for open-weight @@ -30,8 +28,6 @@ Use the provider ID `fireworks-ai`. The legacy ID `fireworks` is also accepted. ### Inline Syntax -The simplest way to use Fireworks AI: - ```yaml agents: root: @@ -42,8 +38,6 @@ agents: ### Named Model -For more control over parameters: - ```yaml models: fireworks_model: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/github-copilot/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/github-copilot/index.md index 0d0ed150d944..be1376bb68e4 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/github-copilot/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/github-copilot/index.md @@ -6,8 +6,6 @@ weight: 110 canonical: https://docs.docker.com/ai/docker-agent/providers/github-copilot/ --- -_Use GitHub Copilot's hosted models with Docker Agent through your existing GitHub subscription._ - ## Overview GitHub Copilot exposes an OpenAI-compatible Chat Completions API at diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/google/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/google/index.md index 7981da6e7d30..e33ad1284d7f 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/google/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/google/index.md @@ -20,6 +20,8 @@ Docker Agent reads the first credential it finds from these environment variable | `GOOGLE_CLOUD_PROJECT` | GCP project used when `GOOGLE_GENAI_USE_VERTEXAI` is enabled or for Vertex AI Model Garden. | | `GOOGLE_CLOUD_LOCATION` | GCP region for Vertex AI (defaults to the SDK default). | +When the model sets no `base_url`, the Google SDK's endpoint override applies: `GOOGLE_GEMINI_BASE_URL` for the Gemini Developer API or `GOOGLE_VERTEX_BASE_URL` for Vertex AI. An explicit `base_url` takes precedence, even when it equals the default endpoint. + Explicit `provider_opts.project` or `provider_opts.location` selects Vertex AI regardless of the flag. On the Gemini Developer API, a model or [custom provider](../custom/index.md) that sets `token_key` reads its key from that variable instead of `GOOGLE_API_KEY` / `GEMINI_API_KEY`. The Vertex AI backends use Application Default Credentials and ignore `token_key`. @@ -280,7 +282,7 @@ models: The value is forwarded unchanged as the top-level `serviceTier` of every `generateContent` request on the Gemini Developer API, Vertex AI, and the Docker models gateway; the endpoint must support it. It applies to all requests using the configured model, including reranking, title generation, and compaction. Other values are passed through for the API to validate. When omitted or empty, no `serviceTier` is sent, leaving the API's default behavior unchanged. Non-string values are ignored. [Vertex AI Model Garden](#vertex-ai-model-garden) models do not use this option. -Flex requests can sit in Google's queue for up to 15 minutes before the first byte arrives. Docker Agent normally treats a stream that stays silent for 5 minutes as stalled; for `google` models with `service_tier: flex` it waits 15 minutes instead. Other tiers and providers keep the 5 minute limit. Rate-limit (`429`) and overloaded (`503`) responses are retried like any other Gemini request; Docker Agent never upgrades a request to a different tier on your behalf. +Flex requests can sit in Google's queue for up to 15 minutes before the first byte arrives. Docker Agent has no stream idle timeout by default. A short [configured stream idle timeout](../../configuration/models/index.md#stream-idle-timeout) can time out a queued Flex request. Rate-limit (`429`) and overloaded (`503`) responses are retried like any other Gemini request; Docker Agent never upgrades a request to a different tier on your behalf. > [!WARNING] > Docker Agent's cost estimates do not adjust for `service_tier`. They use the catalogue's standard pricing, which overestimates `flex` and underestimates `priority` charges. Set the model's [`cost` override](../../configuration/models/index.md#custom-token-pricing) to the applicable input, output, and cache token rates for your tier. @@ -313,7 +315,7 @@ announcements but no dedicated Google card in the 2026-10-13 audit; this proves neither unavailability nor account entitlement. See [Claude access paths](../anthropic/index.md#claude-access-paths) for model IDs, evidence and policy prerequisites. -Title, sampling and compaction clones keep the selected Model Garden transport. +Title and compaction clones keep the selected Model Garden transport. Claude requests remain on the Anthropic-native Vertex endpoints, with the model in the URL and `anthropic_version: vertex-2023-10-16` in the body. Project, location, regional/global host selection and Google OAuth authentication survive diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/groq/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/groq/index.md index 4c7d3945581c..e9bfe93c79da 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/groq/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/groq/index.md @@ -6,8 +6,6 @@ weight: 130 canonical: https://docs.docker.com/ai/docker-agent/providers/groq/ --- -_Use Groq models with Docker Agent._ - ## Overview [Groq](https://groq.com/) serves open-weight models on its LPU inference engine @@ -27,8 +25,6 @@ includes built-in support for Groq as an alias provider. ### Inline Syntax -The simplest way to use Groq: - ```yaml agents: root: @@ -39,8 +35,6 @@ agents: ### Named Model -For more control over parameters: - ```yaml models: groq_model: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/hopbase/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/hopbase/index.md new file mode 100644 index 000000000000..32563bcab5ee --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/hopbase/index.md @@ -0,0 +1,154 @@ +--- +title: "HopBase" +description: "Use HopBase models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, hopbase +weight: 135 +canonical: https://docs.docker.com/ai/docker-agent/providers/hopbase/ +--- + +## Overview + +[HopBase](https://hop-base.com) is a hosted AI API gateway. It serves GPT, +Claude, Gemini and Grok models next to DeepSeek, Zhipu GLM, Moonshot Kimi, +Alibaba Qwen and Doubao behind one base URL with an OpenAI-compatible API. +Docker Agent includes HopBase as a built-in provider in its embedded provider +catalog. + +## Setup + +1. Create an API key in the [HopBase console](https://api.hop-base.com/login). +2. Set the environment variable: + + ```bash + export HOPBASE_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +Prefix a HopBase model ID with `hopbase/`: + +```yaml +agents: + root: + model: hopbase/glm-5.3 + description: Assistant using HopBase + instruction: You are a helpful assistant. +``` + +### Named Model + +```yaml +models: + hopbase_gpt: + provider: hopbase + model: gpt-6.1-sol + max_tokens: 8192 + +agents: + root: + model: hopbase_gpt + description: Assistant using HopBase + instruction: You are a helpful assistant. +``` + +When HopBase is selected automatically from available credentials, the default +model is `glm-5.3`. Model IDs are passed through as supplied. + +## Available Models + +The examples on this page use `glm-5.3`, `gpt-6.1-sol` and `claude-sonnet-5-5`. +The models endpoint returns exactly the model IDs your key can call, so +retrieve the list before choosing another model: + +```bash +curl https://api.hop-base.com/v1/models \ + -H "Authorization: Bearer $HOPBASE_API_KEY" +``` + +Use an ID from the response unchanged as the `model` value. The list can also +contain image, video and speech models, which are not usable for chat. The +[model catalog](https://hop-base.com/models) and the +[HopBase docs](https://hop-base.com/en/docs) describe each model. + +HopBase is absent from Docker Agent's embedded models.dev catalog. Docker Agent +does not import pricing, context limits or attachment capabilities from +HopBase's model list. Attachment detection falls back to text-only, so image +and PDF attachments are dropped, with a warning logged once per model. If you +have verified that your chosen model accepts an attachment type, set +`models..capabilities`; see +[Attachment Capability Overrides](../../configuration/models/index.md#attachment-capability-overrides). +For example, `gpt-6.1-sol` accepts image input and `glm-5.3` does not: + +```yaml +models: + hopbase_vision: + provider: hopbase + model: gpt-6.1-sol + capabilities: + image: true +``` + +## How It Works + +HopBase is an entry in Docker Agent's built-in provider catalog +(`pkg/model/provider/catalog/providers.json`) that uses the existing OpenAI +implementation: + +- **API type:** OpenAI-compatible Chat Completions (`openai_chatcompletions`) +- **Base URL:** `https://api.hop-base.com/v1` +- **Token variable:** `HOPBASE_API_KEY` + +As with other multi-model hosts, Docker Agent combines consecutive system +messages for compatibility with models that require a single leading system +message. + +Claude models are callable through this alias like any other model, for +example `hopbase/claude-sonnet-5-5`. + +## Anthropic Messages Endpoint + +The same host also exposes an Anthropic Messages-compatible endpoint at +`https://api.hop-base.com` (no `/v1`). To send Claude requests in the Messages +format instead of Chat Completions, define a +[named provider](../custom/index.md) that reuses the same key: + +```yaml +providers: + hopbase_messages: + provider: anthropic + base_url: https://api.hop-base.com + token_key: HOPBASE_API_KEY + +models: + hopbase_claude: + provider: hopbase_messages + model: claude-sonnet-5-5 + +agents: + root: + model: hopbase_claude + description: Assistant using Claude through HopBase + instruction: You are a helpful assistant. +``` + +A custom Anthropic `base_url` does not inherit Claude API capability, beta or +price metadata; see +[Claude access paths](../anthropic/index.md#claude-access-paths). + +## Example: Code Assistant + +```yaml +agents: + coder: + model: hopbase/glm-5.3 + description: Code assistant using HopBase + instruction: | + You are an expert programmer. + Write clean code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/huggingface/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/huggingface/index.md index 8b5860100a71..00e619b2cbf5 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/huggingface/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/huggingface/index.md @@ -6,8 +6,6 @@ weight: 140 canonical: https://docs.docker.com/ai/docker-agent/providers/huggingface/ --- -_Use Hugging Face Inference Providers with Docker Agent._ - ## Overview [Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers/index) @@ -28,8 +26,6 @@ includes built-in support for Hugging Face as an alias provider. ### Inline Syntax -The simplest way to use Hugging Face: - ```yaml agents: root: @@ -40,8 +36,6 @@ agents: ### Named Model -For more control over parameters: - ```yaml models: huggingface_model: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/local/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/local/index.md index 86f2f99cc436..d5dc7953290e 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/local/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/local/index.md @@ -10,8 +10,6 @@ aliases: - /ai/docker-agent/providers/ollama/ --- -_Run Docker Agent with locally hosted models for privacy, offline use, or cost savings._ - ## Overview Docker Agent can connect to any OpenAI-compatible local model server. This guide covers the most popular options: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/lunaroute/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/lunaroute/index.md new file mode 100644 index 000000000000..f8b3994749f9 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/lunaroute/index.md @@ -0,0 +1,71 @@ +--- +title: "Lunaroute" +description: "Use Lunaroute models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, lunaroute +weight: 232 +canonical: https://docs.docker.com/ai/docker-agent/providers/lunaroute/ +--- + +_Use Lunaroute models with Docker Agent._ + +## Setup + +Obtain an API key from [Lunaroute](https://lunaroute.com/). Lunaroute keys are +prefixed with `lr_`. Set the environment variable: + +```bash +export LUNAROUTE_API_KEY=lr_your-api-key +``` + +## Usage + +Use the inline model reference: + +```yaml +agents: + root: + model: lunaroute/glm-5.3 + description: Assistant using Lunaroute + instruction: You are a helpful assistant. +``` + +Or configure a named model: + +```yaml +models: + lunaroute_glm: + provider: lunaroute + model: glm-5.3 + +agents: + root: + model: lunaroute_glm + instruction: You are a helpful assistant. +``` + +When Lunaroute is selected automatically from available credentials, the default +model is `glm-5.3`. Model IDs are passed through as supplied. + +## Model discovery and capabilities + +Run `docker agent models --provider lunaroute` with `LUNAROUTE_API_KEY` set to +query the authenticated `https://gw.lunaroute.com/v1/models` endpoint. The +listing also includes the configured default. Discovery is best-effort: if the +endpoint fails, the default remains available. The gateway's listing may contain +models that are not usable for chat. + +Lunaroute is absent from the embedded models.dev catalog. Discovery imports model +IDs, not pricing, context limits, or capabilities; cost tracking and automatic +capability detection therefore lack catalog metadata. Unknown attachment +capabilities fall back to text-only, so image and PDF attachments are dropped +with a warning. If you have verified a model supports them, set a +[capability override](../../configuration/models/index.md#attachment-capability-overrides). + +## How it works + +Direct requests use OpenAI-compatible Chat Completions at +`https://gw.lunaroute.com/v1` with `LUNAROUTE_API_KEY`. When a Docker Agent +models gateway is configured, the built-in alias routes through that gateway +instead; the gateway must support the Lunaroute provider and model. To use +Lunaroute directly, set `bypass_models_gateway: true` on a named model. See +[Gateway Bypass](../../configuration/models/index.md#gateway-bypass). diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/minimax/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/minimax/index.md index e6eeac606e38..6be13b2c1d9b 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/minimax/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/minimax/index.md @@ -6,8 +6,6 @@ weight: 160 canonical: https://docs.docker.com/ai/docker-agent/providers/minimax/ --- -_Use MiniMax AI models with Docker Agent._ - ## Overview MiniMax provides AI models through an OpenAI-compatible API. Docker Agent includes built-in support for MiniMax as an alias provider. @@ -25,8 +23,6 @@ MiniMax provides AI models through an OpenAI-compatible API. Docker Agent includ ### Inline Syntax -The simplest way to use MiniMax: - ```yaml agents: root: @@ -37,8 +33,6 @@ agents: ### Named Model -For more control over parameters: - ```yaml models: minimax_model: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/mistral/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/mistral/index.md index 7e40916d53c6..cd959c7f383d 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/mistral/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/mistral/index.md @@ -6,8 +6,6 @@ weight: 170 canonical: https://docs.docker.com/ai/docker-agent/providers/mistral/ --- -_Use Mistral AI models with Docker Agent._ - ## Overview Mistral AI provides powerful language models through an OpenAI-compatible API. Docker Agent includes built-in support for Mistral as an alias provider. @@ -25,8 +23,6 @@ Mistral AI provides powerful language models through an OpenAI-compatible API. D ### Inline Syntax -The simplest way to use Mistral: - ```yaml agents: root: @@ -37,8 +33,6 @@ agents: ### Named Model -For more control over parameters: - ```yaml models: mistral: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/moonshot/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/moonshot/index.md index c193d1439ce4..6dc93da22525 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/moonshot/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/moonshot/index.md @@ -6,8 +6,6 @@ weight: 180 canonical: https://docs.docker.com/ai/docker-agent/providers/moonshot/ --- -_Use Moonshot AI (Kimi) models with Docker Agent._ - ## Overview [Moonshot AI](https://www.moonshot.ai/) serves its Kimi model family through an @@ -30,8 +28,6 @@ Use the provider ID `moonshotai`. The legacy ID `moonshot` is also accepted. ### Inline Syntax -The simplest way to use Moonshot AI: - ```yaml agents: root: @@ -42,8 +38,6 @@ agents: ### Named Model -For more control over parameters: - ```yaml models: moonshot_model: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/nativ/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/nativ/index.md index 4179528acbfe..b9e8c1d0ae0b 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/nativ/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/nativ/index.md @@ -6,8 +6,6 @@ weight: 185 canonical: https://docs.docker.com/ai/docker-agent/providers/nativ/ --- -_Run Docker Agent with local MLX models served by Nativ on Apple Silicon._ - ## Overview [Nativ](https://github.com/Blaizzy/nativ) is a macOS app for downloading and diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/nebius/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/nebius/index.md index deadbaaea4b3..2972c8ffeec2 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/nebius/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/nebius/index.md @@ -1,20 +1,18 @@ --- -title: "Nebius" -description: "Use Nebius AI models with Docker Agent." -keywords: docker agent, ai agents, model providers, llm, nebius +title: "Nebius Token Factory" +description: "Use Nebius Token Factory models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, nebius, token factory weight: 190 canonical: https://docs.docker.com/ai/docker-agent/providers/nebius/ --- -_Use Nebius AI models with Docker Agent._ - ## Overview -Nebius provides AI models through an OpenAI-compatible API. Docker Agent includes built-in support for Nebius as an alias provider. +[Nebius Token Factory](https://tokenfactory.nebius.com/) (formerly Nebius AI Studio) provides hosted AI models through an OpenAI-compatible API. Docker Agent includes built-in support for Token Factory as the `nebius` alias provider. ## Setup -1. Get an API key from [Nebius AI](https://nebius.ai/) +1. Create an API key in the [Nebius Token Factory console](https://tokenfactory.nebius.com/project/api-keys) 2. Set the environment variable: ```bash @@ -25,51 +23,49 @@ Nebius provides AI models through an OpenAI-compatible API. Docker Agent include ### Inline Syntax -The simplest way to use Nebius: - ```yaml agents: root: - model: nebius/deepseek-ai/DeepSeek-V3 - description: Assistant using Nebius + model: nebius/MiniMaxAI/MiniMax-M3.1-Flash + description: Assistant using Nebius Token Factory instruction: You are a helpful assistant. ``` ### Named Model -For more control over parameters: - ```yaml models: nebius_model: provider: nebius - model: deepseek-ai/DeepSeek-V3 + model: openai/gpt-oss-120b temperature: 0.7 max_tokens: 8192 agents: root: model: nebius_model - description: Assistant using Nebius + description: Assistant using Nebius Token Factory instruction: You are a helpful assistant. ``` ## Available Models -Nebius hosts various open models. Check the [Nebius documentation](https://nebius.ai/docs) for the current model catalog. +Token Factory's catalog changes as models launch and retire, so this page does not keep a static model table. With `NEBIUS_API_KEY` set, list the Nebius models Docker Agent knows about: + +```bash +docker agent models --provider nebius +``` + +Add `--all` to list them without a key. Recent additions include `MiniMaxAI/MiniMax-M3.1-Flash`, `deepseek-ai/DeepSeek-V4.1-Flash-1017`, `zai-org/GLM-5.3` and `moonshotai/Kimi-K3`. -| Model | Description | -| ----------------------------------- | ------------------------------- | -| `deepseek-ai/DeepSeek-V3` | DeepSeek V3 model | -| `Qwen/Qwen2.5-72B-Instruct` | Qwen 2.5 72B instruction-tuned | -| `meta-llama/Llama-3.3-70B-Instruct` | Llama 3.3 70B instruction-tuned | +The listing comes from the [models.dev](https://models.dev/providers/nebius/) catalog, which can lag behind Token Factory. The [Token Factory console](https://tokenfactory.nebius.com/) is the authoritative list of models available to your project. Model IDs are case-sensitive; copy the full ID, including the vendor prefix. ## How It Works Nebius is implemented as a built-in alias in Docker Agent: - **API Type:** OpenAI-compatible (`openai_chatcompletions`) -- **Base URL:** `https://api.studio.nebius.com/v1` +- **Base URL:** `https://api.tokenfactory.nebius.com/v1` - **Token Variable:** `NEBIUS_API_KEY` ## Example: Code Assistant @@ -77,10 +73,10 @@ Nebius is implemented as a built-in alias in Docker Agent: ```yaml agents: coder: - model: nebius/deepseek-ai/DeepSeek-V3 - description: Code assistant using DeepSeek + model: nebius/moonshotai/Kimi-K3 + description: Code assistant using Nebius Token Factory instruction: | - You are an expert programmer using DeepSeek V3. + You are an expert programmer. Write clean, well-documented code. Follow best practices for the language being used. toolsets: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/nvidia/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/nvidia/index.md index 9f026e8b4a1a..b3fda107b575 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/nvidia/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/nvidia/index.md @@ -6,8 +6,6 @@ weight: 290 canonical: https://docs.docker.com/ai/docker-agent/providers/nvidia/ --- -_Use NVIDIA NIM models with Docker Agent._ - ## Overview NVIDIA provides access to Nemotron and many other open-weight models through @@ -29,8 +27,6 @@ alias provider. The same alias also works against a self-hosted ### Inline Syntax -The simplest way to use NVIDIA NIM: - ```yaml agents: root: @@ -41,8 +37,6 @@ agents: ### Named Model -For more control over parameters: - ```yaml models: nemotron: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/obscurify/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/obscurify/index.md new file mode 100644 index 000000000000..68ac77fc751e --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/obscurify/index.md @@ -0,0 +1,116 @@ +--- +title: "Obscurify.ai" +description: "Use Obscurify.ai models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, obscurify +weight: 25 +canonical: https://docs.docker.com/ai/docker-agent/providers/obscurify/ +--- + +## Overview + +[Obscurify.ai](https://obscurify.ai/?utm_source=docker-agent) is a +privacy-focused provider with an OpenAI-compatible API and 200+ models. +Accounts are a random account number with no email, and prompts and responses +are not stored on its servers. Obscurify.ai is a built-in provider in Docker +Agent's embedded provider catalog. + +The API works on every plan with a positive balance. Frontier models such as +`openai/gpt-5.5` or `anthropic/claude-sonnet-5.5` need a Casual or Pro plan; +see the [model list](https://obscurify.ai/model_cards) for prices. + +## Setup + +1. Create an account at [obscurify.ai](https://obscurify.ai/?utm_source=docker-agent) + and copy your key from the [account page](https://obscurify.ai/account) + ("Show API Key"). +2. Set the environment variable: + + ```bash + export OBSCURIFY_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +Prefix an Obscurify.ai model ID with `obscurify/`: + +```yaml +agents: + root: + model: obscurify/deepseek/deepseek-v4-flash + description: Assistant using Obscurify.ai + instruction: You are a helpful assistant. +``` + +Only the first slash separates the provider, so the rest of the model ID +(`deepseek/deepseek-v4-flash`) is sent as is. + +### Named Model + +```yaml +models: + obscurify_kimi: + provider: obscurify + model: moonshotai/kimi-k2-0905 + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: obscurify_kimi + description: Assistant using Obscurify.ai + instruction: You are a helpful assistant. +``` + +## Available Models + +A few of the chat model IDs: + +| Model ID | Context | +| --- | --- | +| `deepseek/deepseek-v4-flash` | 1,048,576 (default) | +| `z-ai/glm-5.3` | 1,048,576 | +| `moonshotai/kimi-k2-0905` | 262,144 | +| `qwen/qwen3-coder` | 262,000 | +| `meta-llama/llama-3.3-70b-instruct` | 131,072 | + +The public [`/v1/models` endpoint](https://obscurify.ai/v1/models) lists every +current ID with its context length and pricing; no key is needed to read it. + +Obscurify.ai is not in the models.dev catalog, so Docker Agent has no +catalog-derived pricing or context limits for these models. Attachment +capabilities fall back to text-only; image and PDF attachments are dropped, +with a warning logged once per model. If you know your model accepts a given +attachment type, set `models..capabilities` to override detection. See +[Attachment Capability Overrides](../../configuration/models/index.md#attachment-capability-overrides). + +## How It Works + +Obscurify.ai is an entry in Docker Agent's built-in provider catalog +(`pkg/model/provider/catalog/providers.json`) that uses the existing OpenAI +implementation: + +- **API Type:** OpenAI-compatible Chat Completions (`openai_chatcompletions`) +- **Base URL:** `https://obscurify.ai/v1` +- **Token Variable:** `OBSCURIFY_API_KEY` + +Many of its models are open-weight models whose chat templates can reject +several leading system messages, so Docker Agent merges its per-source system +messages into one. + +## Example: Code Assistant + +```yaml +agents: + coder: + model: obscurify/qwen/qwen3-coder + description: Code assistant using Obscurify.ai + instruction: | + You are an expert programmer. + Write clean code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` 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 ccfb838f661b..11eb22dabd80 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 @@ -96,7 +96,7 @@ models: native_tool_search: true ``` -Deferred tools are declared with `defer_loading: true` alongside a server-executed `tool_search` tool on Responses API requests. Strictly opt-in: only `openai` models that support deferred tools (gpt-5.4 and later) qualify; the option is ignored elsewhere (`chatgpt`, OpenAI-compatible endpoints including a custom `base_url`, Chat Completions requests) and the legacy behaviour is kept. +Deferred tools are declared with `defer_loading: true` alongside a server-executed `tool_search` tool on Responses API requests. Strictly opt-in: only `openai` models that support deferred tools (gpt-5.4 and later) qualify; the option is ignored elsewhere (`chatgpt`, OpenAI-compatible endpoints including a custom `base_url` or `OPENAI_BASE_URL`, Chat Completions requests) and the legacy behaviour is kept. See [`examples/deferred_native_tool_search.yaml`](https://github.com/docker/docker-agent/blob/main/examples/deferred_native_tool_search.yaml) for a complete example. @@ -176,7 +176,7 @@ models: - Only works with Responses API models: `gpt-4.1+`, `o1`, `o3`, `o4`, `gpt-5` - NOT compatible with the `--models-gateway` flag (automatically falls back to SSE when a gateway is configured) -- Requires `OPENAI_API_KEY` environment variable +- Uses the configured credential source or `token_key`; defaults to `OPENAI_API_KEY` when neither is configured ### Example @@ -218,9 +218,9 @@ generated values. This option does not apply to the Responses API. ## Reasoning State Preservation -Reasoning replay is opt-in, so existing configurations keep their request and -session-storage behavior. Enable it for first-party OpenAI Responses sessions, -including the `chatgpt` provider: +Responses reasoning replay is opt-in, so existing configurations keep their +request and session-storage behavior. Enable it for first-party OpenAI +Responses sessions, including the `chatgpt` provider: ```yaml provider_opts: @@ -247,3 +247,9 @@ WebSocket requests replay the full history without also chaining it through `pre See [OpenAI's reasoning guide](https://developers.openai.com/api/docs/guides/reasoning) and [cache diagnostics guide](https://developers.openai.com/api/docs/guides/prompt-caching/diagnostics). + +`preserve_reasoning` is unrelated to `provider_opts.replay_reasoning`, which +replays plain reasoning text as a `reasoning_content` field on Chat +Completions requests to OpenAI-compatible servers. It does not apply to the +Responses API, and `preserve_reasoning` does not apply to Chat Completions. +See [Replaying reasoning on later turns](../custom/index.md#replaying-reasoning-on-later-turns). diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/opencode-go/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/opencode-go/index.md index 32a3bdbe5c87..82ae5746dfa1 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/opencode-go/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/opencode-go/index.md @@ -6,8 +6,6 @@ weight: 210 canonical: https://docs.docker.com/ai/docker-agent/providers/opencode-go/ --- -_Use OpenCode Go models with Docker Agent._ - ## Overview [OpenCode Go](https://opencode.ai/docs/go) is a low-cost subscription service ($5 first month, then $10/month) that provides reliable access to popular open-source coding models. It serves models through both OpenAI-compatible and Anthropic-compatible APIs from globally distributed endpoints. @@ -28,8 +26,6 @@ Docker Agent includes built-in support for OpenCode Go as an alias provider. ### Inline Syntax -The simplest way to use OpenCode Go: - ```yaml agents: root: @@ -40,8 +36,6 @@ agents: ### Named Model -For more control over parameters: - ```yaml models: my_model: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/opencode-zen/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/opencode-zen/index.md index 30d34098df20..76e95db35a2d 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/opencode-zen/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/opencode-zen/index.md @@ -6,8 +6,6 @@ weight: 220 canonical: https://docs.docker.com/ai/docker-agent/providers/opencode-zen/ --- -_Use OpenCode Zen models with Docker Agent._ - ## Overview [OpenCode Zen](https://opencode.ai/docs/zen) is a curated gateway of tested and verified AI models provided by the OpenCode team. It offers pay-per-use access to a wide range of models — from GPT and Claude to open-source models — all through a single API key. Several free models are also available. @@ -39,8 +37,6 @@ See [Claude access paths](../anthropic/index.md#claude-access-paths). ### Inline Syntax -The simplest way to use OpenCode Zen with a free model: - ```yaml agents: root: @@ -51,8 +47,6 @@ agents: ### Named Model -For more control over parameters: - ```yaml models: zen_model: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/openrouter/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/openrouter/index.md index e55ea4b3c335..6f23464fbd28 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/openrouter/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/openrouter/index.md @@ -6,8 +6,6 @@ weight: 230 canonical: https://docs.docker.com/ai/docker-agent/providers/openrouter/ --- -_Use OpenRouter models with Docker Agent._ - ## Overview OpenRouter provides access to models from many providers through an OpenAI-compatible API. Docker Agent includes built-in support for OpenRouter as an alias provider. @@ -25,8 +23,6 @@ OpenRouter provides access to models from many providers through an OpenAI-compa ### Inline Syntax -The simplest way to use OpenRouter: - ```yaml agents: root: @@ -39,8 +35,6 @@ OpenRouter model IDs usually include the upstream provider name, such as `anthro ### Named Model -For more control over parameters: - ```yaml models: openrouter_llama: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/opper/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/opper/index.md new file mode 100644 index 000000000000..3d7c029f23d2 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/opper/index.md @@ -0,0 +1,67 @@ +--- +title: "Opper" +description: "Use Opper models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, opper +weight: 225 +canonical: https://docs.docker.com/ai/docker-agent/providers/opper/ +--- + +## Overview + +[Opper](https://opper.ai) is an EU-hosted AI gateway that serves models from +many providers behind one OpenAI-compatible endpoint, with one API key. +Docker Agent includes built-in support for Opper as an alias provider. + +## Setup + +1. Create an API key at [platform.opper.ai](https://platform.opper.ai). +2. Set the environment variable: + + ```bash + export OPPER_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +```yaml +agents: + root: + model: opper/claude-sonnet-4-6 + description: Assistant using Opper + instruction: You are a helpful assistant. +``` + +### Named Model + +```yaml +models: + opper_model: + provider: opper + model: claude-sonnet-4-6 + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: opper_model + description: Assistant using Opper + instruction: You are a helpful assistant. +``` + +## Available Models + +Opper model IDs come in two forms. A bare pool name such as +`claude-sonnet-4-6` or `gpt-5.4-mini` lets Opper pick a provider for each +request. A `provider/model` ID such as `anthropic/claude-sonnet-4-6` pins one +route. List the model IDs your key can call with: + +```bash +curl https://api.opper.ai/v3/compat/models \ + -H "Authorization: Bearer $OPPER_API_KEY" +``` + +The public catalogue is also available without a key at +`https://api.opper.ai/v3/models`. Docker Agent's default for Opper is +`claude-sonnet-4-6`. diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/orcarouter/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/orcarouter/index.md new file mode 100644 index 000000000000..69cd816ea9c7 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/orcarouter/index.md @@ -0,0 +1,84 @@ +--- +title: "OrcaRouter" +description: "Use OrcaRouter models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, orcarouter +weight: 231 +canonical: https://docs.docker.com/ai/docker-agent/providers/orcarouter/ +--- + +## Overview + +[OrcaRouter](https://www.orcarouter.ai) provides access to models from many providers through an OpenAI-compatible API. Docker Agent includes built-in support for OrcaRouter as an alias provider. + +## Setup + +1. Get an API key from [OrcaRouter](https://www.orcarouter.ai) +2. Set the environment variable: + + ```bash + $ export ORCAROUTER_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +Set the provider and model in the agent definition: + +```yaml +agents: + root: + model: orcarouter/orcarouter/auto + description: Assistant using OrcaRouter + instruction: You are a helpful assistant. +``` + +`orcarouter/auto` is OrcaRouter's adaptive router. You can also reference a model served by the gateway with its upstream provider prefix, such as `orcarouter/anthropic/claude-sonnet-4.5` or `orcarouter/deepseek/deepseek-v4-pro`. Docker Agent splits only the first slash, so the full upstream model ID is preserved. + +### Named Model + +```yaml +models: + orca_router: + provider: orcarouter + model: orcarouter/auto + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: orca_router + description: Assistant using OrcaRouter + instruction: You are a helpful assistant. +``` + +## Pricing and Model Metadata + +Docker Agent fetches OrcaRouter model metadata from [models.dev](https://models.dev/), including pricing per 1M input/output tokens, cache pricing when available, context limits, output limits, and modalities. This powers cost tracking and the model picker in the same way as other first-class providers. + +If models.dev is unavailable, Docker Agent falls back to its embedded catalog snapshot. + +## How It Works + +OrcaRouter is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai`) +- **Base URL:** `https://api.orcarouter.ai/v1` +- **Token Variable:** `ORCAROUTER_API_KEY` + +## Example: Code Assistant + +```yaml +agents: + coder: + model: orcarouter/orcarouter/auto + description: Code assistant using OrcaRouter + instruction: | + You are an expert programmer. + Write clean, maintainable code. + Explain trade-offs when helpful. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/overview/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/overview/index.md index 2f6e18ea85c9..78b71cf49a13 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/overview/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/overview/index.md @@ -13,9 +13,9 @@ _Docker Agent supports multiple AI model providers. Choose the right one for you ## Supported Providers -- [**OpenAI**](../openai/index.md) — GPT-5, GPT-5-mini, GPT-4o. The most widely used AI models. +- [**OpenAI**](../openai/index.md) — GPT-5, GPT-5-mini, GPT-4o. - [**Anthropic**](../anthropic/index.md) — Claude models for coding and analysis. See [Claude access paths](../anthropic/index.md#claude-access-paths) for protocol, host and model-specific limits. -- [**Google Gemini**](../google/index.md) — Gemini 2.5 Flash, Gemini 3 Pro. Fast and cost-effective. +- [**Google Gemini**](../google/index.md) — Gemini 2.5 Flash, Gemini 3 Pro. - [**AWS Bedrock**](../bedrock/index.md) — access Claude, Nova, Llama, and more through AWS infrastructure. - [**Docker Model Runner**](../dmr/index.md) — run models locally with Docker. No API keys, no costs. - [**Local Models**](../local/index.md) — run Ollama, vLLM, or LocalAI locally. No API key required. @@ -67,8 +67,16 @@ Use this table to find a built-in provider's config key and authentication metho | Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_GATEWAY_ID` | | Requesty | `requesty` | `REQUESTY_API_KEY` | | OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | +| Opper | `opper` | `OPPER_API_KEY` | | API Route | `api-route` | `API_ROUTE_API_KEY` | +| Lunaroute | [`lunaroute`](../lunaroute/index.md) | `LUNAROUTE_API_KEY` | +| OrcaRouter | `orcarouter` | `ORCAROUTER_API_KEY` | | Atlas Cloud | [`atlascloud`](../atlascloud/index.md) | `ATLASCLOUD_API_KEY` | +| PopNow | [`popnow`](../popnow/index.md) | `POPNOW_API_KEY` | +| Runcrate | [`runcrate`](../runcrate/index.md) | `RUNCRATE_API_KEY` | +| CloudGPU | [`cloudgpu`](../cloudgpu/index.md) | `CLOUDGPU_API_KEY` | +| Obscurify.ai | [`obscurify`](../obscurify/index.md) | `OBSCURIFY_API_KEY` | +| HopBase | [`hopbase`](../hopbase/index.md) | `HOPBASE_API_KEY` | | Azure OpenAI | `azure` | `AZURE_API_KEY` + `base_url` (override the key with `token_key`) | | [Ollama](../local/index.md) | `ollama` | None (local; optional `base_url`) | | GitHub Copilot | `github-copilot` | `GITHUB_TOKEN` or `GH_TOKEN` (PAT with `copilot` scope) | @@ -84,11 +92,6 @@ agents: model: mistral/mistral-large-latest ``` -> [!TIP] -> **Multi-provider teams** -> -> Use expensive models for complex reasoning and cheaper/local models for routine tasks. See the example below. - ## Using Multiple Providers Different agents can use different providers in the same configuration: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/ovhcloud/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/ovhcloud/index.md index f47d36781d3e..7270770ae3cb 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/ovhcloud/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/ovhcloud/index.md @@ -6,8 +6,6 @@ weight: 240 canonical: https://docs.docker.com/ai/docker-agent/providers/ovhcloud/ --- -_Use OVHcloud AI Endpoints models with Docker Agent._ - ## Overview [OVHcloud AI Endpoints](https://endpoints.ai.cloud.ovh.net/) serves open-weight diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/popnow/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/popnow/index.md new file mode 100644 index 000000000000..86628d0fb6da --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/popnow/index.md @@ -0,0 +1,98 @@ +--- +title: "PopNow" +description: "Use PopNow models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, popnow +weight: 25 +canonical: https://docs.docker.com/ai/docker-agent/providers/popnow/ +--- + +_Use PopNow models with Docker Agent._ + +## Overview + +[PopNow](https://popnow.ai/api) provides chat models from several vendors through one OpenAI-compatible API, billed per token in USD. Docker Agent includes built-in support for PopNow as a provider alias. + +## Setup + +1. [Create a PopNow API key](https://popnow.ai/api/console/keys) +2. Set the environment variable: + + ```bash + export POPNOW_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +Use a PopNow model by prefixing its model ID with `popnow/`: + +```yaml +agents: + root: + model: popnow/deepseek/v4-flash/chat + description: Assistant using PopNow + instruction: You are a helpful assistant. +``` + +Docker Agent splits only the first slash, so the vendor prefix and task suffix in PopNow model IDs are preserved. + +### Named Model + +For more control over parameters: + +```yaml +models: + popnow_deepseek: + provider: popnow + model: deepseek/v4-flash/chat + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: popnow_deepseek + description: Assistant using PopNow + instruction: You are a helpful assistant. +``` + +## Available Models + +PopNow model IDs end in a task suffix, and chat models use `/chat`: + +| Model ID | Model | +| --- | --- | +| `deepseek/v4-flash/chat` | DeepSeek V4 Flash | +| `moonshot/kimi-k3/chat` | Kimi K3 | + +Model IDs are case-sensitive. Check the [PopNow model catalog](https://popnow.ai/api/models) for current IDs and availability. Only models with the `chat` task work with Docker Agent. + +PopNow is not in the models.dev catalog, so Docker Agent has no catalog-derived pricing or context limits for these models. Attachment capabilities conservatively fall back to text-only; image and PDF attachments are dropped, with a warning logged once per model. + +If you have verified that your chosen model accepts a particular attachment type, set `models..capabilities` to override detection. See [Attachment Capability Overrides](../../configuration/models/index.md#attachment-capability-overrides) for all supported flags. + +## How It Works + +PopNow is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible Chat Completions (`openai_chatcompletions`) +- **Base URL:** `https://api.popnow.ai/v1` +- **Token Variable:** `POPNOW_API_KEY` + +Because PopNow serves models from many vendors, some of which reject multiple leading system messages, Docker Agent coalesces its per-source system messages into one. + +## Example: Code Assistant + +```yaml +agents: + coder: + model: popnow/deepseek/v4-flash/chat + description: Code assistant using PopNow + instruction: | + You are an expert programmer. + Write clean code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/runcrate/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/runcrate/index.md new file mode 100644 index 000000000000..bb323781cc27 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/runcrate/index.md @@ -0,0 +1,116 @@ +--- +title: "Runcrate" +description: "Use Runcrate models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, runcrate +weight: 25 +canonical: https://docs.docker.com/ai/docker-agent/providers/runcrate/ +--- + +## Overview + +[Runcrate](https://www.runcrate.ai/?utm_source=docker-agent&utm_medium=directory&utm_campaign=gpu_pricing) +is a GPU cloud that also serves open models (DeepSeek, GLM, Qwen, gpt-oss and +others) through an OpenAI-compatible API. Docker Agent includes built-in +support for Runcrate as an alias provider. + +Some open models come with a limited free allowance for GitHub accounts at +least 30 days old. Once the allowance is used up, or when free capacity is +busy, requests from a workspace with credit are billed to that credit. See +[Runcrate's free inference terms](https://www.runcrate.ai/inference/free?utm_source=docker-agent&utm_medium=directory&utm_campaign=gpu_pricing) +for the current models, limits and prices. + +## Setup + +1. [Create a Runcrate API key](https://www.runcrate.ai/dashboard/api-keys) +2. Set the environment variable: + + ```bash + export RUNCRATE_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +Use a Runcrate model by prefixing its model ID with `runcrate/`: + +```yaml +agents: + root: + model: runcrate/deepseek-ai/DeepSeek-V4.1-Flash + description: Assistant using Runcrate + instruction: You are a helpful assistant. +``` + +Docker Agent splits only the first slash, so model IDs that include an +organization prefix are preserved. + +### Named Model + +```yaml +models: + runcrate_glm: + provider: runcrate + model: zai-org/GLM-5.3 + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: runcrate_glm + description: Assistant using Runcrate + instruction: You are a helpful assistant. +``` + +## Available Models + +Some chat model IDs Runcrate serves: + +| Model ID | Model | +| --- | --- | +| `deepseek-ai/DeepSeek-V4.1-Flash` | DeepSeek V4.1 Flash (default) | +| `zai-org/GLM-5.3` | GLM-5.3 | +| `Qwen/Qwen3.8-Flash` | Qwen3.8 Flash | +| `openai/gpt-oss-120b` | gpt-oss 120B | + +Model IDs are case-sensitive. The live [`/v1/models` endpoint](https://api.runcrate.ai/v1/models) +lists current IDs; it also lists image, video, speech and embedding models, +which this chat provider does not use. + +Runcrate is not in the models.dev catalog. Docker Agent does not import metadata +from Runcrate's model list, so it has no catalog-derived pricing or context limits +for these models. Attachment capabilities conservatively fall back to text-only; +image and PDF attachments are dropped, with a warning logged once per model. + +If you have verified that your chosen model accepts a particular attachment +type, set `models..capabilities` to override detection. See +[Attachment Capability Overrides](../../configuration/models/index.md#attachment-capability-overrides) +for all supported flags. + +## How It Works + +Runcrate is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible Chat Completions (`openai_chatcompletions`) +- **Base URL:** `https://api.runcrate.ai/v1` +- **Token Variable:** `RUNCRATE_API_KEY` + +Because Runcrate serves open-weight models whose chat templates can reject +multiple leading system messages, Docker Agent coalesces its per-source system +messages into one. + +## Example: Code Assistant + +```yaml +agents: + coder: + model: runcrate/deepseek-ai/DeepSeek-V4.1-Flash + description: Code assistant using Runcrate + instruction: | + You are an expert programmer. + Write clean code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/together/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/together/index.md index 4cd5acd3dddf..f661adbc51ba 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/together/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/together/index.md @@ -6,8 +6,6 @@ weight: 250 canonical: https://docs.docker.com/ai/docker-agent/providers/together/ --- -_Use Together AI models with Docker Agent._ - ## Overview [Together AI](https://www.together.ai/) is one of the largest hosts of open @@ -30,8 +28,6 @@ Use the provider ID `togetherai`. The legacy ID `together` is also accepted. ### Inline Syntax -The simplest way to use Together AI: - ```yaml agents: root: @@ -42,8 +38,6 @@ agents: ### Named Model -For more control over parameters: - ```yaml models: together_model: 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 49de22e42c26..d700ea381546 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 @@ -6,8 +6,6 @@ weight: 260 canonical: https://docs.docker.com/ai/docker-agent/providers/vercel/ --- -_Use Vercel AI Gateway models with Docker Agent._ - ## Overview [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) is a single, unified @@ -35,8 +33,6 @@ only (`openai/gpt-5.6-sol`, `-terra`, `-luna`) — there is no unsuffixed ### Inline Syntax -The simplest way to use Vercel AI Gateway: - ```yaml agents: root: @@ -47,8 +43,6 @@ agents: ### Named Model -For more control over parameters: - ```yaml models: vercel_model: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/xai/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/xai/index.md index 7ba9de38180f..9b74e2a49818 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/xai/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/xai/index.md @@ -6,8 +6,6 @@ weight: 270 canonical: https://docs.docker.com/ai/docker-agent/providers/xai/ --- -_Use xAI's Grok models with Docker Agent._ - ## Overview xAI provides the Grok family of models through an OpenAI-compatible API. Docker Agent includes built-in support for xAI as an alias provider. @@ -25,8 +23,6 @@ xAI provides the Grok family of models through an OpenAI-compatible API. Docker ### Inline Syntax -The simplest way to use xAI: - ```yaml agents: root: @@ -37,8 +33,6 @@ agents: ### Named Model -For more control over parameters: - ```yaml models: grok: diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/a2a/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/a2a/index.md index 1b3315565cc2..900d26c691d9 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/a2a/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/a2a/index.md @@ -7,8 +7,6 @@ weight: 60 canonical: https://docs.docker.com/ai/docker-agent/tools/a2a/ --- -_Connect to remote agents via the Agent-to-Agent protocol._ - ## Overview The A2A tool connects to a remote agent exposed over the A2A (Agent-to-Agent) protocol. Unlike [`handoff`](../handoff/index.md), which only targets local agents declared in the same config, `a2a` reaches out to an agent running on the network. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/api/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/api/index.md index 7fd09a30fd79..ebc859c725cb 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/api/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/api/index.md @@ -7,8 +7,6 @@ weight: 240 canonical: https://docs.docker.com/ai/docker-agent/tools/api/ --- -_Create custom tools that call HTTP APIs._ - ## Overview The API tool type lets you define custom tools that make HTTP requests to external APIs. This is useful for integrating agents with REST APIs, webhooks, or any HTTP-based service without writing code. @@ -69,9 +67,13 @@ The `api` toolset accepts the following toolset-level fields in addition to the ## HTTP Methods +Only `method: GET` carries the read-only hint. Other methods are classified as `unknown`: absent overriding permissions or hooks, Restricted mode denies them, while Balanced and the legacy/default mode require confirmation. For trusted unattended POST calls, use a narrowly scoped [allow rule](../../configuration/permissions/index.md). Non-GET tools are excluded when the agent or toolset sets `readonly: true`. + +Read-only classification is not a confidentiality guarantee: GET parameters are sent to the endpoint in the URL. Use trusted endpoints and appropriate data-access and egress controls. + ### GET Requests -For GET requests, parameters are interpolated into the URL: +For GET requests, parameters are interpolated into the URL. Declare GET arguments as strings, including numeric query parameters; the GET handler decodes arguments into a string map: ```yaml toolsets: @@ -86,9 +88,9 @@ toolsets: type: string description: Search query limit: - type: integer - description: Maximum results (default 10) - required: ["query"] + type: string + description: Maximum number of results + required: ["query", "limit"] ``` ### POST Requests 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 6e8840313c9f..f3acc1623004 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 @@ -7,8 +7,6 @@ weight: 90 canonical: https://docs.docker.com/ai/docker-agent/tools/background-agents/ --- -_Dispatch work to sub-agents concurrently and collect results asynchronously._ - ## Overview The background agents tool lets an orchestrator dispatch work to sub-agents concurrently and collect results asynchronously. Unlike [transfer_task](../transfer-task/index.md) (which blocks until the sub-agent finishes), background agent tasks run in parallel — the orchestrator can start several tasks, do other work, and check on them later. @@ -30,6 +28,7 @@ The background agents tool lets an orchestrator dispatch work to sub-agents conc | `agent` | string | ✓ | Name of the sub-agent to run. Must be listed under the caller's `sub_agents`. | | `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. | +| `worktree` | bool | ✗ | Create an isolated Git checkout and branch for this task. Default `false`. | `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). @@ -66,7 +65,43 @@ A timeout returns available results and live output without stopping unfinished A stopped task can have `done: false` while its execution is still shutting down. The join waits for execution to exit, not just for the stop request to be acknowledged. Unknown or pruned IDs are reported individually as `status: "not_found"`, leave `all_done` false, and make the result a tool error; other requested tasks are still joined. Completed tasks may be pruned when the task-history limit is reached, so collect their results before dispatching many more tasks. -This is a synchronization tool, not workspace isolation: concurrent coding agents still need separate workspaces to avoid conflicting edits. +## Isolated coding tasks + +Set `worktree: true` to run concurrent coding tasks without sharing a checkout: + +```json +{"agent": "coder", "task": "Implement the backend change and commit it", "worktree": true} +``` + +This works when the calling session is in a Git repository **or an existing Git worktree**. Each task gets a fresh branch from that checkout's current `HEAD`, not the repository's default branch. Uncommitted and untracked files are **not copied**, except for gitignored files selected by the source repository's [`.worktreeinclude`](../../features/cli/index.md#copy-ignored-files-into-worktrees); commit shared starting changes before dispatching tasks. Copied ignored files can be lost when a worktree is removed and do not propagate back to the source. A missing repository or a failed setup is reported as a failed task. + +The child gets fresh toolsets and hooks rooted in its checkout; the parent's tools and process working directory are unchanged. Blocking delegations (`transfer_task` and forked skills) inherit the isolated workspace. Nested background dispatch is rejected: start parallel worktree tasks from the top-level orchestrator. Model clients are reused, and tasks share the parent's run budget and inherit its safety policy and permissions. Configured `worktree_create` hooks run before tools and skills are loaded, so setup-created ignore files and directories take effect. + +`list_background_agents` and `view_background_agent` report the checkout path, branch, and base commit once creation finishes. `wait_background_agents` includes them as `worktree`, `branch`, and `base_commit`, independently of truncated output and whether the task succeeded. + +### Review and merge at the top level + +1. Start all independent tasks with `worktree: true`. Describe files relative to the repository. The child is instructed to translate source-checkout paths to its own checkout; the child is instructed to treat attached files as read-only inputs at their original paths. +2. Have each child commit its changes on its own branch, following the project's signing policy. No commits are made automatically. +3. Wait for all tasks, check each status, and review each branch's diff. +4. Merge branches **one at a time** from the parent checkout, resolve conflicts, and run the combined tests. For example: + + ```sh + git diff HEAD...worktree-agent- + git merge --no-edit worktree-agent- + ``` + +5. After integrating the work, remove the now-unneeded checkout and branch: + + ```sh + git worktree remove /path/reported/by/the/task + git branch -d worktree-agent- + ``` + +Worktrees and branches are **retained**, including after failure, cancellation, and runtime shutdown. Uncommitted changes cannot be merged with `git merge`; inspect and commit them first. Never remove a task's checkout while it or its descendants are still running. Save the reported paths before task history is pruned. + +> [!NOTE] +> Worktrees isolate checkouts, not permissions or arbitrary external side effects. Explicit absolute tool/hook directories, external services, and shared Git configuration remain shared. External harness agents do not yet support `worktree: true`; their drivers currently inherit the process directory. Programmatic agents need a working-directory factory; configuration-loaded native agents supply one automatically. Adding tools after loading invalidates that factory unless the host supplies a replacement. Shared plans, shared todos, and default persistent memory remain shared intentionally. RAG indexes are scoped to the workspace unless an explicit database path selects shared storage. ## Configuration diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/background-jobs/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/background-jobs/index.md index c4f637901bba..191c276d8b91 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/background-jobs/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/background-jobs/index.md @@ -7,8 +7,6 @@ weight: 21 canonical: https://docs.docker.com/ai/docker-agent/tools/background-jobs/ --- -_Run and manage long-running shell commands._ - ## Overview The `background_jobs` toolset starts shell commands that should keep running while the agent continues with other work, such as local servers, file watchers, long builds, or test suites. It returns a job ID immediately, captures combined stdout/stderr up to 10 MB per job, and terminates all running jobs when the agent session ends. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/datetime/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/datetime/index.md index 6e792c792d95..e5f1068a9178 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/datetime/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/datetime/index.md @@ -7,8 +7,6 @@ weight: 146 canonical: https://docs.docker.com/ai/docker-agent/tools/datetime/ --- -_Obtain the current date, time, or datetime in a model-chosen format._ - ## Overview The `datetime` toolset exposes one read-only tool, `get_datetime`. It reads the diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/environment/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/environment/index.md index 8709c9d36419..baf8801fa2f2 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/environment/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/environment/index.md @@ -7,8 +7,6 @@ weight: 145 canonical: https://docs.docker.com/ai/docker-agent/tools/environment/ --- -_Report the OS and resolved shell so the model can pick the right syntax._ - ## Overview The environment tool exposes a single read-only call — `get_environment_info` — that returns the operating system and the resolved shell that will run shell-tool commands, e.g. `{"os":"Windows","shell":"powershell"}`. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/fetch/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/fetch/index.md index a6d967f756f7..01fd402e78a7 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/fetch/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/fetch/index.md @@ -7,8 +7,6 @@ weight: 50 canonical: https://docs.docker.com/ai/docker-agent/tools/fetch/ --- -_Read content from HTTP/HTTPS URLs._ - ## Overview The fetch tool lets agents retrieve content from one or more HTTP/HTTPS URLs. It is **read-only** — only `GET` requests are supported. The tool respects `robots.txt`, limits response size (1 MB per URL), and can return content as plain text, Markdown (converted from HTML), or raw HTML. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/file/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/file/index.md index 520bb1f87d47..0a2688f4b93d 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/file/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/file/index.md @@ -7,8 +7,6 @@ weight: 9 canonical: https://docs.docker.com/ai/docker-agent/tools/file/ --- -_Read, write, and edit individual files without exposing directory or search operations._ - ## Overview The file toolset is a focused subset of the [filesystem toolset](../filesystem/index.md). It reuses the filesystem implementations and exposes only these tools: @@ -47,5 +45,5 @@ toolsets: - ".env" post_edit: - path: "*.go" - cmd: "gofmt -w ${file}" + cmd: 'gofmt -w "${file}"' ``` diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/filesystem/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/filesystem/index.md index e80aff67c352..2cead86403b9 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/filesystem/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/filesystem/index.md @@ -7,8 +7,6 @@ weight: 10 canonical: https://docs.docker.com/ai/docker-agent/tools/filesystem/ --- -_Read, write, list, search, and navigate files and directories._ - ## Overview The filesystem tool gives agents the ability to explore codebases, read and edit files, create new files, search across files, and navigate directory structures. @@ -119,7 +117,7 @@ restriction visible to the model so it can adjust its plan. ### Post-Edit Hooks -Automatically run formatting, linting, or other commands after the agent edits a file. The command fires once per file after each edit operation (`write_file` and `edit_file`). Use `${file}` as a placeholder for the absolute path of the edited file. +Automatically run formatting, linting, or other commands after the agent edits a file. The command fires once per file after each edit operation (`write_file` and `edit_file`). The command receives the absolute path in the `file` environment variable. With a POSIX shell, use `"${file}"` to preserve spaces and shell metacharacters in the path; use the corresponding environment-variable syntax for other shells. ```yaml toolsets: @@ -127,17 +125,17 @@ toolsets: ignore_vcs: false post_edit: - path: "*.go" - cmd: "gofmt -w ${file}" + cmd: 'gofmt -w "${file}"' - path: "*.ts" - cmd: "prettier --write ${file}" + cmd: 'prettier --write "${file}"' - path: "src/*/*.py" - cmd: "black ${file}" + cmd: 'black "${file}"' ``` | Property | Type | Description | | --- | --- | --- | | `path` | string | Glob pattern matched against the file path. `*.go` matches any `.go` file; `src/*/*.ts` matches `.ts` files inside `src/`. | -| `cmd` | string | Shell command to run. `${file}` expands to the absolute path of the just-edited file. | +| `cmd` | string | Shell command to run. The `file` environment variable contains the absolute path of the just-edited file; quote its expansion using your shell's syntax. | Post-edit commands run with the same working directory as the agent. If a command exits non-zero, the tool reports that the write or edit succeeded but the post-edit command failed. The edit is not rolled back. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/git/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/git/index.md index 9568b7508dfa..a5402ccce17c 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/git/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/git/index.md @@ -7,14 +7,10 @@ weight: 125 canonical: https://docs.docker.com/ai/docker-agent/tools/git/ --- -_Read-only inspection of the working git repository._ - ## Overview The git toolset gives an agent structured, **read-only** access to the working repository — status, history, branches, a commit's changes, and line-level authorship. It is implemented with go-git, so it needs **no `git` binary**. -Compared with running `git` through the `shell` tool, the git toolset returns clean, structured output the model can read reliably, is **safe by construction** (no command can modify the repository), and works even when `shell` is disabled or no `git` binary is installed. - > [!NOTE] > The git toolset is read-only. To stage, commit, or check out, use the [`shell`](../shell/index.md) tool. @@ -93,8 +89,3 @@ On branch master 1 changed file(s) [XY = staged/worktree; M=modified A=added D=deleted R=renamed ?=untracked]: M main.go ``` - -> [!TIP] -> **When to use** -> -> Use the git toolset whenever the agent needs repository context — before editing, to review recent history, or to find who last touched a line — without exposing the writable `shell` surface. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/handoff/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/handoff/index.md index 4375be03daac..453a61166e97 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/handoff/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/handoff/index.md @@ -7,8 +7,6 @@ weight: 70 canonical: https://docs.docker.com/ai/docker-agent/tools/handoff/ --- -_Hand off the active conversation to another local agent defined in the same config._ - ## Overview The `handoff` tool lets an agent transfer control of the **current conversation** to another agent in the **same config file**. Unlike [`transfer_task`](../transfer-task/index.md), which delegates a sub-task and collects the result, `handoff` rewires the session so the receiving agent continues the conversation directly with the user. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/lsp/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/lsp/index.md index 97adbadeff5b..ae7d702d5bf9 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/lsp/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/lsp/index.md @@ -7,8 +7,6 @@ weight: 220 canonical: https://docs.docker.com/ai/docker-agent/tools/lsp/ --- -_Connect to Language Server Protocol servers for code intelligence._ - ## Overview The LSP tool connects your agent to any Language Server Protocol (LSP) server, providing comprehensive code intelligence capabilities like go-to-definition, find references, diagnostics, and more. @@ -63,7 +61,7 @@ agents: | ------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- | | `command` | string | ✓ | LSP server executable command | | `args` | array | ✗ | Command-line arguments for the LSP server | -| `env` | object | ✗ | Environment variables for the LSP process | +| `env` | object | ✗ | Environment variables for the LSP process. When a key is also set in the host environment, the value from `env` wins. | | `file_types` | array | ✗ | File extensions this LSP handles (e.g., `[".go", ".mod"]`) | | `working_dir` | string | ✗ | Working directory for the LSP server process. Relative paths are resolved against the agent's working directory. Defaults to the agent's working directory when omitted. | | `version` | string | ✗ | Package reference for [auto-installing](../../configuration/tools/index.md#auto-installing-tools) the command binary | @@ -197,7 +195,7 @@ Available Capabilities: LSP toolsets are managed by the same supervisor as MCP toolsets, so a crashed `gopls` (or any other language server) is reconnected automatically with exponential backoff. Use the [`lifecycle`](../../configuration/tools/index.md#toolset-lifecycle) block to tune the policy per toolset — for example, mark `gopls` as `strict` if your CI flow requires it to be available, or use `/toolset-restart gopls` from the TUI to force a reconnect when the server gets stuck. -**Startup failure behaviour:** missing-binary and bad-config failures fail fast — each turn retries immediately with no artificial delay. A language server that crash-loops (3 crashes within 1 minute, by default) is different: the supervisor stops auto-restarting and reports the loop instead. The next attempt to use the toolset (a turn's start, a tool call, or `/toolset-restart`) surfaces that report rather than relaunching the server, and the backoff gate then paces subsequent attempts (15s, doubling up to 5 minutes) the same way it paces a rate-limited MCP server — so a server that dies right after every restart no longer relaunches at full speed. This applies regardless of `profile`: even a `strict` toolset is retried on the next turn once its window elapses, rather than staying down until an explicit `/toolset-restart`. +**Startup failure behaviour:** missing-binary and bad-config failures fail fast — each turn retries immediately with no artificial delay. A language server that crash-loops (3 crashes within 1 minute, by default) is different: the supervisor stops auto-restarting and reports the loop instead. The next attempt to use the toolset (a turn's start, a tool call, or `/toolset-restart`) surfaces that report rather than relaunching the server, and the backoff gate then paces subsequent attempts (15s, doubling up to 5 minutes) the same way it paces a rate-limited MCP server. This applies regardless of `profile`: even a `strict` toolset is retried on the next turn once its window elapses, rather than staying down until an explicit `/toolset-restart`. ```yaml toolsets: diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/mcp-catalog/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/mcp-catalog/index.md index d395a3ef6de7..a85a9c64bbf9 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/mcp-catalog/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/mcp-catalog/index.md @@ -7,8 +7,6 @@ weight: 120 canonical: https://docs.docker.com/ai/docker-agent/tools/mcp-catalog/ --- -_Let the agent discover and activate remote MCP servers from the Docker MCP Catalog on demand._ - ## Overview The `mcp_catalog` toolset gives an agent access to a curated subset of the [Docker MCP Catalog](https://hub.docker.com/search?q=&type=mcp) — every server in this subset is reachable over the **streamable-http** transport, so Docker Agent can talk to it directly without the MCP gateway or a local subprocess. 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 408d4696729b..150bb6f0b4d1 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 @@ -9,8 +9,6 @@ aliases: - /ai/docker-agent/integrations/mcp/ --- -_Extend agents with external tools via the Model Context Protocol (MCP)._ - ## Overview The `mcp` toolset connects your agent to any MCP server — a process or remote service that exposes tools, resources, and prompts over the [Model Context Protocol](https://modelcontextprotocol.io/). Three flavours are supported: @@ -68,7 +66,7 @@ toolsets: | `command` | string | Command to execute the MCP server. | | `args` | array | Command arguments. | | `tools` | array | Optional whitelist — only expose these tools. | -| `env` | object | Environment variables (key-value pairs). | +| `env` | object | Environment variables (key-value pairs) for the server process. The process also inherits the host environment; when a key is set in both, the value from `env` wins. | | `working_dir` | string | Working directory for the MCP server process. Relative paths are resolved against the agent's working directory. Defaults to the agent's working directory when omitted. Supports `${env.VAR}` (canonical), plus `~` and shell-style `$VAR`/`${VAR}` expansion ([details](../../configuration/overview/index.md#variable-expansion-in-config-fields)). | | `instruction` | string | Custom instructions injected into the agent's context. | | `version` | string | Package reference for [auto-installing](../../configuration/tools/index.md#auto-installing-tools) the command binary. | @@ -101,6 +99,7 @@ toolsets: | `remote.transport_type` | string | `streamable` or `sse`. | | `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#configuration) 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). | +| `remote.standalone_sse` | boolean | Open the streamable-HTTP standalone SSE `GET` stream (default `false`). Enable for gateways that send keepalive pings or `notifications/tools/list_changed` and close sessions they cannot reach, such as the sbx MCP gateway. Ignored for `sse`. | | `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). @@ -109,7 +108,7 @@ When Docker Desktop is running, eligible MCP OAuth discovery, token, and helper ## 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. +MCP servers can expose **prompts** — named, parameterized templates that the server provides via the `prompts/list` and `prompts/get` protocol methods. 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 @@ -126,7 +125,7 @@ MCP servers can expose **prompts** — named, parameterized templates that the s - 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. +> MCP prompt discovery requires a YAML-declared `mcp` toolset. Prompts from servers activated through the [Docker MCP Catalog](../../tools/mcp-catalog/index.md) (`type: mcp_catalog`, activated with `enable_remote_mcp_server`) are not currently surfaced. YAML-declared `type: mcp` entries with `ref: docker:` do participate in prompt discovery. ## Embedded Resources @@ -134,7 +133,7 @@ MCP tool results can include embedded resources — images, PDFs, and text files - **Anthropic** — images become `image` blocks in the `tool_result`; PDFs and other documents become `document` blocks. - **OpenAI** — images are forwarded as `input_image` data URIs; PDFs as `input_file` data URIs in the tool result content. -- **OpenAI Chat Completions** (`api_type: openai_chatcompletions`, the default, and OpenAI-compatible providers) — tool messages only accept text, so images (including image documents) are sent as text in the tool message as their data URI or URL. PDFs and other documents are attached in a follow-up user message labeled "Attached content from tool result:". +- **OpenAI Chat Completions** (`api_type: openai_chatcompletions`, selected automatically for models without Responses API support or set explicitly) — tool messages only accept text, so images (including image documents) are sent as text in the tool message as their data URI or URL. PDFs and other documents are attached in a follow-up user message labeled "Attached content from tool result:". - **Bedrock** and **Gemini** — receive equivalent provider-native representations. No configuration is required. When an MCP server returns an embedded resource alongside its text output, the resource is automatically attached and sent to the model on the next turn. This is useful for MCP servers that generate charts, export PDFs, or return binary data as part of their responses. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/memory/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/memory/index.md index 1e5671a304ea..5a34fb3dc5e4 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/memory/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/memory/index.md @@ -7,8 +7,6 @@ weight: 100 canonical: https://docs.docker.com/ai/docker-agent/tools/memory/ --- -_Persistent key-value storage backed by SQLite for cross-session recall._ - ## Overview The memory tool provides persistent key-value storage backed by SQLite. Data survives across sessions, allowing agents to remember facts, user preferences, project context, and past decisions. Memories can be organized with categories and searched by keyword. @@ -54,6 +52,3 @@ Memories support an optional `category` field for organization and filtering. Co - `fact` — Factual information about the project or user - `project` — Project-specific context - `decision` — Past decisions and their rationale - -> [!TIP] -> Memory is especially useful for long-running assistants that need to recall information across conversations — like coding preferences, project conventions, or context discovered during previous sessions. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/model-picker/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/model-picker/index.md index 0c0d4613021c..14c0a8a3c595 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/model-picker/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/model-picker/index.md @@ -7,8 +7,6 @@ weight: 200 canonical: https://docs.docker.com/ai/docker-agent/tools/model-picker/ --- -_Let the agent pick between several models per turn._ - ## Overview The model picker tool gives an agent the ability to dynamically choose which model to use for each turn of the conversation. This is useful when you want the agent to route different types of requests to different models — for example, using a fast, inexpensive model for simple queries and a more capable model for complex reasoning tasks. @@ -51,11 +49,6 @@ agents: - openai/gpt-5 ``` -> [!TIP] -> **Cost optimization** -> -> The model picker tool is particularly useful for cost optimization: let the agent use a cheap model by default and only escalate to expensive models when necessary. - ## Tool Interface The toolset exposes two tools: diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/open-url/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/open-url/index.md index b2a97dd44b36..24122dd7bbfb 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/open-url/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/open-url/index.md @@ -7,8 +7,6 @@ weight: 40 canonical: https://docs.docker.com/ai/docker-agent/tools/open-url/ --- -_Open a fixed URL in the user's default browser._ - ## Overview The `open_url` toolset exposes a single, argument-less tool that opens a URL diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/openapi/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/openapi/index.md index c98a703c1b01..75d91f8ed567 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/openapi/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/openapi/index.md @@ -7,8 +7,6 @@ weight: 230 canonical: https://docs.docker.com/ai/docker-agent/tools/openapi/ --- -_Automatically generate tools from an OpenAPI specification._ - ## Overview The OpenAPI tool fetches an OpenAPI 3.x specification from a URL and creates one tool per API operation. Each endpoint's parameters, request body, and description are translated into a callable tool that the agent can invoke directly. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/plan/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/plan/index.md index 53076c4c43ba..b56a41656d37 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/plan/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/plan/index.md @@ -7,13 +7,11 @@ weight: 150 canonical: https://docs.docker.com/ai/docker-agent/tools/plan/ --- -_Shared persistent scratchpad for multi-agent collaboration._ - ## Overview -The plan tool gives agents a shared, persistent scratchpad of named documents. Any agent in a multi-agent config that loads the `plan` toolset can read and write the same plans, and those plans survive across sessions. This makes it straightforward to wire a planner agent that sketches work and one or more executor agents that consume it without any custom tool wiring. +The plan tool gives agents a shared, persistent scratchpad of named documents. Any agent in a multi-agent config that loads the `plan` toolset can read and write the same plans, and those plans survive across sessions. -Plans are stored as JSON files in the Docker Agent data directory (`~/.cagent/plans/` by default). Agents that share a process serialize on a single mutex, and every write or delete additionally holds an advisory lock on a sentinel file in the plans directory, so writers in *separate* Docker Agent processes are serialized too: concurrent edits can never silently overwrite each other, and a stale revision always fails with a deterministic version conflict. Writes are atomic (temp file + rename), so a reader never observes partial content. +Plans are stored as JSON files in the Docker Agent data directory (`~/.cagent/plans/` by default). Agents that share a process serialize on a single mutex, and every write or delete additionally holds an advisory lock on a sentinel file in the plans directory, so writers in *separate* Docker Agent processes are serialized too: a stale revision fails with a deterministic version conflict when the caller supplies `last_known_revision`. Without that guard, updates are last-writer-wins. Writes are atomic (temp file + rename), so a reader never observes partial content. ## Configuration diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/rag/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/rag/index.md index 6563e75390e4..c5b41bd6f23a 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/rag/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/rag/index.md @@ -11,6 +11,12 @@ aliases: _Give your agents access to document knowledge bases with background indexing, multiple retrieval strategies, and hybrid search._ +> Relative document and database paths resolve from the agent's working directory +> (or the configuration directory when no working directory is set). Default +> database files are stored under the data directory, scoped by workspace, so +> isolated worktrees do not mix indexed documents. Explicit absolute database +> paths retain their sharing semantics. + ## Overview The `rag` toolset lets agents search through your documents to find relevant information before responding. Knowledge bases are declared once at the top of the config under `rag:` and then referenced from any agent via `type: rag, ref: `. Docker Agent supports: @@ -60,6 +66,12 @@ loaded with different credentials, gets its own index. Background indexing for a shared knowledge base is not attributed to any session. ```yaml +rag: + my_docs: + docs: [./documents] + strategies: + - type: bm25 + agents: researcher: model: anthropic/claude-sonnet-4-5 @@ -201,7 +213,7 @@ chunking: > [!NOTE] > **Language Support** > -> Currently supports Go (`.go`) files. More languages will be added. Falls back to plain text chunking for unsupported file types. +> Supports Go (`.go`) files. Falls back to plain text chunking for unsupported file types. ## Indexing failures, retries and backoff @@ -224,9 +236,7 @@ on the failure: file in the run is successfully indexed** — every attempted file hit one of these retryable statuses — the run treats that as a sustained backend failure rather than a one-off hiccup, and surfaces the error so the gate - arms on the next turn (fixed in - [#4097](https://github.com/docker/docker-agent/issues/4097); previously - only 429 reached the gate). + arms on the next turn. | Failure kind | Behaviour | |---|---| @@ -272,11 +282,8 @@ Starting any toolset — RAG included — is bounded by a 30-second *wait* budge tools, exactly as it would for a wedged MCP server. This budget exists to detect toolsets that never come up; it is not a deadline on indexing itself. -A large knowledge base can legitimately take much longer than 30s to index. -Rather than abort in-flight indexing at the 30s mark — which used to discard -any embeddings not yet committed for the file being processed — the RAG -toolset detaches indexing from the caller's wait budget the same way it -already detaches its file watcher. When the 30s budget expires: +Indexing can continue beyond the 30-second startup wait budget. When that +budget expires: - The current turn proceeds without the RAG tool (the existing "taking too long to start" warning and TUI progress events still apply). @@ -288,10 +295,9 @@ already detaches its file watcher. When the 30s budget expires: the tool is available immediately; if it is still running, that turn also proceeds without the tool. -This is a **visible behavior change**: knowledge bases that used to finish -indexing (and thus offer the tool) on the very first turn, within the old -30-second window, now do so on whichever turn happens to land after indexing -completes. If indexing takes under 30s, nothing changes. +Indexing that finishes within the 30-second wait budget can expose the tool on +the current turn. If indexing outlives that budget, the tool becomes available +on a later turn after indexing completes. `indexing_timeout` bounds indexing itself, independent of the 30s wait budget — it exists only so a hung provider connection cannot pin a knowledge @@ -305,6 +311,7 @@ rag: strategies: - type: chunked-embeddings embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 ``` - Default: `30m` when omitted. @@ -317,17 +324,6 @@ rag: unaffected by any of this — it still aborts the run and arms the backoff gate exactly as described above. -### Operational impact - -**Before**: a rate-limited knowledge base was re-indexed on every agent turn — -`max_indexing_concurrency × max_embedding_concurrency` concurrent provider calls -could relaunch within milliseconds, easily tripping rate limits for both the -knowledge base and the agent's own model calls. - -**After**: retries are spaced out and jittered so the provider has room to recover -before the next attempt. The agent continues working with any other toolsets that -are not affected. - ### What you will see - Docker Agent logs a single warning when a knowledge base first fails to start. @@ -353,6 +349,8 @@ If you see persistent `429`, `5xx`, or `408` errors in the logs: docs: [./knowledge-base] strategies: - type: chunked-embeddings + embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 max_indexing_concurrency: 1 max_embedding_concurrency: 1 ``` @@ -387,7 +385,7 @@ Look for log tags: `[RAG Manager]`, `[Chunked-Embeddings Strategy]`, `[BM25 Stra | Field | Type | Default | Description | | ------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `docs` | []string | — | Document paths/directories (shared across strategies) | -| `description` | string | — | Human-readable description of this RAG source | +| `tool.description` | string | — | Description of the search tool shown to the model | | `respect_vcs` | boolean | `true` | Respect `.gitignore` files when indexing documents | | `indexing_timeout` | string | `30m` | Cap on a single indexing run, detached from the 30s toolset-start wait budget; `0s` = unbounded. See [Long indexing runs](#long-indexing-runs) | | `strategies` | []object | — | Array of retrieval strategy configurations | @@ -399,7 +397,7 @@ Look for log tags: `[RAG Manager]`, `[Chunked-Embeddings Strategy]`, `[BM25 Stra | --------------------------- | ------ | ------------------- | ------------------------------------------------------------ | | `embedding_model` | string | — | **Required.** Embedding model reference | | `database` | string | — | Path to local SQLite database | -| `vector_dimensions` | int | — | Embedding dimensions (e.g., 1536 for text-embedding-3-small) | +| `vector_dimensions` | int | — | **Required.** Embedding dimensions (e.g., 1536 for text-embedding-3-small) | | `similarity_metric` | string | `cosine_similarity` | Similarity metric | | `threshold` | float | `0.5` | Minimum similarity score (0–1) | | `limit` | int | `5` | Max results from this strategy | 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 index 16635f7f77f2..2b5c40dc8b23 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/scheduler/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/scheduler/index.md @@ -7,8 +7,6 @@ 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). diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/script/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/script/index.md index b4f912705517..5fba0df4de2e 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/script/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/script/index.md @@ -7,11 +7,9 @@ weight: 30 canonical: https://docs.docker.com/ai/docker-agent/tools/script/ --- -_Define custom shell scripts as named tools with typed parameters._ - ## Overview -The script tool lets you define custom shell scripts as named tools. Unlike the generic [shell tool](../shell/index.md) where the agent writes the command, script tools execute predefined commands — ideal for exposing safe, well-scoped operations with descriptive names. +The script tool lets you define custom shell scripts as named tools. Unlike the generic [shell tool](../shell/index.md) where the agent writes the command, script tools execute predefined commands. ## Configuration @@ -57,8 +55,3 @@ toolsets: | `shell..required` | array | Required parameter names | | `shell..env` | object | Environment variables for this script | | `shell..working_dir` | string | Working directory for script execution | - -> [!TIP] -> **Script vs. Shell** -> -> Use the [shell tool](../shell/index.md) when the agent needs to run arbitrary commands. Use the script tool when you want to expose specific, predefined operations with clear names and typed parameters — giving the agent less freedom but more safety. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/session_context/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/session_context/index.md index 9f241bb551db..bf786a15e91a 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/session_context/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/session_context/index.md @@ -7,11 +7,9 @@ weight: 210 canonical: https://docs.docker.com/ai/docker-agent/tools/session_context/ --- -_Reference a previous session as context, without manual export/import._ - ## Overview -The `session_context` toolset lets an agent discover earlier sessions and pull one in as context for the current session. It removes the manual workaround of exporting a conversation to HTML and re-attaching it with an `@` mention. +The `session_context` toolset lets an agent discover earlier sessions and pull one in as context for the current session. The tool surface is two read-only tools: diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/shell/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/shell/index.md index bc1958f593f6..cd49431c5b9b 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/shell/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/shell/index.md @@ -7,11 +7,9 @@ weight: 20 canonical: https://docs.docker.com/ai/docker-agent/tools/shell/ --- -_Execute arbitrary shell commands in the user's environment._ - ## Overview -The shell tool allows agents to execute arbitrary shell commands synchronously. This is one of the most powerful tools — it lets agents run builds, install dependencies, query APIs, and interact with the system. Each call runs in a fresh, isolated shell session — no state persists between calls. +The shell tool allows agents to execute arbitrary shell commands synchronously. Each call runs in a fresh, isolated shell session — no state persists between calls. Commands have a default 30-second timeout and require user confirmation unless `--yolo` is used. For servers, watchers, and other long-running commands, add the [`background_jobs`](../background-jobs/index.md) toolset alongside `shell`. @@ -126,8 +124,3 @@ The shell toolset exposes one tool: > **Safety** > > The shell tool gives agents full access to the system shell. Always set `max_iterations` on agents that use the shell tool to prevent infinite loops. A value of 20–50 is typical for development agents. Use [Sandbox Mode](../../configuration/sandbox/index.md) for additional isolation. - -> [!NOTE] -> **Tool Confirmation** -> -> By default, Docker Agent asks for user confirmation before executing shell commands. Use `--yolo` to auto-approve all tool calls. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/tasks/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/tasks/index.md index 9d399f96958b..939b76f94e27 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/tasks/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/tasks/index.md @@ -7,8 +7,6 @@ weight: 180 canonical: https://docs.docker.com/ai/docker-agent/tools/tasks/ --- -_Persistent task database with priorities and dependencies, shared across sessions._ - ## Overview The tasks tool provides a persistent task database that survives across agent sessions. Unlike the [Todo tool](../todo/index.md), which maintains an in-memory task list for the current session only, the tasks tool stores tasks in a JSON file on disk so they can be accessed and updated across multiple sessions. Tasks support priorities and dependencies — a task is _blocked_ until every task it depends on is `done`. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/think/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/think/index.md index 7ed1e0ed0eeb..a84ad61306d1 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/think/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/think/index.md @@ -7,13 +7,11 @@ weight: 140 canonical: https://docs.docker.com/ai/docker-agent/tools/think/ --- -_Step-by-step reasoning scratchpad for planning and decision-making._ - ## Overview The think tool is a reasoning scratchpad that lets agents think step-by-step before acting. The agent can write its thoughts without producing visible output to the user — ideal for planning complex tasks, breaking down problems, and reasoning through multi-step solutions. -This lightweight tool changes only its internal scratchpad, not external data. It is most useful for models that lack built-in reasoning or thinking capabilities (e.g., smaller or older models). For models that already support native thinking — such as Claude with extended thinking, OpenAI o-series, or Gemini with a thinking budget — this tool is unnecessary since the model can reason internally. +This lightweight tool changes only its internal scratchpad, not external data. It is most useful for models that lack built-in reasoning or thinking capabilities (e.g., smaller or older models). For models that already support native thinking — such as Claude with extended thinking, OpenAI o-series, or Gemini with a [thinking budget](../../configuration/models/index.md#thinking-budget) — this tool is unnecessary since the model can reason internally. ## Configuration @@ -24,11 +22,6 @@ toolsets: No configuration options. -> [!TIP] -> **When to use** -> -> Use the think tool with models that don't have native reasoning capabilities. If your model already supports a [thinking budget](../../configuration/models/index.md#thinking-budget), you likely don't need this tool. - ## Scope and lifetime Thoughts are isolated by conversation ID, calling agent and think toolset instance. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/todo/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/todo/index.md index 7f2154379cce..da8c07ed307e 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/todo/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/todo/index.md @@ -7,11 +7,9 @@ weight: 170 canonical: https://docs.docker.com/ai/docker-agent/tools/todo/ --- -_Task list management for complex multi-step workflows._ - ## Overview -The todo tool provides task list management. Agents can create, update, list, and track progress on tasks with status tracking (pending, in-progress, completed). Useful for complex multi-step workflows where the agent needs to stay organized and ensure all steps are completed. +The todo tool provides task list management. Agents can create, update, list, and track progress on tasks with status tracking (pending, in-progress, completed). ## Available Tools diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/transfer-task/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/transfer-task/index.md index ef4831bb51e2..deeea03a6e74 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/transfer-task/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/transfer-task/index.md @@ -7,8 +7,6 @@ weight: 80 canonical: https://docs.docker.com/ai/docker-agent/tools/transfer-task/ --- -_Delegate tasks to sub-agents in multi-agent setups._ - ## Overview The `transfer_task` tool allows an agent to delegate tasks to specialized sub-agents and receive their results. This is the core mechanism for multi-agent orchestration. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/user-prompt/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/user-prompt/index.md index 739892c93750..2d6dc10cd4d2 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/user-prompt/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/user-prompt/index.md @@ -7,11 +7,9 @@ weight: 190 canonical: https://docs.docker.com/ai/docker-agent/tools/user-prompt/ --- -_Ask the user questions and collect interactive input during agent execution._ - ## Overview -The user prompt tool allows agents to ask questions and collect input from users during execution. This enables interactive workflows where the agent needs clarification, confirmation, or additional information before proceeding. +The user prompt tool allows agents to ask questions and collect input from users during execution. > [!NOTE] > **When to Use** @@ -163,8 +161,8 @@ Agent: Deploying to staging... How the prompt appears depends on the interface: -- **TUI**: Displays an interactive dialog with appropriate input controls -- **CLI (exec mode)**: Prints the prompt and reads from stdin +- **TUI**: Displays an interactive dialog with appropriate input controls. The lean TUI shows the same form inline in place of the editor +- **CLI (exec mode)**: Automatically declines form prompts; the agent must handle the decline without reading an answer from stdin - **API/MCP**: Returns an elicitation request to the client > [!TIP] @@ -183,4 +181,4 @@ The agent should handle all possible actions: > [!WARNING] > **Context Requirement** > -> The user prompt tool requires an elicitation handler to be configured. It works in the TUI and CLI modes but may not be available in all contexts (e.g., some MCP client configurations). +> The user prompt tool requires an elicitation handler. The full and lean TUIs support interactive form prompts; API/MCP clients must implement elicitation. Exec mode declines form prompts automatically. Interactive OAuth authorization in exec mode is a separate flow, not support for `user_prompt` forms. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/webhook/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/webhook/index.md index ded710754192..1dcb9df46c47 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/webhook/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/webhook/index.md @@ -7,8 +7,6 @@ weight: 145 canonical: https://docs.docker.com/ai/docker-agent/tools/webhook/ --- -_Reliable outbound notifications to Slack, Discord, Telegram, IFTTT, and more._ - ## Overview The webhook toolset delivers a notification to a destination **you configure**. The diff --git a/_vendor/modules.txt b/_vendor/modules.txt index ed8d29965135..7d5c4c243b05 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -2,7 +2,7 @@ # github.com/moby/moby/v2 v2.0.0-beta.31 # github.com/moby/buildkit v0.35.1 # github.com/docker/buildx v0.39.1 -# github.com/docker/cli v29.9.3+incompatible +# github.com/docker/cli v29.10.0+incompatible # github.com/docker/compose/v5 v5.7.1 # github.com/docker/model-runner v1.1.36 -# github.com/docker/docker-agent v1.152.0 +# github.com/docker/docker-agent v1.163.0 diff --git a/go.mod b/go.mod index eb4f989fe2b2..2e20d6546d0d 100644 --- a/go.mod +++ b/go.mod @@ -1,6 +1,6 @@ module github.com/docker/docs -go 1.27 +go 1.27.4 // This go.mod file is used by hugo to vendor documentation from upstream // repositories. Use the "require" section to specify the version of the @@ -9,9 +9,9 @@ go 1.27 // Make sure to add an entry in the "tools" section when adding a new repository. require ( github.com/docker/buildx v0.39.1 - github.com/docker/cli v29.9.3+incompatible + github.com/docker/cli v29.10.0+incompatible github.com/docker/compose/v5 v5.7.1 - github.com/docker/docker-agent v1.152.0 + github.com/docker/docker-agent v1.163.0 github.com/docker/model-runner v1.1.36 github.com/moby/buildkit v0.35.1 github.com/moby/moby/api v1.57.0 diff --git a/go.sum b/go.sum index d7c5d2c9bb25..c0f6baa944b5 100644 --- a/go.sum +++ b/go.sum @@ -150,6 +150,8 @@ github.com/docker/cli v29.9.2+incompatible h1:trup/vUxx5uUo2t+87Cd9AmITR+DvKUe4H github.com/docker/cli v29.9.2+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= github.com/docker/cli v29.9.3+incompatible h1:SBaMp7ecohadEHMDrUJg22t9I3awqsAVhnJ7GOcWpfE= github.com/docker/cli v29.9.3+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= +github.com/docker/cli v29.10.0+incompatible h1:lCL+clBUJnHsmjBCr6TwvfQFkmBidPxi5SkuXCoYxc0= +github.com/docker/cli v29.10.0+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8= github.com/docker/compose/v5 v5.0.0 h1:J2uMCzJ/5xLcoIVVXvMmPe6HBzVQpmJThKa7Qk7Xldc= github.com/docker/compose/v5 v5.0.0/go.mod h1:BurapGv8zmYnsbSmlpCz5EU2Pi3YFV/PjeUnoFpcw64= github.com/docker/compose/v5 v5.0.1 h1:5yCjDJbwUqcuI+6WNFHNWz2/3vyBDsNnfe8LlFjyxEc= @@ -200,6 +202,8 @@ github.com/docker/docker-agent v1.126.0 h1:GjX84SHcvS4Txo7dGjatWhKGFLNpDqKcGAoIs github.com/docker/docker-agent v1.126.0/go.mod h1:K38q6CsnSTHDOrLP46HLGhKwv3i+vjmu33cjmjpkAvg= github.com/docker/docker-agent v1.152.0 h1:inDwSlc963dTjThWXydrbxu4ehz/Yqmh3vd1+8hBhts= github.com/docker/docker-agent v1.152.0/go.mod h1:ZGCPdL/EinADY1IMcLoWXEsAjsDhciRw59ba96xI2FQ= +github.com/docker/docker-agent v1.163.0 h1:tLXZ7N0Wd1tV9bB0qAqltIDhnXkQPeoukQaIyd8euxU= +github.com/docker/docker-agent v1.163.0/go.mod h1:ktzAFv9Rp6evBhnDzNBNtOTuAfQHmzaqH6hahmm1wIQ= 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=