From 84e4d98ff787f24228014bcda965001cb9c7c5ea Mon Sep 17 00:00:00 2001 From: David Gageot Date: Tue, 9 Jun 2026 22:27:04 +0200 Subject: [PATCH] docs: fix config version, provider defaults, CLI flags, and RAG parameters --- docs/concepts/models/index.md | 14 +++++++------- docs/configuration/models/index.md | 5 +++-- docs/configuration/overview/index.md | 6 +++--- docs/features/a2a/index.md | 2 +- docs/features/cli/index.md | 5 +++++ docs/features/tui/index.md | 1 + docs/guides/thinking/index.md | 9 +++++---- docs/providers/anthropic/index.md | 6 +++--- docs/providers/bedrock/index.md | 6 +++--- docs/tools/filesystem/index.md | 2 +- docs/tools/model-picker/index.md | 14 ++++++++++---- docs/tools/rag/index.md | 12 ++++++------ 12 files changed, 48 insertions(+), 34 deletions(-) diff --git a/docs/concepts/models/index.md b/docs/concepts/models/index.md index 20fb367ad..d43c31962 100644 --- a/docs/concepts/models/index.md +++ b/docs/concepts/models/index.md @@ -108,13 +108,13 @@ See the [Model Providers]({{ '/providers/overview/' | relative_url }}) section f Control how much the model "thinks" before responding: -| Provider | Format | Values | Default | -| ---------- | ---------- | ------------------------------------- | ------------ | -| OpenAI | string | `minimal`, `low`, `medium`, `high` | `medium` | -| Anthropic | int | 1024–32768 tokens | 8192 | -| Gemini 2.5 | int | 0 (off), -1 (dynamic), or token count | -1 (dynamic) | -| Gemini 3 | string | `minimal`, `low`, `medium`, `high` | varies | -| All | string/int | `none` or `0` to disable | — | +| Provider | Format | Values | Default | +| ---------- | ---------- | -------------------------------------------- | -------------------------------- | +| OpenAI | string | `minimal`, `low`, `medium`, `high`, `xhigh` | `medium` (always-reasoning models only) | +| Anthropic | int | 1024–32768 tokens | off | +| Gemini 2.5 | int | 0 (off), -1 (dynamic), or token count | -1 (dynamic) | +| Gemini 3 | string | `minimal`, `low`, `medium`, `high` | varies | +| All | string/int | `none` or `0` to disable | — | ```yaml models: diff --git a/docs/configuration/models/index.md b/docs/configuration/models/index.md index 3817e77f4..f089fe655 100644 --- a/docs/configuration/models/index.md +++ b/docs/configuration/models/index.md @@ -220,14 +220,15 @@ See [`examples/task_budget.yaml`](https://github.com/docker/docker-agent/blob/ma ## Interleaved Thinking -For Anthropic and Bedrock Claude models, interleaved thinking allows tool calls during model reasoning. This is enabled by default: +For Anthropic and Bedrock Claude models, interleaved thinking allows tool calls during model reasoning. It is auto-enabled whenever a thinking budget is configured: ```yaml models: claude: provider: anthropic model: claude-sonnet-4-5 - # interleaved_thinking defaults to true + thinking_budget: 8192 + # interleaved_thinking is auto-enabled when thinking_budget is set provider_opts: interleaved_thinking: false # disable if needed ``` diff --git a/docs/configuration/overview/index.md b/docs/configuration/overview/index.md index c0e265109..2460aa0f5 100644 --- a/docs/configuration/overview/index.md +++ b/docs/configuration/overview/index.md @@ -16,7 +16,7 @@ A docker-agent config has these main sections: ```bash # 1. Version — configuration schema version (optional but recommended) -version: 8 +version: 10 # 2. Metadata — optional agent metadata for distribution metadata: @@ -304,10 +304,10 @@ For YAML editor autocompletion and validation, use the [Docker Agent JSON Schema ## Config Versioning -docker-agent configs are versioned. The current version is `8`. Add the version at the top of your config: +docker-agent configs are versioned. The current version is `10`. Add the version at the top of your config: ```yaml -version: 8 +version: 10 agents: root: diff --git a/docs/features/a2a/index.md b/docs/features/a2a/index.md index 80432a1ad..74e12cf38 100644 --- a/docs/features/a2a/index.md +++ b/docs/features/a2a/index.md @@ -37,7 +37,7 @@ $ docker agent serve a2a agentcatalog/pirate | Flag | Default | Description | | --------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- | | `-l, --listen ` | `127.0.0.1:8082` | Address to listen on. | -| `-a, --agent ` | `root` | Name of the agent to expose when the config contains multiple agents. | +| `-a, --agent ` | (first agent) | Name of the agent to expose when the config contains multiple agents. Defaults to the team's first agent. | | `--working-dir ` | current dir | Working directory the agent runs in. | | `--env-from-file ` | (none) | Load additional environment variables from a `.env` file (repeatable). | | `--models-gateway ` | (none) | Route all provider traffic through a models gateway URL. | diff --git a/docs/features/cli/index.md b/docs/features/cli/index.md index 6789cc915..04f36daad 100644 --- a/docs/features/cli/index.md +++ b/docs/features/cli/index.md @@ -41,6 +41,8 @@ $ docker agent run [config] [message...] [flags] | `--app-name ` | Override the application name label shown in the TUI (status bar, window title, "/exit" notifications). | | `--sidebar` | Control sidebar visibility. Set to `--sidebar=false` to hide the sidebar and disable the Ctrl+B toggle (default: `true`). | | `--disable-commands ` | Hide and disable specific slash commands in the TUI. Accepts a comma-separated list of command names (leading slash optional, case-insensitive). E.g. `--disable-commands="/cost,/eval,/model"`. | +| `--theme ` | Preselect a TUI theme by name (overrides the theme from user config; ignored outside the interactive TUI) | +| `--on-event =` | Run a shell command when an event of the given type fires (`*=` matches any event). Repeatable. | | `--json` | Output results as newline-delimited JSON (use with `--exec`) | | `--hide-tool-calls` | Hide tool calls in the output | | `--hide-tool-results` | Hide tool call results in the output | @@ -220,8 +222,11 @@ $ docker agent serve mcp [flags] | Flag | Default | Description | | ---------------------- | ------------------ | ------------------------------------------------------------------------------------------------- | | `-a, --agent ` | (all agents) | Name of the agent to expose. If omitted, every agent in the config is exposed as a separate tool. | +| `--tool-name ` | (agent name) | Override the MCP tool identifier clients call; only valid when exposing a single agent. | | `--http` | `false` | Use streaming HTTP transport instead of stdio. | | `-l, --listen ` | `127.0.0.1:8081` | Address to listen on (only used with `--http`). | +| `--mcp-keepalive `| `0` (disabled) | Interval between MCP keep-alive pings (e.g. `30s`). | +| `--attach [target]` | (none) | Attach to a running TUI run by pid, address, or session id; given without a value, selects the most recent run. | All [runtime configuration flags](#runtime-configuration-flags) are also accepted. diff --git a/docs/features/tui/index.md b/docs/features/tui/index.md index 1bbb6f027..068380bec 100644 --- a/docs/features/tui/index.md +++ b/docs/features/tui/index.md @@ -70,6 +70,7 @@ Type `/` during a session to see available commands, or press Ctrl+`) | | `/permissions` | Inspect and edit tool permission rules | | `/split-diff` | Toggle split-diff view for file edits | diff --git a/docs/guides/thinking/index.md b/docs/guides/thinking/index.md index 244848b06..14f3b13cf 100644 --- a/docs/guides/thinking/index.md +++ b/docs/guides/thinking/index.md @@ -126,7 +126,7 @@ thinking_budget: none # or 0 ### Interleaved thinking -By default, thinking is non-interleaved (the model reasons once before answering). Enable interleaved thinking to allow reasoning during tool calls — useful for complex agentic tasks: +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: ```yaml models: @@ -134,8 +134,9 @@ models: provider: anthropic model: claude-sonnet-4-5 thinking_budget: 16384 + # interleaved_thinking is auto-enabled; disable it explicitly if needed: provider_opts: - interleaved_thinking: true + interleaved_thinking: false ```
@@ -247,13 +248,13 @@ models: thinking_budget: high provider_opts: region: us-east-1 - interleaved_thinking: true + # interleaved_thinking is auto-enabled when thinking_budget is set ```
Bedrock thinking requirements
-

Bedrock Claude requires thinking_budget to be ≥ 1024 and less than max_tokens. docker-agent logs a warning and ignores the budget if either condition is violated. Interleaved thinking requires the interleaved-thinking-2025-05-14 beta header, which docker-agent adds automatically when interleaved_thinking: true is set.

+

Bedrock Claude requires thinking_budget to be ≥ 1024 and less than max_tokens. docker-agent logs a warning and ignores the budget if either condition is violated. Interleaved thinking requires the interleaved-thinking-2025-05-14 beta header, which docker-agent adds automatically; it is auto-enabled whenever a thinking budget is set on a Bedrock-hosted Claude model.

## xAI (Grok) and Mistral diff --git a/docs/providers/anthropic/index.md b/docs/providers/anthropic/index.md index 75a8ba19a..35021332a 100644 --- a/docs/providers/anthropic/index.md +++ b/docs/providers/anthropic/index.md @@ -98,13 +98,13 @@ models: | Model ID | Description | | ------------------- | --------------------------------------------------- | | `claude-opus-4-7` | Highest-capability Opus model; supports task budget | -| `claude-sonnet-4-5` | Most capable Sonnet, extended thinking (default) | +| `claude-sonnet-4-5` | Most capable Sonnet; supports extended thinking | | `claude-sonnet-4-0` | Previous Sonnet generation, still supported | | `claude-haiku-4-5` | Fast and inexpensive, good for tight loops | ## Thinking Budget -Anthropic uses integer token budgets (1024–32768). Defaults to 8192 with interleaved thinking enabled: +Anthropic uses integer token budgets (1024–32768). Thinking is off unless you set `thinking_budget`; when set, interleaved thinking is auto-enabled: ```yaml models: @@ -116,7 +116,7 @@ models: ## Interleaved Thinking -Enabled by default. Allows tool calls during model reasoning for more integrated problem-solving: +Auto-enabled whenever a thinking budget is configured on a Claude model. Allows tool calls during model reasoning for more integrated problem-solving: ```yaml models: diff --git a/docs/providers/bedrock/index.md b/docs/providers/bedrock/index.md index 1f9e61e2a..95f093d3a 100644 --- a/docs/providers/bedrock/index.md +++ b/docs/providers/bedrock/index.md @@ -80,7 +80,7 @@ models: | `role_session_name` | string | docker-agent-bedrock-session | Session name for assumed role | | `external_id` | string | — | External ID for role assumption | | `endpoint_url` | string | — | Custom endpoint (VPC/testing) | -| `interleaved_thinking` | bool | false | Allow reasoning between tool calls (Claude); adds the required beta header automatically | +| `interleaved_thinking` | bool | auto | Allow reasoning between tool calls (Claude); auto-enabled when a thinking budget is set on a Claude model; adds the required beta header automatically | | `disable_prompt_caching` | bool | false | Disable automatic prompt caching | ## Inference Profiles @@ -144,10 +144,10 @@ models: thinking_budget: high provider_opts: region: us-east-1 - interleaved_thinking: true + # interleaved_thinking is auto-enabled when thinking_budget is set ``` -docker-agent automatically adds the `interleaved-thinking-2025-05-14` beta header when `interleaved_thinking: true` is set. If you set `interleaved_thinking: false` while a thinking budget is active, a warning is logged because the budget may be ignored by Bedrock without the beta header. +docker-agent auto-enables `interleaved_thinking` whenever a thinking budget is configured on a Bedrock-hosted Claude model and automatically adds the `interleaved-thinking-2025-05-14` beta header. If you set `interleaved_thinking: false` while a thinking budget is active, a warning is logged because the budget may be ignored by Bedrock without the beta header. See the [Thinking / Reasoning guide]({{ '/guides/thinking/' | relative_url }}) for a full cross-provider overview. diff --git a/docs/tools/filesystem/index.md b/docs/tools/filesystem/index.md index 56288a0c9..acb7e217b 100644 --- a/docs/tools/filesystem/index.md +++ b/docs/tools/filesystem/index.md @@ -84,7 +84,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 (including `write_file`, `patch_file`, and similar mutations). 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`). Use `${file}` as a placeholder for the absolute path of the edited file. ```yaml toolsets: diff --git a/docs/tools/model-picker/index.md b/docs/tools/model-picker/index.md index 0d7278470..5239dbee9 100644 --- a/docs/tools/model-picker/index.md +++ b/docs/tools/model-picker/index.md @@ -31,7 +31,7 @@ toolsets: ## How It Works -When the model picker toolset is enabled, the agent gets a `pick_model` tool it can call to switch to a different model for the next turn. The agent decides which model to use based on the complexity of the task, cost considerations, or other factors you describe in its instruction. +When the model picker toolset is enabled, the agent gets two tools: `change_model` to switch to one of the configured models, and `revert_model` to return to its default model. The agent decides which model to use based on the complexity of the task, cost considerations, or other factors you describe in its instruction. ## Example @@ -59,10 +59,16 @@ agents: ## Tool Interface -The toolset exposes a single tool, `pick_model`, with one parameter: +The toolset exposes two tools: + +### `change_model` | Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------------------------------------------------- | -| `model` | string | ✓ | The model to use for the next turn. Must be one of the configured models. | +| `model` | string | ✓ | The model to switch to. Must be one of the configured models. | + +### `revert_model` + +Takes no parameters. Reverts the agent to its original/default model. -The model switch takes effect on the **next** turn — the current turn continues with the model that was active when `pick_model` was called. +The switch takes effect immediately: the next inference call — including the remainder of the current agentic loop — uses the new model. diff --git a/docs/tools/rag/index.md b/docs/tools/rag/index.md index 249f7fac4..ccc5af3d6 100644 --- a/docs/tools/rag/index.md +++ b/docs/tools/rag/index.md @@ -56,7 +56,7 @@ strategies: similarity_metric: cosine_similarity threshold: 0.5 limit: 10 - batch_size: 50 + embedding_batch_size: 50 chunking: size: 1000 overlap: 100 @@ -212,9 +212,9 @@ Look for log tags: `[RAG Manager]`, `[Chunked-Embeddings Strategy]`, `[BM25 Stra | `similarity_metric` | string | `cosine_similarity` | Similarity metric | | `threshold` | float | `0.5` | Minimum similarity score (0–1) | | `limit` | int | `5` | Max results from this strategy | -| `batch_size` | int | `50` | Chunks per embedding request | +| `embedding_batch_size` | int | `50` | Chunks per embedding request | | `max_embedding_concurrency` | int | `3` | Max concurrent embedding requests | -| `chunking.size` | int | `1000` | Chunk size in characters | +| `chunking.size` | int | `1500` | Chunk size in characters (`4000` when `code_aware` is set) | | `chunking.overlap` | int | `75` | Overlap between chunks in characters | | `chunking.code_aware` | bool | `false` | AST-based chunking (Go files only) | @@ -231,7 +231,7 @@ Look for log tags: `[RAG Manager]`, `[Chunked-Embeddings Strategy]`, `[BM25 Stra | `threshold` | float | `0.5` | Minimum similarity score (0–1) | | `limit` | int | `5` | Max results | | `max_indexing_concurrency` | int | `3` | Max concurrent file indexing | -| `chunking.size` | int | `1000` | Chunk size in characters | +| `chunking.size` | int | `1500` | Chunk size in characters (`4000` when `code_aware` is set) | | `chunking.overlap` | int | `75` | Overlap between chunks | | `chunking.code_aware` | bool | `false` | AST-based chunking | @@ -244,7 +244,7 @@ Look for log tags: `[RAG Manager]`, `[Chunked-Embeddings Strategy]`, `[BM25 Stra | `b` | float | `0.75` | Length normalization (0–1) | | `threshold` | float | `0.0` | Minimum BM25 score | | `limit` | int | `5` | Max results | -| `chunking.size` | int | `1000` | Chunk size in characters | +| `chunking.size` | int | `1500` | Chunk size in characters | | `chunking.overlap` | int | `75` | Overlap between chunks | ### Results (Post-Processing) @@ -258,6 +258,6 @@ Look for log tags: `[RAG Manager]`, `[Chunked-Embeddings Strategy]`, `[BM25 Stra | `include_score` | bool | `false` | Include relevance scores in results | | `return_full_content` | bool | `false` | Return full document content instead of just matched chunks | | `reranking.model` | string | — | Reranking model reference | -| `reranking.top_k` | int | (all) | Only rerank top K results | +| `reranking.top_k` | int | (`limit`) | Only rerank top K results. Defaults to the results `limit` when set. | | `reranking.threshold` | float | `0.5` | Minimum relevance score after reranking | | `reranking.criteria` | string | — | Custom relevance guidance for the reranking model |