From 49d4c288ee83f80ea9b3168698c4a99020e54700 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sun, 19 Jul 2026 03:45:54 +0000 Subject: [PATCH] docker-agent: sync docs with docker-agent v1.111.0 --- .../docs/concepts/agents/index.md | 4 +- .../docs/configuration/agents/index.md | 35 ++- .../docs/configuration/commands/index.md | 218 ++++++++++++++++++ .../docs/configuration/models/index.md | 18 +- .../docs/configuration/sandbox/index.md | 85 ++++++- .../docs/configuration/tools/index.md | 1 + .../docs/configuration/user-settings/index.md | 127 ++++++++++ .../docs/features/api-server/index.md | 15 +- .../docker-agent/docs/features/cli/index.md | 4 +- .../docker-agent/docs/features/tui/index.md | 15 +- .../docs/guides/compaction/index.md | 147 ++++++++++++ .../docker-agent/docs/guides/tips/index.md | 2 +- .../docs/providers/custom/index.md | 6 + .../docs/providers/mistral/index.md | 2 +- .../docs/tools/scheduler/index.md | 96 ++++++++ _vendor/modules.txt | 2 +- go.mod | 2 +- go.sum | 2 + 18 files changed, 749 insertions(+), 32 deletions(-) create mode 100644 _vendor/github.com/docker/docker-agent/docs/configuration/commands/index.md create mode 100644 _vendor/github.com/docker/docker-agent/docs/configuration/user-settings/index.md create mode 100644 _vendor/github.com/docker/docker-agent/docs/guides/compaction/index.md create mode 100644 _vendor/github.com/docker/docker-agent/docs/tools/scheduler/index.md 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 4d87c853a4c5..4724133a2689 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 @@ -97,10 +97,10 @@ Commands support environment variable interpolation using JavaScript template li ## Default Agent -Running `docker agent run` without a config file uses a built-in default agent. This is a capable general-purpose agent for quick tasks without needing any configuration. +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. ```bash -# Use the default agent +# Use the project config or built-in default agent $ docker agent run # Override the default with an alias 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 631c5d516b43..7812438c3359 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 @@ -102,8 +102,8 @@ agents: | `max_old_tool_call_tokens` | int | ✗ | Maximum number of tokens to keep from old tool call arguments and results. Older tool calls beyond this budget have their content replaced with a placeholder, saving context space. Tokens are approximated as `len/4`. Truncation is disabled by default; set a positive value to enable it. Set to `-1` to disable truncation (unlimited). | | `max_tool_result_tokens` | int | ✗ | Maximum number of tokens to keep from each tool result when it is added to the session. Oversized results are truncated middle-out: the head and tail are kept and the removed middle is replaced with a truncation marker. Textual documents attached to the result share the same budget. Tokens are approximated as `len/4`. The cap is disabled by default; set a positive value to enable it. `0` and `-1` both leave tool results unbounded. | | `num_history_items` | int | ✗ | Limit the number of conversation history messages sent to the model. Useful for managing context window size with long conversations. Default: unlimited (all messages sent). | -| `session_compaction` | boolean | ✗ | When `false`, disables automatic session compaction for this agent: neither the proactive threshold trigger nor the post-overflow auto-recovery runs. The manual `/compact` command remains available. Default: `true`. | -| `compaction_threshold` | float | ✗ | Fraction of the model's context window at which proactive auto-compaction triggers. Must be greater than `0` and at most `1`. A `compaction_threshold` set on the agent's model takes precedence. Default: `0.9`. See [Compaction Threshold](../models/index.md#delegating-session-compaction). | +| `session_compaction` | boolean | ✗ | When `false`, disables automatic session compaction for this agent: neither the proactive threshold trigger nor the post-overflow auto-recovery runs. The manual `/compact` command remains available. Default: `true`. See the [Context & Compaction guide](../../guides/compaction/index.md). | +| `compaction_threshold` | float | ✗ | Fraction of the model's context window at which proactive auto-compaction triggers. Must be greater than `0` and at most `1`. A `compaction_threshold` set on the agent's model takes precedence. Default: `0.9`. See the [Context & Compaction guide](../../guides/compaction/index.md). | | `skills` | bool/array | ✗ | Enable automatic skill discovery. `true` loads all discovered local skills, `false` disables them. A list can mix skill sources (`local` or `https://…` URLs) and skill names to include — see [Skills](../../features/skills/index.md). | | `commands` | object | ✗ | Named prompts that can be run with `docker agent run config.yaml /command_name`. Can be simple strings or objects with `instruction` and/or `agent` fields for agent switching, or a `url` field to open a link in the browser (TUI only). See [Named Commands](#named-commands) below. | | `use_commands` | list of string | ✗ | Names of top-level `commands` groups to merge into this agent. Inline `commands` entries take precedence on name conflicts. Default: `[]`. | @@ -123,6 +123,11 @@ agents: > > Default is `0` (unlimited). Always set `max_iterations` for agents with powerful tools like `shell` to prevent infinite loops. A value of 20–50 is typical for development agents. +> [!TIP] +> **Managing long sessions** +> +> `max_old_tool_call_tokens`, `max_tool_result_tokens`, `num_history_items`, `session_compaction`, and `compaction_threshold` all help keep long-running sessions inside the model's context window. See the [Context & Compaction guide](../../guides/compaction/index.md) for how to combine them. + ## External Instruction Files Long system prompts can be kept in their own files instead of being inlined in @@ -322,6 +327,11 @@ agents: ## Named Commands +> [!TIP] +> **Full reference** +> +> This section covers the basics. For URL commands, agent-switching commands, reusable top-level `commands:` groups, and hiding commands with `--disable-commands`, see [Custom Commands](../commands/index.md). + Define reusable prompt shortcuts that can send prompts to the current agent, switch to a different sub-agent, or open a URL in the browser: > **Note:** Named slash commands execute immediately, even while the agent is processing another message. Unlike regular chat messages (which are queued), slash commands interrupt or direct the agent even while it is mid-response. @@ -339,8 +349,8 @@ agents: # Advanced format with agent switching plan: - agent: planner # Switch to the 'planner' sub-agent - instruction: "Create a detailed plan for: $1" # Optional: send this prompt after switching + agent: planner # Switch to the 'planner' agent + instruction: "Create a detailed plan for: ${args.join(\" \")}" # Optional: send this prompt after switching # Agent switching without instruction - forwards remaining text as prompt review: @@ -366,8 +376,8 @@ Commands support three formats: ```yaml plan: - agent: planner # Required: name of sub-agent to switch to - instruction: "Plan: $1" # Optional: prompt to send after switching + agent: planner # Required: name of any agent defined in the team + instruction: "Plan: ${args.join(\" \")}" # Optional: prompt to send after switching description: "Switch to planning mode" # Optional: shown in help text ``` @@ -379,7 +389,16 @@ Commands support three formats: description: "Open the documentation" # Optional: shown in help text ``` -When `agent` is set without `instruction`, any text typed after the slash command (e.g., `/plan build a web app`) is forwarded as a prompt to the target agent. The target agent must be listed in the current agent's `sub_agents` array. +When `agent` is set without `instruction`, any text typed after the slash command (e.g., `/plan build a web app`) is forwarded as a prompt to the target agent. The target agent can be **any agent defined in the team configuration** — it does not need to be listed in the current agent's `sub_agents` array. + +**Argument and expansion syntax** + +An `instruction` string can reference the command's arguments and expand tool calls: + +- `${args[0]}`, `${args[1]}`, … — individual positional arguments, in the order the user typed them after the command +- `${args.join(" ")}` — all arguments joined into a single string +- `${tool_name({...})}` — calls a tool and inlines its return value (any tool available to the agent) +- `!tool_name(key=value)` — legacy tool-call form: calls a tool with plain `key=value` arguments and inlines its output ### Agent-Switching Commands @@ -396,7 +415,7 @@ agents: # Switch to planner with a pre-filled prompt plan: agent: planner - instruction: "Create a detailed plan for: $1" + instruction: "Create a detailed plan for: ${args.join(\" \")}" # Switch to reviewer; any text after /review is forwarded review: agent: reviewer diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/commands/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/commands/index.md new file mode 100644 index 000000000000..51eeea3c68c2 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/commands/index.md @@ -0,0 +1,218 @@ +--- +title: "Custom Commands" +description: "Define slash commands that send prompts, open URLs, or switch agents, and reuse them across agents with top-level command groups." +keywords: docker agent, ai agents, configuration, yaml, custom commands, slash commands +linkTitle: "Custom Commands" +weight: 55 +canonical: https://docs.docker.com/ai/docker-agent/configuration/commands/ +--- + +_Define slash commands that send prompts, open URLs, or switch agents._ + +## What Slash Commands Are + +A slash command is a named shortcut a user types in the TUI (`/df`, `/deploy`, `/plan`) or on the CLI (`docker agent run agent.yaml /df`) instead of typing out a full prompt. Every agent can declare its own commands under `commands:`, and top-level `commands:` groups let multiple agents share the same set without duplicating them. + +Unlike regular chat messages — which are queued while the agent is busy — slash commands (both built-in and named) execute immediately, even mid-response. + +Commands come in three shapes: + +| Shape | What it does | +| --- | --- | +| [Prompt command](#prompt-commands) | Sends a prompt to the current agent | +| [URL command](#url-commands) | Opens a link in the user's browser (full TUI only) | +| [Agent-switching command](#agent-switching-commands) | Switches the active agent, optionally with a prompt (full TUI and CLI) | + +> [!IMPORTANT] +> **Behavior differs by frontend** +> +> `url` and `agent` are only fully honored in the **full TUI**, which checks `url` before `agent` (a URL command opens the browser and stops there; an agent-switching command switches before sending any instruction). The **lean TUI** doesn't special-case either field — it only resolves a command's expanded text and sends it as a chat message, so a URL-only command silently sends whatever trailing text followed the slash (often nothing, opening no browser) and an agent-switching command sends its instruction to the *current* agent instead of the target. The **CLI** (`docker agent run agent.yaml /command`) switches agents like the full TUI, but has no browser to open, so `url` has no effect there. + +## Prompt Commands + +The simplest form: a string value that becomes the instruction sent to the current agent. + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: A system administrator assistant. + instruction: You are a system administrator. + commands: + df: "Check how much free space I have on my disk" + logs: "Show me the last 50 lines of system logs" + greet: "Say hello to ${env.USER}" +``` + +For more control, use the object form with an `instruction:` field, plus an optional `description:` shown in completion dialogs and help text: + +```yaml +commands: + deploy: + description: "Deploy the application to staging" + instruction: "Deploy ${env.PROJECT_NAME || 'app'} to ${env.ENV || 'staging'}" +``` + +Commands support JavaScript template literal syntax (`${env.VAR}`) for environment variable interpolation, with optional `||` defaults and ternary expressions — the same syntax as agent `instruction` and `description`. Undefined variables expand to the empty string. See [Variable Expansion in Config Fields](../overview/index.md#variable-expansion-in-config-fields) for the full picture. + +Prompt commands can also reference the text typed after the slash and call tools, using the same `${...}` expansion engine as `${env.VAR}`: + +- `${args[0]}`, `${args[1]}`, … — individual positional arguments (whitespace-tokenized; quoted substrings keep their spaces together). +- `${args}` or `${args.join(" ")}` — the full argument list. +- `${tool_name({key: value, ...})}` — calls an agent tool and inlines its output. JS expressions are evaluated before tool commands, so tool output is never itself re-evaluated as JS. +- `` !tool_name(key=value) `` — legacy bang syntax for the same tool-call inlining; still supported alongside `${tool_name({...})}`. + +If `instruction` uses none of the `${args...}` placeholders, any text typed after the slash is appended to the resolved instruction automatically. + +```yaml +commands: + fix: + description: "Fix a file, with optional extra options" + instruction: "Fix the file ${args[0]} with options ${args[1]}" + run: + description: "Run a command with all the typed arguments" + instruction: 'Run command with args: ${args.join(" ")}' + lint: + description: "Show the current lint output" + instruction: 'Lint: ${shell({cmd: "task lint"})}' +``` + +```bash +# Run commands from the CLI too +$ docker agent run agent.yaml /df +$ docker agent run agent.yaml /greet +$ docker agent run agent.yaml /fix main.go --verbose +$ PROJECT_NAME=myapp ENV=production docker agent run agent.yaml /deploy +``` + +## URL Commands + +A command with a `url` field opens that URL in the user's default browser instead of sending a prompt to the agent. Any URI scheme the OS knows how to dispatch works — standard web URLs and custom schemes such as `docker-desktop://` for deep links. + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: An agent with handy URL shortcuts. + instruction: You are a helpful assistant. + commands: + feedback: + description: "Open the feedback site for this session" + url: https://example.com/feedback?session={{session_id}} + docs: + description: "Open the documentation" + url: https://docs.docker.com/ + desktop: + description: "Open this session in Docker Desktop" + url: docker-desktop://dashboard/session/{{session_id}} +``` + +The `{{session_id}}` token is replaced at invocation time with the current session ID (URL-query-escaped so it can't break the URL or inject extra query parameters), letting a command deep-link to something scoped to the conversation. This token deliberately uses `{{...}}` rather than the `${...}` JS-expansion syntax, since the session ID is only known at dispatch time. + +URLs are validated before being handed to the OS opener: a parseable URL with a non-empty scheme is required, and flag-like inputs (those starting with `-`) are rejected to prevent argument injection. + +> [!NOTE] +> **Full TUI only** +> +> URL commands only open a browser in the full TUI. The CLI and lean TUI don't check the `url` field at all, so `docker agent run agent.yaml /docs` never opens a browser there — but the command is still dispatched: its resolved text (usually empty, for a URL-only command) is sent as a prompt and can trigger a model turn. + +See [`examples/url_commands.yaml`](https://github.com/docker/docker-agent/blob/main/examples/url_commands.yaml) for a complete example. + +## Agent-Switching Commands + +A command with an `agent` field switches the active agent for the rest of the conversation. This is useful for building workflow shortcuts where `/plan`, `/review`, `/deploy` each route the user to the right specialist. + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Main assistant + instruction: You are a project coordinator. + sub_agents: [planner, reviewer] + commands: + # Switch to planner with a pre-filled prompt + plan: + agent: planner + instruction: "Create a detailed plan for: ${args.join(' ')}" + # Switch to reviewer; any text after /review is forwarded + review: + agent: reviewer + + planner: + model: anthropic/claude-sonnet-4-5 + description: Planning specialist + instruction: You create detailed project plans. + + reviewer: + model: anthropic/claude-sonnet-4-5 + description: Code review specialist + instruction: You review code and suggest improvements. +``` + +When `agent` is set **without** `instruction`, any text typed after the slash command (e.g. `/review fix the auth bug`) is forwarded as a prompt to the target agent. When both are set, the agent is switched first, then the instruction is sent to the new agent. Either way, the target can be **any agent defined in the team**, not just one of the current agent's own `sub_agents` — `sub_agents` above is shown because `planner` and `reviewer` also happen to be delegation targets, not because `agent:` requires it. + +Agent switching stays in the same session — the target agent sees the full conversation history, and the user must explicitly switch back (there's no automatic return). This is different from the two other ways agents hand off work: + +| | Agent-switching command | `handoff` tool | `transfer_task` | +| --- | --- | --- | --- | +| **Trigger** | User runs `/command` | Model calls `handoff()` | Model calls `transfer_task()` | +| **Session** | Stays in the same session | Stays in the same session | Launches an isolated sub-session | +| **History** | Target agent sees full conversation | Target agent sees full conversation | Child runs in isolation; only the result returns | +| **Control** | User must explicitly switch back | Target agent can chain to another agent | Root agent stays in control | + +Use `transfer_task` (via `sub_agents`) when you want delegation with a clean result; use agent-switching commands when you want to *become* a different agent for the rest of the conversation. + +See [`examples/agent_switching_commands.yaml`](https://github.com/docker/docker-agent/blob/main/examples/agent_switching_commands.yaml) for a complete example. + +## Reusable Command Groups + +Repeated command sets across agents can be hoisted into the top-level `commands:` section and pulled in by name with `use_commands:` — the same reuse pattern as `mcps:` for MCP servers and `toolsets:` for shared toolsets. + +```yaml +commands: + ci: + deploy: "Deploy the application" + test: "Run the test suite" + +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: Lead developer + instruction: You are the lead developer. Coordinate the team. + use_commands: [ci] # reuse the "ci" command group + commands: + lint: "Run the linter" # inline command, merged in (wins on conflict) + + docs-writer: + model: anthropic/claude-sonnet-4-5 + description: Documentation writer + instruction: You write and maintain the project documentation. + use_commands: [ci] # same group, reused without duplication +``` + +An agent's own inline `commands:` entries take precedence over merged `use_commands:` entries on name conflicts. See [`examples/shared-commands-skills.yaml`](https://github.com/docker/docker-agent/blob/main/examples/shared-commands-skills.yaml) for a complete example that also covers the equivalent `skills:` / `use_skills:` pattern. + +## Hiding Commands + +Use `--disable-commands` to hide and disable specific slash commands in the TUI — built-in ones (`/cost`, `/eval`, `/model`, …) or your own named ones. Accepts a comma-separated list; the leading slash is optional and matching is case-insensitive. + +```bash +$ docker agent run agent.yaml --disable-commands="/cost,/eval,/model" +``` + +This is useful for shipping a distributed agent with a narrower command surface — for example, hiding `/model` so a published agent always runs its intended model. + +## Built-in Commands + +The TUI ships its own slash commands (`/new`, `/compact`, `/sessions`, `/settings`, …) alongside whatever an agent defines. See [Slash Commands](../../features/tui/index.md#slash-commands) in the TUI reference for the full list. + +## Command Configuration Reference + +| Property | Type | Description | +| --- | --- | --- | +| `description` | string | Shown in completion dialogs and help text. | +| `instruction` | string | The prompt sent to the agent. Supports argument expansion (`${args[0]}`, `${args.join(" ")}`, …), tool calls (`${tool_name({...})}`), and the legacy bang syntax `!tool_name(...)`. | +| `agent` | string | Name of an agent in the team to switch to when this command is invoked — any agent in the team's `agents:` map, not just one of the current agent's `sub_agents`. When set without `instruction`, any text typed after the slash command is forwarded as a prompt to the target agent. | +| `url` | string | URL to open in the user's default browser when this command is invoked, instead of sending a prompt to the agent (full TUI only — see [URL Commands](#url-commands)). The token `{{session_id}}` is replaced at invocation time with the current session ID (URL-query-escaped). | + +`instruction` and `agent` can be combined (the agent is switched first, then the instruction is sent to the new agent). In the full TUI, if `url` is set, it takes precedence over `agent` and `instruction` — the command only opens the browser; the lean TUI and CLI don't check `url` at all, so a URL-only command instead sends its (usually empty) resolved text as a prompt. See [Behavior differs by frontend](#what-slash-commands-are) above. The simple string form is shorthand for `{ instruction: "..." }`. 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 b9865886af42..afcc82e9c5ff 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 @@ -47,7 +47,7 @@ models: title_model: string # Optional: model used for session-title generation compaction_model: string # Optional: model used for session-compaction (summary generation) compaction_threshold: float # Optional: context-window fraction that triggers auto-compaction (0–1, default: 0.9) - bypass_models_gateway: boolean # Optional: skip the models gateway for this model + bypass_models_gateway: boolean # Optional: skip the models gateway for this model (implied by a custom base_url) ``` ## Properties Reference @@ -73,9 +73,9 @@ models: | `cost` | object | ✗ | Explicit token pricing in USD per 1M tokens, overriding the built-in catalogue. See [Custom Token Pricing](#custom-token-pricing). | | `provider_opts` | object | ✗ | Provider-specific options (see provider pages) | | `title_model` | string | ✗ | Model used for session-title generation. Can be a named model from the `models:` section or an inline `provider/model` string. When omitted, the agent's primary model generates titles. Cannot be combined with `first_available`. | -| `compaction_model` | string | ✗ | Model used for session compaction (summary generation). Can be a named model or an inline `provider/model` string. When omitted, the primary model compacts. Cannot be combined with `first_available`. See [Delegating Session Compaction](#delegating-session-compaction). | -| `compaction_threshold` | float | ✗ | Fraction of the context window at which proactive auto-compaction triggers for agents running this model. Must be greater than `0` and at most `1`. Takes precedence over the agent-level `compaction_threshold`. Cannot be combined with `first_available`. Default: `0.9`. | -| `bypass_models_gateway` | boolean | ✗ | When `true`, this model connects directly to its provider even when a models gateway (`--models-gateway` / `CAGENT_MODELS_GATEWAY`) is configured. See [Gateway Bypass](#gateway-bypass). | +| `compaction_model` | string | ✗ | Model used for session compaction (summary generation). Can be a named model or an inline `provider/model` string. When omitted, the primary model compacts. Cannot be combined with `first_available`. See the [Context & Compaction guide](../../guides/compaction/index.md). | +| `compaction_threshold` | float | ✗ | Fraction of the context window at which proactive auto-compaction triggers for agents running this model. Must be greater than `0` and at most `1`. Takes precedence over the agent-level `compaction_threshold`. Cannot be combined with `first_available`. Default: `0.9`. See the [Context & Compaction guide](../../guides/compaction/index.md). | +| `bypass_models_gateway` | boolean | ✗ | When `true`, this model connects directly to its provider even when a models gateway (`--models-gateway` / `CAGENT_MODELS_GATEWAY`) is configured. Implied by a custom `base_url`. See [Gateway Bypass](#gateway-bypass). | ## Attachment Capability Overrides @@ -185,6 +185,11 @@ titles. ## Delegating Session Compaction +> [!TIP] +> **Full guide** +> +> For a task-oriented walkthrough of automatic vs. on-demand compaction, trimming tool results, and reading the context gauge, see [Managing Context & Compaction](../../guides/compaction/index.md). This section covers the `compaction_model` and `compaction_threshold` fields themselves. + The `compaction_model` field lets a heavyweight primary model hand off the expensive compaction (summary generation) call to a smaller, faster model: @@ -238,8 +243,9 @@ for complete examples. ## Gateway Bypass When a models gateway (`--models-gateway` / `CAGENT_MODELS_GATEWAY`) is configured, -all models route through it by default. Set `bypass_models_gateway: true` on a -specific model to make it connect directly to its provider instead: +models without a custom `base_url` route through it by default. Set +`bypass_models_gateway: true` on a specific model to make it connect directly +to its provider instead: ```yaml models: 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 3e1bca42691c..a7c9c2ed7074 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 @@ -34,7 +34,7 @@ docker-agent launches a sandbox VM, copies itself into it, mounts the current wo | Flag | Default | Description | | ------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `--sandbox` | `false` | Enable sandbox mode. | -| `--template` | `docker/sandbox-templates:docker-agent` | OCI image used as the sandbox template. Passed to `docker sandbox create -t` / `sbx create -t`. | +| `--template` | `docker/sandbox-templates:docker-agent` | OCI image used as the sandbox template. Passed to `docker sandbox create -t` / `sbx create -t`. See [Sandbox templates](#sandbox-templates). | | `--sbx` | `true` | Prefer the `sbx` CLI backend when it is available. Set `--sbx=false` to always use `docker sandbox`. | | `--no-kit` | `false` | Disable the [auto-kit](#auto-kit) — do not stage skills or prompt files into the sandbox. | @@ -139,6 +139,78 @@ pointing at this command so you can turn the missing host into a one-line, persistent fix instead of relying on the wider conservative fallback host set. +## Sandbox templates + +A sandbox template is the OCI image the sandbox VM boots from. It determines +the base OS and the tools available inside the VM, including whether the +`docker-agent` binary is already there. `--template` (or `-t` on `sbx +create` / `docker sandbox create`) selects it. + +### The default template + +`--template` defaults to `docker/sandbox-templates:docker-agent`, the +official Docker Agent sandbox template, maintained by the Docker Sandboxes +team. See [What the default template includes](#what-the-default-template-includes) +for details. + +> [!NOTE] +> There's currently no automated process that syncs this repository's own +> template improvements into `docker/sandbox-templates:docker-agent`. Such a +> process may land later, but until then this image can lag behind the +> latest Docker Agent template build. + +### The repo-published templates + +This repository's own CI also builds and publishes a sandbox template — from +the `template` stage of the +[`Dockerfile`](https://github.com/docker/docker-agent/blob/main/Dockerfile) — +as `docker/docker-agent-sbx-templates`. It's the way to get the freshest +Docker Agent–flavored template: + +| Tag | Built from | Use it when | +| --------- | ------------------------------ | ------------------------------------------------------------------- | +| `:latest` | The most recent `v*` release | You want the newest Docker Agent template with release stability. | +| `:edge` | The current `main` branch | You want today's `main` build and can tolerate lower stability. | + +(Each release also publishes a matching version-pinned tag, e.g. +`docker/docker-agent-sbx-templates:1.2.3`.) + +Use `:latest` for normal use. Reach for `:edge` only when you specifically +need an unreleased fix or feature and can tolerate the occasional breakage. +For reproducible runs, pin to a digest instead of a tag, e.g. +`docker/docker-agent-sbx-templates@sha256:...`. + +Select one with `--template`: + +```bash +$ docker agent run --sandbox --template docker/docker-agent-sbx-templates:latest agent.yaml +``` + +Or point the [`sbx`](https://docs.docker.com/ai/sandboxes/) CLI at it +directly, without going through Docker Agent: + +```bash +$ sbx create -t docker/docker-agent-sbx-templates:latest +``` + +> [!TIP] +> The upstream [Docker Sandboxes documentation](https://docs.docker.com/ai/sandboxes/) +> covers the full `sbx` / `docker sandbox` CLI reference, independent of +> Docker Agent. + +### What they contain + +The `template` stage in this repository's +[`Dockerfile`](https://github.com/docker/docker-agent/blob/main/Dockerfile) +layers onto `docker/sandbox-templates:shell-docker` and adds: + +- The `docker-agent` binary. +- `vim` and `tmux`, for interactive debugging inside the VM. +- The **`docker-mcp`** Docker CLI plugin, installed at `~/.docker/cli-plugins/docker-mcp`. + +The image carries the label `com.docker.sandboxes.flavor=docker-agent-docker` +so sandbox tooling can identify it. + ## Example ```yaml @@ -168,9 +240,16 @@ docker agent run --sandbox agent.yaml ### What the default template includes -The default template (`docker/sandbox-templates:docker-agent`) ships with: +The default template (`docker/sandbox-templates:docker-agent`) is a +separate image maintained by the Docker Sandboxes team. This repository +does not control its base image or contents, so no claim is made here +about what it ships with beyond being the image `docker agent run +--sandbox` uses whenever `--template` is not overridden (see +[Flags](#flags) for the exact default). -- **`docker-mcp`** CLI plugin — installed at `~/.docker/cli-plugins/docker-mcp`, available out of the box so agents can invoke `docker mcp` commands inside the sandbox without any additional setup. +For a template whose base image and contents are verified against this +repository's own build — including the `docker-mcp` CLI plugin — see +[the repo-published templates](#sandbox-templates). ## Auto-Kit 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 773df257bf55..c84f65b0ba2f 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/tools/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/tools/index.md @@ -20,6 +20,7 @@ Built-in tools are included with docker-agent and require no external dependenci | `filesystem` | Read, write, list, search, navigate | [Filesystem](../../tools/filesystem/index.md) | | `shell` | Execute shell commands synchronously | [Shell](../../tools/shell/index.md) | | `background_jobs` | Run and manage long-running shell commands | [Background Jobs](../../tools/background-jobs/index.md) | +| `scheduler` | Schedule instructions to run at a time or on a recurring interval | [Scheduler](../../tools/scheduler/index.md) | | `think` | Reasoning scratchpad | [Think](../../tools/think/index.md) | | `plan` | Shared persistent scratchpad for multi-agent collaboration | [Plan](../../tools/plan/index.md) | | `session_plan` | Per-session markdown plan for the draft-review-execute workflow | [Session Plan](../../tools/session_plan/index.md) | 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 new file mode 100644 index 000000000000..a5a98ddd4c7a --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/user-settings/index.md @@ -0,0 +1,127 @@ +--- +title: "User Settings" +description: "Full reference for the global settings block in ~/.config/cagent/config.yaml: theme, layout, YOLO, sound, snapshots, permissions, hooks, keybindings, and how they interact with agent config and CLI flags." +keywords: docker agent, ai agents, configuration, yaml, user settings, user config +linkTitle: "User Settings" +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: + +```text +~/.config/cagent/config.yaml +``` + +The `settings:` block inside it holds preferences that apply to every agent you run — appearance, behavior, notifications, and a few global safety defaults. Everything under `settings:` is optional; an unset field falls back to the documented default. + +```yaml +# ~/.config/cagent/config.yaml +settings: + theme: dracula + lean: false + sound: true +``` + +You rarely need to hand-edit this file. Most fields are managed from the TUI's `/settings` dialog (**Appearance**, **Behavior**, **Notifications** tabs) — press Enter there to apply and persist a change. A few fields (`permissions`, `hooks`, `keybindings`) have no dialog UI and are only set by editing the file directly. + +> [!NOTE] +> This page documents `settings:`. The user config file also has top-level sections outside `settings:` — `aliases:`, `providers:`, `board:`, `credential_helper:`, `sandbox_allowlist:` — which are not covered here. + +## Settings Reference + +| Setting | Type | Default | Description | +| --- | --- | --- | --- | +| `hide_tool_results` | boolean | `false` | Hide tool call results in the TUI by default. Mirrors the `--hide-tool-results` flag and the Ctrl+O toggle. | +| `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. | +| `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. | +| `YOLO` | boolean | `false` | Auto-approve all tool calls globally, across every agent you run. Mirrors the `--yolo` flag and the `/yolo` command. | +| `lean` | boolean | `false` | Make the [lean TUI](../../features/tui/index.md#lean-tui) (simplified, minimal-chrome interface) the default for interactive runs instead of the full TUI. | +| `tab_title_max_length` | int | `20` | Maximum display length for tab titles; longer titles are truncated with an ellipsis. | +| `restore_tabs` | boolean | `false` | Restore previously open tabs when launching the TUI. | +| `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). | +| `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. | +| `permissions` | object | _unset_ | Global tool-permission rules (`allow` / `ask` / `deny`), merged with agent-level and session-level permissions. See [Permissions](../permissions/index.md#global-permissions). | +| `hooks` | object | _unset_ | Global lifecycle hooks applied to every agent, additive with agent-config and CLI hooks. See [Global (user-level) hooks](../hooks/index.md#global-user-level-hooks). | +| `keybindings` | array | _unset_ | Remap TUI keyboard shortcuts. See [Custom Keybindings](../../features/tui/index.md#custom-keybindings) for the full list of actions and syntax. | +| `layout` | object | _unset_ | Sidebar position and section visibility. See [Layout Settings](#layout-settings) below. | + +## Layout Settings + +`layout` customizes the TUI's sidebar. The zero value (an omitted `layout:` block, or any field left out) is the default: sidebar on the right, every section visible, normal spacing. + +| Field | Type | Default | Description | +| --- | --- | --- | --- | +| `sidebar_position` | string | `right` | `right`, `left`, `top`, or `bottom`. Left/right keep a full vertical sidebar; top/bottom render a compact horizontal band. | +| `section_spacing` | string | `normal` | `compact`, `normal`, or `relaxed` — the number of blank lines between sidebar sections. | +| `hide_session_path` | boolean | `false` | Hide the working-directory (session path) line, including its git branch. | +| `hide_usage` | boolean | `false` | Hide the token-usage section. | +| `hide_agents` | boolean | `false` | Hide the Agents section. | +| `hide_tools` | boolean | `false` | Hide the Tools section. | +| `hide_todos` | boolean | `false` | Hide the Todos section. | + +```yaml +settings: + layout: + sidebar_position: left + section_spacing: compact + hide_usage: true +``` + +## Complete Example + +```yaml +# ~/.config/cagent/config.yaml +settings: + theme: auto + theme_dark: dracula + theme_light: default-light + lean: false + expand_thinking: false + split_diff_view: true + hide_tool_results: false + sound: true + sound_threshold: 10 + snapshot: true + cache_stable_prompts: true + warn_on_cache_miss: true + busy_send_mode: queue + restore_tabs: true + tab_title_max_length: 24 + layout: + sidebar_position: right + section_spacing: normal + permissions: + deny: + - "shell:cmd=sudo*" + allow: + - "read_*" + hooks: + session_start: + - type: command + command: "~/.config/cagent/hooks/session-start.sh" + keybindings: + - action: "commands" + keys: ["f2", "ctrl+k"] +``` + +## Precedence Rules + +User settings are the **lowest-priority** source: they establish defaults, and anything more specific wins. + +- **CLI flags over user settings — except plain boolean flags going from `true` to `false`.** Where a `docker agent run` flag mirrors a setting, passing the flag for a specific run takes precedence over the setting for that run only, and the flag never modifies the saved user config file. This holds cleanly for `--lean` / `lean` and `--theme` / `theme`, which track whether the flag was explicitly passed on the command line. `--yolo` / `YOLO` and `--hide-tool-results` / `hide_tool_results` don't: they're plain booleans with no "was this explicitly set" tracking, so passing `--yolo=false` or `--hide-tool-results=false` cannot turn a saved `YOLO: true` / `hide_tool_results: true` setting off for that run — the saved `true` wins and is reapplied on top of the flag. Passing the flag to turn either *on* (`--yolo`, `--hide-tool-results`) works as expected regardless of the saved setting. +- **Aliases sit between CLI flags and user settings.** An [alias](../../features/cli/index.md#docker-agent-alias) (`docker agent alias add ...`) can bundle its own `yolo`, `model`, `hide_tool_results`, and `sandbox` defaults; those apply when the corresponding flag was not explicitly passed, the same way user settings do, but are resolved after user settings so an alias's own choices take priority over your global defaults. +- **Permissions are merged, not overridden.** Global `settings.permissions` and an agent's own `permissions:` are combined into a single set of `deny` → `allow` → `ask` patterns before evaluation — a global deny always blocks, regardless of what the agent config allows. See [Merging Behavior](../permissions/index.md#merging-behavior). +- **Hooks are additive, not overridden.** For a given lifecycle event, hooks from the agent config, `settings.hooks`, `hooks.d/` drop-ins, and `--hook-*` CLI flags **all** run, in that order. Global hooks cannot be suppressed by an individual agent. +- **Everything else is a plain default.** Fields with no CLI or agent-config equivalent (`sound`, `sound_threshold`, `restore_tabs`, `tab_title_max_length`, `split_diff_view`, `cache_stable_prompts`, `warn_on_cache_miss`, `busy_send_mode`, `keybindings`, `layout`) only ever come from `settings:` (or the `/settings` dialog that writes it) — there is nothing to override them per run. 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 a7e452c74414..721f686db684 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 @@ -46,7 +46,7 @@ All endpoints are under the `/api` prefix. | `GET` | `/api/sessions/:id` | Get a session by ID (messages, tokens, permissions) | | `GET` | `/api/sessions/:id/status` | Lightweight runtime state (streaming, title, agent, tokens). Requires an attached runtime. | | `GET` | `/api/sessions/:id/snapshot` | Full state in one call (stored fields + runtime state + `last_event_seq`) for gapless resync — see [Reconnecting without gaps](#reconnecting-without-gaps). | -| `GET` | `/api/sessions/:id/events` | Live session event stream (SSE) with sequence numbers and replay. Available for a run attached via [`--listen`](#listen). | +| `GET` | `/api/sessions/:id/events` | Live session event stream (SSE) with sequence numbers and replay. Available for a run attached via [`--listen`](#listen), or once a session has raised at least one out-of-band event (e.g. a background job's elicitation, answered via `POST .../elicitation`), which creates a session-scoped event log on demand carrying such out-of-band events — see [Session event stream](#session-event-stream-and-reconnection) for what each kind of log contains. | | `DELETE` | `/api/sessions/:id` | Delete a session | | `PATCH` | `/api/sessions/:id/title` | Update session title | | `PATCH` | `/api/sessions/:id/permissions` | Update session permissions | @@ -55,7 +55,7 @@ All endpoints are under the `/api` prefix. | `PATCH` | `/api/sessions/:id/messages/:msg_id` | Update an existing message by ID. Returns `409 Conflict` while the session has an active run. | | `POST` | `/api/sessions/:id/resume` | Resume a paused session (after tool confirmation) | | `POST` | `/api/sessions/:id/tools/toggle` | Toggle auto-approve (YOLO) mode | -| `POST` | `/api/sessions/:id/elicitation` | Respond to an MCP tool elicitation request | +| `POST` | `/api/sessions/:id/elicitation` | Respond to an MCP tool elicitation request. Pass the `elicitation_id` from the `elicitation_request` event to target a specific concurrent request; omitted, it resolves the sole pending one. | | `POST` | `/api/sessions/:id/steer` | Inject messages into a running turn (pre-empts current) | | `POST` | `/api/sessions/:id/followup` | Enqueue messages to run after the current turn finishes (supports an `Idempotency-Key` — see [Idempotent follow-ups](#idempotent-follow-ups)). | | `GET` | `/api/sessions/:id/models` | List available models for the session's current agent | @@ -257,7 +257,16 @@ session's runtime events — `stream_started`, `agent_choice`, `tool_call`, per-request stream returned by the agent-execution endpoint, it is session-scoped and survives across turns, so a client can watch a session for its whole lifetime. It is available for a run attached via -[`--listen`](#listen). +[`--listen`](#listen), and — since a session-scoped event log is created on +demand the first time a session raises an out-of-band event, such as an +`elicitation_request` from a background job — for any API-created session +that has produced at least one (see the +[Sessions endpoint table](#sessions) above). The two kinds of log differ in +coverage: a `--listen` run feeds its full runtime event stream into the log, +while an on-demand log for an API-created session carries the session's +out-of-band events — not necessarily all ordinary turn events, which flow on +the per-request SSE stream of the [agent-execution](#agent-execution) +request that runs the turn. Each event carries a monotonic **sequence number** in the SSE `id:` field, and the server buffers recent events. This makes the stream resumable: 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 1105a3ec1fac..506839fa4224 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 @@ -13,7 +13,7 @@ _Complete reference for all docker-agent command-line commands and flags._ > [!TIP] > **No config needed** > -> Running `docker agent run` without a config file uses a built-in default agent. 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 a built-in default agent that is perfect for quick experimentation. ## Commands @@ -627,7 +627,7 @@ Commands that accept a config support multiple reference types: | OCI registry | `docker.io/username/agent:latest` | | Agent catalog | `agentcatalog/pirate` | | Alias | `pirate` (after `docker agent alias add`) | -| Default | (no argument) — uses built-in default agent | +| Default | (no argument) — uses project config or built-in default agent | > [!NOTE] > **Debugging** 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 510737cfbc5f..40884ad2e59a 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 @@ -55,7 +55,7 @@ settings: lean: true ``` -Omit `lean` or set it to `false` to keep the full TUI as the default. You can still use `--lean` for a single run, or `--lean=false` to use the full TUI when `settings.lean` is enabled. +Omit `lean` or set it to `false` to keep the full TUI as the default. You can still use `--lean` for a single run, or `--lean=false` to use the full TUI when `settings.lean` is enabled. See [User Settings](../../configuration/user-settings/index.md) for the full precedence rules between flags and user config. The lean TUI supports **steering**: messages submitted while the agent is running are queued and delivered to the active session. Pending steering messages appear with muted styling at the end of the live stream so you can see what will be sent next. @@ -97,6 +97,8 @@ Type `/` during a session to see available commands, or press Ctrl+Ctrl+H to view the complete list of all available ke ### Custom Keybindings -You can remap the shortcuts above by adding a `keybindings` list to the `settings` block of your `~/.config/cagent/config.yaml`. Each entry maps an action to one or more key combinations in [Bubbles key format](https://github.com/charmbracelet/bubbles) (for example `ctrl+q`, `alt+enter`, `f2`). Unlisted actions keep their defaults. +You can remap the shortcuts above by adding a `keybindings` list to the `settings` block of your `~/.config/cagent/config.yaml` (see [User Settings](../../configuration/user-settings/index.md#settings-reference) for the field reference). Each entry maps an action to one or more key combinations in [Bubbles key format](https://github.com/charmbracelet/bubbles) (for example `ctrl+q`, `alt+enter`, `f2`). Unlisted actions keep their defaults. This is the recommended way to replace the `Ctrl+J` newline fallback, which conflicts with common editor/terminal shortcuts (for example inside VS Code). @@ -376,6 +378,11 @@ Press Ctrl+R to enter incremental history search mode. Sta Run `/settings` to open the settings dialog. Use Tab to switch between **Appearance**, **Behavior**, and **Notifications**. +> [!TIP] +> **Full settings reference** +> +> 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 show a live schematic preview and apply immediately to the UI behind the dialog: - **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, usage, plus a one-line summary of the current agent, tools, and todos). @@ -474,7 +481,7 @@ markdown: ### Applying Themes -**In user config** (`~/.config/cagent/config.yaml`): +**In user config** (`~/.config/cagent/config.yaml`, see [User Settings](../../configuration/user-settings/index.md) for the full reference): ```yaml settings: 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 new file mode 100644 index 000000000000..999d248136a3 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/guides/compaction/index.md @@ -0,0 +1,147 @@ +--- +title: "Managing Context & Compaction" +description: "How to keep long Docker Agent sessions from filling the model's context window: automatic and on-demand compaction, trimming tool results, and reading the context gauge." +keywords: docker agent, ai agents, guides, context window, compaction, session compaction +weight: 50 +canonical: https://docs.docker.com/ai/docker-agent/guides/compaction/ +--- + +_How to keep long-running sessions from filling the model's context window._ + +## Why long sessions fill the context window + +Every model has a fixed context window — a maximum number of tokens it can read per request. As a session grows, the system prompt, tool definitions, prompt files, and the full message history (including every tool call and its result) all count against that budget. A long-running agent — one that reads many files, runs many commands, or just keeps chatting for a while — eventually approaches the limit. Once a request no longer fits, the model provider rejects it and the session stalls. + +Docker Agent addresses this with **compaction**: replacing older parts of the conversation with a compact AI-generated summary, freeing up room for the session to keep going. This guide covers the levers you have — automatic compaction, on-demand compaction, and trimming individual tool results — and how to read the context gauge so you know where a session stands. + +## Let Docker Agent compact automatically + +By default, every agent proactively compacts its own session once estimated token usage crosses **90%** of the model's context window: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: A long-running research assistant + instruction: You are a helpful assistant. +``` + +No configuration is required to get this behavior — it's on by default. Three fields let you tune it: + +| Field | Where | Description | +| --- | --- | --- | +| `session_compaction` | agent | Set to `false` to disable automatic compaction entirely for this agent (both the proactive threshold trigger and the post-overflow auto-recovery). The manual `/compact` command still works. Default: `true`. | +| `compaction_threshold` | agent or model | Fraction of the context window (greater than `0`, at most `1`) at which proactive compaction fires. A value set on the model takes precedence over the agent-level value. Default: `0.9`. | +| `compaction_model` | model | Delegate the compaction (summary-generation) call to a different, usually cheaper and faster, model. | + +Lower the threshold to compact earlier and keep individual requests smaller and cheaper; raise it to keep more verbatim history in context before the first summary happens: + +```yaml +models: + primary: + provider: anthropic + model: claude-sonnet-4-5 + # Compact at 80% of the window instead of the default 90%. + compaction_threshold: 0.8 +``` + +Compaction itself is a model call — feeding the full conversation to a model and asking for a summary — and it's the most expensive call in a session simply because it's the one that runs when the context is largest. There's rarely a reason to spend your primary reasoning model on it. Point `compaction_model` at something smaller instead; every other call still runs on the primary model: + +```yaml +models: + primary: + provider: anthropic + model: claude-sonnet-4-5 + compaction_model: fast + fast: + provider: anthropic + model: claude-haiku-4-5 +``` + +> [!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. + +Disable compaction only when you specifically want a session to keep full, unabridged history and are willing to risk hitting the context limit: + +```yaml +agents: + archivist: + model: anthropic/claude-sonnet-4-5 + description: An assistant that never auto-compacts its sessions. + instruction: You keep full conversation history and never lose context. + session_compaction: false +``` + +See [`examples/compaction_model.yaml`](https://github.com/docker/docker-agent/blob/main/examples/compaction_model.yaml) and [`examples/compaction_threshold.yaml`](https://github.com/docker/docker-agent/blob/main/examples/compaction_threshold.yaml) for complete configurations, and [Delegating Session Compaction](../../configuration/models/index.md#delegating-session-compaction) in the Model Config reference for the full field-level details. + +## Compact on demand + +You don't have to wait for the automatic threshold. Two TUI commands give you direct control: + +- **`/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. + +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. + +```bash +$ docker agent run agent.yaml +# ... work for a while ... +# Type /context to see the current breakdown, or /compact to summarize now +``` + +## Trim tool results to save room + +Compaction deals with the whole conversation at once. For sessions dominated by a few oversized tool results — a full build log, a large file dump — three agent-level fields let you cap the damage before it ever reaches compaction: + +| Field | What it bounds | Behavior | +| --- | --- | --- | +| `max_tool_result_tokens` | Each tool result, as it's added to the session | Oversized results are truncated **middle-out**: the head and tail are kept (usually the most informative parts) and the removed middle is replaced with a truncation marker. | +| `max_old_tool_call_tokens` | The total budget for **old** tool call arguments and results | Once older tool calls exceed the budget, their content is replaced wholesale with a placeholder — freeing context space without touching recent, still-relevant calls. | +| `num_history_items` | The number of non-system conversation messages kept in history | A message-**count** limit, not a token budget. The oldest non-protected messages are dropped first once the count is exceeded; **system and user messages are always protected** and are never counted against or removed by this limit, so the assembled history can exceed `num_history_items` and every user message survives even a long single-turn agentic loop. | + +`max_tool_result_tokens` and `max_old_tool_call_tokens` are approximated as `len/4` tokens (the industry rule-of-thumb of ~4 characters per token); `num_history_items` counts messages, not tokens. All three are disabled by default (`0`). Set a positive value to enable them: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: An assistant whose tool results are capped at ~2000 tokens each. + instruction: | + You are a helpful assistant with shell access. Very large command + outputs are truncated in the middle — the beginning and end are + always preserved, and a marker shows where content was removed. + max_tool_result_tokens: 2000 + toolsets: + - type: shell +``` + +> [!TIP] +> **Use both together** +> +> `max_tool_result_tokens` bounds each result the moment it's recorded; `max_old_tool_call_tokens` reclaims space from calls that are no longer fresh. Combine them on tool-heavy agents (shell, filesystem) to keep the session lean well before it approaches the compaction threshold. + +See [`examples/max_tool_result_tokens.yaml`](https://github.com/docker/docker-agent/blob/main/examples/max_tool_result_tokens.yaml) for a complete example, and [Agent Config](../../configuration/agents/index.md#properties-reference) for the full field reference. + +## Read the context gauge + +The TUI's sidebar token-usage section (and the fill bar in the [lean TUI](../../features/tui/index.md#lean-tui) status line) color-escalates as a session approaches its compaction threshold, so you can see trouble coming before a request fails: + +| State | Color | Trigger | +| --- | --- | --- | +| Normal | (default) | Usage below 75% of the compaction threshold | +| Warning | Orange | Usage at or above 75% of the compaction threshold | +| Critical | Red | Usage at or above 95% of the compaction threshold | + +While a compaction is running, the percentage is replaced by a **"compacting…"** indicator; token counts remain visible in the lean TUI status line. The thresholds scale with the agent's configured `compaction_threshold` (default `0.9`), so a custom value keeps a predictable visual runway — for example, a `compaction_threshold: 0.8` session turns orange at 60% usage (75% of 0.8) instead of 67.5%. + +Open `/context` at any time for the full per-category breakdown behind that percentage. + +## What happens to cost across compaction + +Compaction summarizes history, but it never resets what a session has actually cost you. Session cost tracking is **monotonic across compaction**: the running total only ever goes up, even though the summarized conversation itself is now smaller. Check `/cost` to see the current breakdown at any point, before or after a compaction has run. + +## 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. 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 af6d01c52db5..35e20806afa1 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 @@ -375,7 +375,7 @@ settings: default_model: anthropic/claude-sonnet-4-5 ``` -This model is used when you run `docker agent run` without a config file. +This model is used by the built-in default agent when you run `docker agent run` without a config argument and no project-level `docker-agent.yaml`, `docker-agent.yml`, or `docker-agent.hcl` exists. ### Get Desktop Notifications with Hooks 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 c6cc389bb0d5..a56534cbd423 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/custom/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/custom/index.md @@ -302,3 +302,9 @@ When you reference a provider: 3. All model-level defaults (temperature, max_tokens, thinking_budget, etc.) are inherited (model settings take precedence) 4. For OpenAI-compatible providers, the `api_type` is stored in `provider_opts.api_type` 5. The model is used with the appropriate API client + +A provider with a `base_url` implies `bypass_models_gateway: true` for every +model that references it: user-chosen endpoints are never routed through a +configured models gateway, and such models authenticate with the provider's +own credentials (`token_key`). See +[Gateway Bypass](../../configuration/models/index.md#gateway-bypass). diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/mistral/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/mistral/index.md index db977d445141..5d2805fbcce5 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 @@ -70,7 +70,7 @@ Check the [Mistral Models documentation](https://docs.mistral.ai/getting-started ## Auto-Detection -When you run `docker agent run` without specifying a config, docker-agent automatically detects available providers. If `MISTRAL_API_KEY` is set and higher-priority providers (OpenAI, Anthropic, Google) are not available, Mistral will be used with `mistral-small-latest` as the default model. +When you run `docker agent run` without specifying a config and no project-level `docker-agent.yaml`, `docker-agent.yml`, or `docker-agent.hcl` exists, docker-agent automatically detects available providers. If `MISTRAL_API_KEY` is set and higher-priority providers (OpenAI, Anthropic, Google) are not available, Mistral will be used with `mistral-small-latest` as the default model. ## Extended Thinking diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/scheduler/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/scheduler/index.md new file mode 100644 index 000000000000..16635f7f77f2 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/tools/scheduler/index.md @@ -0,0 +1,96 @@ +--- +title: "Scheduler Tool" +description: "Schedule instructions to run at a time or on a recurring interval." +keywords: docker agent, ai agents, tools, toolsets, scheduler tool, cron +linkTitle: "Scheduler" +weight: 135 +canonical: https://docs.docker.com/ai/docker-agent/tools/scheduler/ +--- + +_Schedule instructions to run at a time or on a recurring interval._ + +## Overview + +The scheduler toolset lets an agent make something happen at a chosen time or on a repeating cadence during a session. You give it an instruction and a schedule; when the schedule is due, the instruction is delivered back to the agent, which then carries out the action with its normal tools (`shell`, `api`, `fetch`, and so on). + +The scheduler does not run shell or API calls itself. When a schedule fires it injects the instruction into the agent loop via the runtime's recall mechanism — the same primitive [`background_jobs`](../background-jobs/index.md) uses to report completed work — and the agent decides how to act. This keeps every action under the agent's normal tools and permissions rather than adding a second, unattended +command runner. + +> [!NOTE] +> Schedules only fire while the session is running (interactive TUI or a server mode) and are not persisted across restarts. Scheduling requires a host that supports recall; if it does not, `create_schedule` returns an error. + +## Configuration + +```yaml +toolsets: + - type: scheduler +``` + +No configuration options. + +## Tools + +| Tool | Description | +| --- | --- | +| `create_schedule` | Register an instruction to run at a time or interval. | +| `list_schedules` | List active schedules with their id, spec, and next fire time. | +| `cancel_schedule` | Remove a schedule by id. | + +### `create_schedule` + +| Parameter | Required | Description | +| --- | --- | --- | +| `prompt` | Yes | The instruction to deliver to the agent when the schedule fires. | +| `when` | Yes | When to fire (see [Schedule specs](#schedule-specs)). | +| `name` | No | Optional human-readable label. | + +Returns the new schedule's id and its next fire time. + +### `cancel_schedule` + +| Parameter | Required | Description | +| --- | --- | --- | +| `id` | Yes | The id of the schedule to cancel (from `create_schedule` or `list_schedules`). | + +## Schedule specs + +The `when` argument accepts: + +| Form | Meaning | Example | +| --- | --- | --- | +| `in:` | One-shot, after a delay | `in:10m` | +| `at:` | One-shot, at an absolute future time | `at:2026-07-14T09:00:00Z` | +| `every:` | Recurring, at a fixed interval | `every:1h` | +| `minutely` / `hourly` / `daily` / `weekly` | Recurring preset intervals | `hourly` | + +Durations use Go's duration syntax (`30s`, `15m`, `2h`). Preset and `every:` intervals are measured from the schedule's creation time (for example `hourly` fires every hour after it is created), not aligned to wall-clock slots. + +> [!IMPORTANT] +> **Recurring schedules have a one-minute minimum.** Every fire injects a message into the agent loop and typically costs an LLM turn, so `every:` values below `1m` are rejected — a typo such as `every:1s` in place of `every:1h` would otherwise become a runaway token burn. One-shot schedules (`in:` / `at:`) are not restricted, since they fire once. + +## Example + +```yaml +agents: + root: + model: openai/gpt-5-mini + description: A monitoring assistant + instruction: | + Every 15 minutes, run `git fetch` and tell me if origin/main moved. + toolsets: + - type: scheduler + - type: shell +``` + +The agent calls: + +```text +create_schedule(prompt="Run git fetch and report if origin/main moved", when="every:15m") +``` + +Every 15 minutes it is reminded, runs the command with the `shell` tool, and reports back. + +> [!TIP] +> **When to use** +> +> Use the scheduler for recurring monitoring, timed one-shots, and unattended housekeeping loops during a long-running session. For work that should run immediately and be awaited, use [`background_jobs`](../background-jobs/index.md) instead. diff --git a/_vendor/modules.txt b/_vendor/modules.txt index 8403425740b0..b8a46dc1b57a 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -4,4 +4,4 @@ # github.com/docker/cli v29.6.1+incompatible # github.com/docker/compose/v5 v5.3.0 # github.com/docker/model-runner v1.1.36 -# github.com/docker/docker-agent v1.110.0 +# github.com/docker/docker-agent v1.111.0 diff --git a/go.mod b/go.mod index d0382531ba66..cac7079fcc86 100644 --- a/go.mod +++ b/go.mod @@ -11,7 +11,7 @@ require ( github.com/docker/buildx v0.35.0 github.com/docker/cli v29.6.1+incompatible github.com/docker/compose/v5 v5.3.0 - github.com/docker/docker-agent v1.110.0 + github.com/docker/docker-agent v1.111.0 github.com/docker/model-runner v1.1.36 github.com/moby/buildkit v0.31.0 github.com/moby/moby/api v1.55.0 diff --git a/go.sum b/go.sum index b946e47850ce..7edc19343c1c 100644 --- a/go.sum +++ b/go.sum @@ -132,6 +132,8 @@ github.com/docker/docker-agent v1.103.0 h1:hmS2u0fU4MMyUnXrjJlhcfjpBUzkBEBM9/Drm github.com/docker/docker-agent v1.103.0/go.mod h1:KUYwjuxrs2N3BBrAQ6CMNPVQxOfoZoLUYpbxyGTM02w= github.com/docker/docker-agent v1.110.0 h1:B5LJRkEvIk1WLojMR09gD6ZAD2hD43SIRSbjKs+yyc4= github.com/docker/docker-agent v1.110.0/go.mod h1:TcrFxPYbc9SL0ouAcb/YwwjePfS0ULYkzfTJkvDUfzY= +github.com/docker/docker-agent v1.111.0 h1:kLIxO5oxFlvUfROldmNe9G1mO3kAGY8LtfCehb0M0Ys= +github.com/docker/docker-agent v1.111.0/go.mod h1:xiBK+8ajugSvAVx1oSOIHE/SA5ZcamQERH6YjAfrldE= 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=