From fa8db0312e9ae43d913bb7e1c18c6b7781604c4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Mon, 13 Jul 2026 04:10:55 +0000 Subject: [PATCH 1/2] docs: update for docker/docker-agent#3341,3343,3358,3361,3368,3369,3376,3384,3385,3337,3389 - add new model providers Add documentation for twelve new built-in provider aliases: Baseten, Cerebras, Cloudflare AI Gateway, Cloudflare Workers AI, DeepSeek, Fireworks AI, Groq, Moonshot AI, OpenRouter, OVHcloud, Together AI, Vercel. Also add compaction_model and bypass_models_gateway model config fields, and tags metadata field. --- .../ai/docker-agent/model-providers.md | 526 +++++++++++++ .../ai/docker-agent/reference/config.md | 695 ++++++++++++++++++ 2 files changed, 1221 insertions(+) create mode 100644 content/manuals/ai/docker-agent/model-providers.md create mode 100644 content/manuals/ai/docker-agent/reference/config.md diff --git a/content/manuals/ai/docker-agent/model-providers.md b/content/manuals/ai/docker-agent/model-providers.md new file mode 100644 index 00000000000..82865c10190 --- /dev/null +++ b/content/manuals/ai/docker-agent/model-providers.md @@ -0,0 +1,526 @@ +--- +title: Model providers +description: Get API keys and configure cloud model providers for Docker Agent +keywords: [docker agent, model providers, api keys, anthropic, openai, google, gemini, groq, deepseek, cerebras, fireworks, together, moonshot, openrouter, ovhcloud, baseten, vercel, cloudflare] +weight: 10 +--- + +To run Docker Agent, you need a model provider. You can either use a cloud provider +with an API key or run models locally with [Docker Model +Runner](local-models.md). + +This guide covers cloud providers. For the local alternative, see [Local +models with Docker Model Runner](local-models.md). + +## Supported providers + +Docker Agent supports these cloud model providers: + +- Anthropic — Claude models +- Baseten — open-weight models via Baseten +- Cerebras — fast inference for open-weight models +- Cloudflare AI Gateway — multi-provider gateway with caching and observability +- Cloudflare Workers AI — open-weight models on the Cloudflare edge +- DeepSeek — DeepSeek chat and reasoning models +- Fireworks AI — fast inference for open-weight models +- Google — Gemini models +- Groq — ultra-low-latency open-weight models +- Moonshot AI — Kimi models +- OpenAI — GPT models +- OpenRouter — unified gateway to hundreds of models +- OVHcloud — EU-hosted open-weight models +- Together AI — large catalog of open-weight models +- Vercel AI Gateway — unified gateway to OpenAI, Anthropic, Google, and more + +## Anthropic + +Anthropic provides the Claude family of models, including Claude Sonnet and +Claude Opus. + +To get an API key: + +1. Go to [console.anthropic.com](https://console.anthropic.com/). +2. Sign up or sign in to your account. +3. Navigate to the API Keys section. +4. Create a new API key. +5. Copy the key. + +Set your API key as an environment variable: + +```console +$ export ANTHROPIC_API_KEY=your_key_here +``` + +Use Anthropic models in your agent configuration: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + instruction: You are a helpful coding assistant +``` + +Available models include: + +- `anthropic/claude-sonnet-4-5` +- `anthropic/claude-opus-4-5` +- `anthropic/claude-haiku-4-5` + +## Baseten + +[Baseten](https://www.baseten.co/) provides AI models through an +OpenAI-compatible API. It is a good choice for deploying your own models or +accessing hosted open-weight models. + +1. Get an API key from [Baseten](https://www.baseten.co/). +2. Set the environment variable: + +```console +$ export BASETEN_API_KEY=your_key_here +``` + +Use Baseten models in your agent configuration: + +```yaml +agents: + root: + model: baseten/deepseek-ai/DeepSeek-V3.1 + instruction: You are a helpful assistant +``` + +Or with a named model for more control: + +```yaml +models: + baseten_model: + provider: baseten + model: deepseek-ai/DeepSeek-V3.1 + max_tokens: 8192 + +agents: + root: + model: baseten_model + instruction: You are a helpful assistant +``` + +## Cerebras + +[Cerebras](https://www.cerebras.ai/) serves open-weight models (including +GPT-OSS and GLM) on its wafer-scale hardware through an OpenAI-compatible API, +delivering some of the highest inference speeds available. + +1. Create an API key from the [Cerebras Cloud console](https://cloud.cerebras.ai/). +2. Set the environment variable: + +```console +$ export CEREBRAS_API_KEY=your_key_here +``` + +Use Cerebras models in your agent configuration: + +```yaml +agents: + root: + model: cerebras/gpt-oss-120b + instruction: You are a helpful assistant +``` + +Available models include: + +- `cerebras/gpt-oss-120b` +- `cerebras/zai-glm-4.7` + +## Cloudflare AI Gateway + +[Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/) is a +single OpenAI-compatible endpoint that routes to models from OpenAI, Anthropic, +Workers AI, and more, with caching, rate limiting, and observability. + +The gateway endpoint is account- and gateway-scoped. Three environment variables +are required: + +```console +$ export CLOUDFLARE_ACCOUNT_ID=your_account_id +$ export CLOUDFLARE_GATEWAY_ID=your_gateway_id +$ export CLOUDFLARE_API_TOKEN=your_api_token +``` + +Use Cloudflare AI Gateway in your agent configuration: + +```yaml +agents: + root: + model: cloudflare-ai-gateway/workers-ai/@cf/meta/llama-3.1-8b-instruct + instruction: You are a helpful assistant +``` + +Or with a named model: + +```yaml +models: + cf_gateway_model: + provider: cloudflare-ai-gateway + model: "workers-ai/@cf/meta/llama-3.1-8b-instruct" + +agents: + root: + model: cf_gateway_model + instruction: You are a helpful assistant +``` + +> [!NOTE] +> The alias sends your token in the standard `Authorization: Bearer` header, +> which works for unauthenticated gateways (the default) routing to Workers AI +> models. Gateways with authentication enabled require the `cf-aig-authorization` +> header, which is not supported by this alias. For that setup, use a [custom +> provider](reference/config.md#models) instead. + +## Cloudflare Workers AI + +[Cloudflare Workers AI](https://developers.cloudflare.com/workers-ai/) runs +open-weight models (Llama, Mistral, Qwen, Gemma, and more) on Cloudflare's +global edge network. + +Workers AI is account-scoped, so two environment variables are required: + +```console +$ export CLOUDFLARE_ACCOUNT_ID=your_account_id +$ export CLOUDFLARE_API_TOKEN=your_api_token +``` + +Use Cloudflare Workers AI in your agent configuration: + +```yaml +agents: + root: + model: cloudflare-workers-ai/@cf/meta/llama-3.1-8b-instruct + instruction: You are a helpful assistant +``` + +Available models include `@cf/meta/llama-3.1-8b-instruct`, +`@cf/mistralai/mistral-small-3.1-24b-instruct`, and more. See the +[Workers AI models catalog](https://developers.cloudflare.com/workers-ai/models/) +for the full list. + +## DeepSeek + +[DeepSeek](https://www.deepseek.com/) serves its frontier chat and reasoning +models through an OpenAI-compatible API, with strong price/performance on coding +and reasoning tasks. + +1. Create an API key from the [DeepSeek Platform](https://platform.deepseek.com/api_keys). +2. Set the environment variable: + +```console +$ export DEEPSEEK_API_KEY=your_key_here +``` + +Use DeepSeek models in your agent configuration: + +```yaml +agents: + root: + model: deepseek/deepseek-chat + instruction: You are a helpful coding assistant +``` + +Available models include: + +- `deepseek/deepseek-chat` — DeepSeek-V3, general-purpose chat and tool calling +- `deepseek/deepseek-reasoner` — DeepSeek-R1, extended-reasoning model + +## Fireworks AI + +[Fireworks AI](https://fireworks.ai/) is a fast inference host for open-weight +models, serving Kimi K2, Llama, Qwen, DeepSeek, GLM, and others through an +OpenAI-compatible API. + +1. Create an API key from the [Fireworks dashboard](https://fireworks.ai/account/api-keys). +2. Set the environment variable: + +```console +$ export FIREWORKS_API_KEY=your_key_here +``` + +Use Fireworks AI models in your agent configuration: + +```yaml +agents: + root: + model: fireworks/accounts/fireworks/models/kimi-k2-instruct + instruction: You are a helpful assistant +``` + +Fireworks model IDs use the `accounts/fireworks/models/` form. See the +[Fireworks model library](https://fireworks.ai/models) for current IDs. + +## Google Gemini + +Google provides the Gemini family of models. + +To get an API key: + +1. Go to [aistudio.google.com/apikey](https://aistudio.google.com/apikey). +2. Sign in with your Google account. +3. Create an API key. +4. Copy the key. + +Set your API key as an environment variable: + +```console +$ export GOOGLE_API_KEY=your_key_here +``` + +Use Gemini models in your agent configuration: + +```yaml +agents: + root: + model: google/gemini-2.5-flash + instruction: You are a helpful coding assistant +``` + +Available models include: + +- `google/gemini-2.5-flash` +- `google/gemini-2.5-pro` + +## Groq + +[Groq](https://groq.com/) serves open-weight models on its LPU inference engine +through an OpenAI-compatible API, with a focus on very low latency. + +1. Create an API key from the [Groq Console](https://console.groq.com/keys). +2. Set the environment variable: + +```console +$ export GROQ_API_KEY=your_key_here +``` + +Use Groq models in your agent configuration: + +```yaml +agents: + root: + model: groq/llama-3.3-70b-versatile + instruction: You are a helpful assistant +``` + +Available models include `llama-3.3-70b-versatile`, `llama-3.1-8b-instant`, and +more. See the [Groq models documentation](https://console.groq.com/docs/models) +for current model IDs. + +## Moonshot AI + +[Moonshot AI](https://www.moonshot.ai/) serves its Kimi model family through an +OpenAI-compatible API. Kimi K2 models are well-suited for coding and agentic +tasks. + +1. Create an API key from the [Moonshot AI console](https://platform.moonshot.ai/console/api-keys). +2. Set the environment variable: + +```console +$ export MOONSHOT_API_KEY=your_key_here +``` + +Use Moonshot AI models in your agent configuration: + +```yaml +agents: + root: + model: moonshot/kimi-k2-0905-preview + instruction: You are a helpful assistant +``` + +Available models include: + +- `moonshot/kimi-k2-0905-preview` +- `moonshot/kimi-k2-turbo-preview` +- `moonshot/kimi-k2-thinking` + +## OpenAI + +OpenAI provides the GPT family of models, including GPT-5 and GPT-5 mini. + +To get an API key: + +1. Go to [platform.openai.com/api-keys](https://platform.openai.com/api-keys). +2. Sign up or sign in to your account. +3. Navigate to the API Keys section. +4. Create a new API key. +5. Copy the key. + +Set your API key as an environment variable: + +```console +$ export OPENAI_API_KEY=your_key_here +``` + +Use OpenAI models in your agent configuration: + +```yaml +agents: + root: + model: openai/gpt-5 + instruction: You are a helpful coding assistant +``` + +Available models include: + +- `openai/gpt-5` +- `openai/gpt-5-mini` + +## OpenRouter + +[OpenRouter](https://openrouter.ai/) provides access to hundreds of models from +many providers through a single OpenAI-compatible API, with automatic failover +and unified billing. + +1. Get an API key from [OpenRouter](https://openrouter.ai/settings/keys). +2. Set the environment variable: + +```console +$ export OPENROUTER_API_KEY=your_key_here +``` + +Use OpenRouter in your agent configuration: + +```yaml +agents: + root: + model: openrouter/meta-llama/llama-3.3-70b-instruct + instruction: You are a helpful assistant +``` + +OpenRouter model IDs include the upstream provider name (for example +`anthropic/claude-sonnet-4-5` or `meta-llama/llama-3.3-70b-instruct`). Docker +Agent preserves the full upstream model ID after the first slash. See the +[OpenRouter models list](https://openrouter.ai/models) for available models. + +## OVHcloud + +[OVHcloud AI Endpoints](https://endpoints.ai.cloud.ovh.net/) serves open-weight +models through an OpenAI-compatible API, hosted in the EU. Several models are +available on a rate-limited free tier with no billing setup required. + +1. Create an access token from the + [OVHcloud AI Endpoints portal](https://endpoints.ai.cloud.ovh.net/). +2. Set the environment variable: + +```console +$ export OVH_AI_ENDPOINTS_ACCESS_TOKEN=your_token_here +``` + +Use OVHcloud models in your agent configuration: + +```yaml +agents: + root: + model: ovhcloud/Qwen3.5-397B-A17B + instruction: You are a helpful assistant +``` + +Available models include `Qwen3.5-397B-A17B`, `Qwen3-32B`, +`Meta-Llama-3_3-70B-Instruct`, and more. See the +[AI Endpoints catalogue](https://endpoints.ai.cloud.ovh.net/) for current model +IDs. + +## Together AI + +[Together AI](https://www.together.ai/) is one of the largest hosts of +open-weight models, serving Llama, Qwen, DeepSeek, Kimi, GLM, and others +through an OpenAI-compatible API. + +1. Create an API key from the [Together AI settings](https://api.together.ai/settings/api-keys). +2. Set the environment variable: + +```console +$ export TOGETHER_API_KEY=your_key_here +``` + +Use Together AI models in your agent configuration: + +```yaml +agents: + root: + model: together/meta-llama/Llama-3.3-70B-Instruct-Turbo + instruction: You are a helpful assistant +``` + +See the [Together AI model library](https://docs.together.ai/docs/serverless-models) +for current model IDs. + +## Vercel AI Gateway + +[Vercel AI Gateway](https://vercel.com/docs/ai-gateway) is a unified +OpenAI-compatible endpoint that routes to models from OpenAI, Anthropic, Google, +xAI, and more at list price with no markup. + +1. Create an API key from the [Vercel AI Gateway dashboard](https://vercel.com/docs/ai-gateway). +2. Set the environment variable: + +```console +$ export AI_GATEWAY_API_KEY=your_key_here +``` + +Use Vercel AI Gateway in your agent configuration: + +```yaml +agents: + root: + model: vercel/openai/gpt-5 + instruction: You are a helpful assistant +``` + +Vercel AI Gateway model IDs use the `creator/model` form (for example +`openai/gpt-5` or `anthropic/claude-sonnet-4.5`). See the +[Vercel AI Gateway documentation](https://vercel.com/docs/ai-gateway) for the +current model list. + +## OpenAI-compatible providers + +You can use the `openai` provider type to connect to any model or provider that +implements the OpenAI API specification. This includes services like Azure +OpenAI, local inference servers, and other compatible endpoints. + +Define a named model in the `models` section with the `openai` provider and a +`base_url`, then reference it from your agent: + +```yaml +models: + my-model: + provider: openai + model: your-model-name + base_url: https://your-provider.example.com/v1 + +agents: + root: + model: my-model + instruction: You are a helpful coding assistant +``` + +By default, Docker Agent uses the `OPENAI_API_KEY` environment variable for +authentication. If your provider uses a different variable, specify it with +`token_key`: + +```yaml +models: + my-model: + provider: openai + model: your-model-name + base_url: https://your-provider.example.com/v1 + token_key: YOUR_PROVIDER_API_KEY + +agents: + root: + model: my-model + instruction: You are a helpful coding assistant +``` + +## What's next + +- Follow the [tutorial](tutorial.md) to build your first agent +- Learn about [local models with Docker Model Runner](local-models.md) as an + alternative to cloud providers +- Review the [configuration reference](reference/config.md) for advanced model + settings diff --git a/content/manuals/ai/docker-agent/reference/config.md b/content/manuals/ai/docker-agent/reference/config.md new file mode 100644 index 00000000000..70e5ea56ecc --- /dev/null +++ b/content/manuals/ai/docker-agent/reference/config.md @@ -0,0 +1,695 @@ +--- +title: Configuration file reference +linkTitle: Configuration file +description: Complete reference for the Docker Agent YAML configuration file format +keywords: [ai, agent, cagent, configuration, yaml] +weight: 10 +--- + +This reference documents the YAML configuration file format for agents using Docker Agent. +It covers file structure, agent parameters, model configuration, toolset setup, +and RAG sources. + +For detailed documentation of each toolset's capabilities and specific options, +see the [Toolsets reference](./toolsets.md). + +## File structure + +A configuration file has four top-level sections: + +```yaml +agents: # Required - agent definitions + root: + model: anthropic/claude-sonnet-4-5 + description: What this agent does + instruction: How it should behave + +models: # Optional - model configurations + custom_model: + provider: openai + model: gpt-5 + +rag: # Optional - RAG sources + docs: + docs: [./documents] + strategies: [...] + +metadata: # Optional - author, license, readme, version, tags + author: Your Name +``` + +## Agents + +| Property | Type | Description | Required | +| ---------------------- | ------- | ---------------------------------------------- | -------- | +| `model` | string | Model reference or name | Yes | +| `description` | string | Brief description of agent's purpose | No | +| `instruction` | string | Detailed behavior instructions | Yes | +| `sub_agents` | array | Agent names for task delegation | No | +| `handoffs` | array | Agent names for conversation handoff | No | +| `toolsets` | array | Available tools | No | +| `welcome_message` | string | Message displayed on start | No | +| `add_date` | boolean | Include current date in context | No | +| `add_environment_info` | boolean | Include working directory, OS, Git info | No | +| `add_prompt_files` | array | Prompt file paths to include | No | +| `max_iterations` | integer | Maximum tool call loops (unlimited if not set) | No | +| `num_history_items` | integer | Conversation history limit | No | +| `code_mode_tools` | boolean | Enable Code Mode for tools | No | +| `commands` | object | Named prompts accessible via `/command_name` | No | +| `structured_output` | object | JSON schema for structured responses | No | +| `rag` | array | RAG source names | No | + +### Task delegation versus conversation handoff + +Agents support two different delegation mechanisms. Choose based on whether you +need task results or conversation control. + +#### Sub_agents: Hierarchical task delegation + +Use `sub_agents` for hierarchical task delegation. The parent agent assigns a +specific task to a child agent using the `transfer_task` tool. The child +executes in its own context and returns results. The parent maintains control +and can delegate to multiple agents in sequence. + +This works well for structured workflows where you need to combine results from +specialists, or when tasks have clear boundaries. Each delegated task runs +independently and reports back to the parent. + +**Example:** + +```yaml +agents: + root: + sub_agents: [researcher, analyst] + instruction: | + Delegate research to researcher. + Delegate analysis to analyst. + Combine results and present findings. +``` + +Root calls: `transfer_task(agent="researcher", task="Find pricing data")`. The +researcher completes the task and returns results to root. + +#### Handoffs: Conversation transfer + +Use `handoffs` to transfer conversation control to a different agent. When an +agent uses the `handoff` tool, the new agent takes over completely. The +original agent steps back until someone hands back to it. + +This works well when different agents should own different parts of an ongoing +conversation, or when specialists need to collaborate as peers without a +coordinator managing every step. + +**Example:** + +```yaml +agents: + generalist: + handoffs: [database_expert, security_expert] + instruction: | + Help with general development questions. + If the conversation moves to database optimization, + hand off to database_expert. + If security concerns arise, hand off to security_expert. + + database_expert: + handoffs: [generalist, security_expert] + instruction: Handle database design and optimization. + + security_expert: + handoffs: [generalist, database_expert] + instruction: Review code for security vulnerabilities. +``` + +When the user asks about query performance, generalist executes: +`handoff(agent="database_expert")`. The database expert now owns the +conversation and can continue working with the user directly, or hand off to +security_expert if the discussion shifts to SQL injection concerns. + +### Commands + +Named prompts users invoke with `/command_name`. Supports JavaScript template +literals with `${env.VARIABLE}` for environment variables: + +```yaml +commands: + greet: "Say hello to ${env.USER}" + analyze: "Analyze ${env.PROJECT_NAME || 'demo'}" +``` + +Run with: `docker agent run config.yaml /greet` + +### Structured output + +Constrain responses to a JSON schema (OpenAI and Gemini only): + +```yaml +structured_output: + name: code_analysis + strict: true + schema: + type: object + properties: + issues: + type: array + items: { ... } + required: [issues] +``` + +## Models + +| Property | Type | Description | Required | +| --------------------- | ------- | ---------------------------------------------- | -------- | +| `provider` | string | `openai`, `anthropic`, `google`, `dmr` | Yes | +| `model` | string | Model name | Yes | +| `temperature` | float | Randomness (0.0-2.0) | No | +| `max_tokens` | integer | Maximum response length | No | +| `top_p` | float | Nucleus sampling (0.0-1.0) | No | +| `frequency_penalty` | float | Repetition penalty (-2.0 to 2.0, OpenAI only) | No | +| `presence_penalty` | float | Topic penalty (-2.0 to 2.0, OpenAI only) | No | +| `base_url` | string | Custom API endpoint | No | +| `parallel_tool_calls` | boolean | Enable parallel tool execution (default: true) | No | +| `token_key` | string | Authentication token key | No | +| `track_usage` | boolean | Track token usage | No | +| `thinking_budget` | mixed | Reasoning effort (provider-specific) | No | +| `compaction_model` | string | Model to use for session compaction (summary generation); defaults to the agent's own model | No | +| `bypass_models_gateway` | boolean | Connect directly to the provider, bypassing any configured models gateway | No | +| `provider_opts` | object | Provider-specific options | No | + +### Alloy models + +Use multiple models in rotation by separating names with commas: + +```yaml +model: anthropic/claude-sonnet-4-5,openai/gpt-5 +``` + +### Compaction model + +By default, when a session is compacted (via `/compact`, the proactive +threshold trigger, or post-overflow recovery), Docker Agent uses the agent's +own model to summarize the conversation. That summary call ingests the entire +conversation and is the slowest, most expensive call in a session. + +You can point `compaction_model` at a smaller, faster model to make compaction +cheaper without changing the model that runs the conversation: + +```yaml +models: + primary: + provider: anthropic + model: claude-sonnet-4-5 + compaction_model: fast # use the cheaper model for compaction + fast: + provider: anthropic + model: claude-haiku-4-5 + +agents: + root: + model: primary + instruction: You are a helpful assistant. +``` + +The value can be a model name from the `models` section or an inline +`provider/model` spec (for example `openai/gpt-5-mini`). When omitted, +compaction reuses the agent's own model. + +> [!NOTE] +> If the compaction model has a smaller context window than the primary model, +> Docker Agent triggers compaction against the smaller window, so the summary +> call can always ingest the full conversation. Pair the primary with a +> compaction model whose context window is at least as large to keep the +> proactive trigger aligned with the primary's window. + +### Bypass models gateway + +When a models gateway is configured (via `--models-gateway` or +`CAGENT_MODELS_GATEWAY`), Docker Agent routes all model requests through it by +default. Set `bypass_models_gateway: true` on a specific model to make it +connect directly to its provider instead: + +```yaml +models: + # Routed through the gateway when one is configured. + gateway-model: + provider: openai + model: gpt-5 + + # Always connects directly to Anthropic, even when a gateway is configured. + # Requires ANTHROPIC_API_KEY to be set. + direct-model: + provider: anthropic + model: claude-sonnet-4-5 + bypass_models_gateway: true + +agents: + root: + model: direct-model + instruction: You are a helpful assistant. +``` + +A bypassed model authenticates with its own provider credentials +(`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or the explicit `token_key`) rather +than the gateway's token. + +### Thinking budget + +Controls reasoning depth. Configuration varies by provider: + +- **OpenAI**: String values - `minimal`, `low`, `medium`, `high` +- **Anthropic**: Integer token budget (1024-32768, must be less than + `max_tokens`) + - Set `provider_opts.interleaved_thinking: true` for tool use during reasoning +- **Gemini**: Integer token budget (0 to disable, -1 for dynamic, max 24576) + - Gemini 2.5 Pro: 128-32768, cannot disable (minimum 128) + +```yaml +# OpenAI +thinking_budget: low + +# Anthropic +thinking_budget: 8192 +provider_opts: + interleaved_thinking: true + +# Gemini +thinking_budget: 8192 # Fixed +thinking_budget: -1 # Dynamic +thinking_budget: 0 # Disabled +``` + +### Docker Model Runner (DMR) + +Run local models. If `base_url` is omitted, Docker Agent auto-discovers via Docker +Model plugin. + +```yaml +provider: dmr +model: ai/qwen3 +max_tokens: 8192 +base_url: http://localhost:12434/engines/llama.cpp/v1 # Optional +``` + +Pass llama.cpp options via `provider_opts.runtime_flags` (array, string, or +multiline): + +```yaml +provider_opts: + runtime_flags: ["--ngl=33", "--threads=8"] + # or: runtime_flags: "--ngl=33 --threads=8" +``` + +Model config fields auto-map to runtime flags: + +- `temperature` → `--temp` +- `top_p` → `--top-p` +- `max_tokens` → `--context-size` + +Explicit `runtime_flags` override auto-mapped flags. + +Speculative decoding for faster inference: + +```yaml +provider_opts: + speculative_draft_model: ai/qwen3:0.6B-F16 + speculative_num_tokens: 16 + speculative_acceptance_rate: 0.8 +``` + +## Tools + +Configure tools in the `toolsets` array. Three types: built-in, MCP +(local/remote), and Docker Gateway. + +> [!NOTE] This section covers toolset configuration syntax. For detailed +> documentation of each toolset's capabilities, available tools, and specific +> configuration options, see the [Toolsets reference](./toolsets.md). + +All toolsets support common properties like `tools` (whitelist), `defer` +(deferred loading), `toon` (output compression), `env` (environment variables), +and `instruction` (usage guidance). See the [Toolsets reference](./toolsets.md) +for details on these properties and what each toolset does. + +### Built-in tools + +```yaml +toolsets: + - type: filesystem + - type: shell + - type: think + - type: todo + shared: true + - type: memory + path: ./memory.db +``` + +### MCP tools + +Local process: + +```yaml +- type: mcp + command: npx + args: + ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"] + tools: ["read_file", "write_file"] # Optional: limit to specific tools + env: + NODE_OPTIONS: "--max-old-space-size=8192" +``` + +Remote server: + +```yaml +- type: mcp + remote: + url: https://mcp-server.example.com + transport_type: sse + headers: + Authorization: Bearer token +``` + +### Docker MCP Gateway + +Containerized tools from [Docker MCP +Catalog](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md): + +```yaml +- type: mcp + ref: docker:duckduckgo +``` + +## RAG + +Retrieval-augmented generation for document knowledge bases. Define sources at +the top level, reference in agents. + +```yaml +rag: + docs: + docs: [./documents, ./README.md] + strategies: + - type: chunked-embeddings + embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 + database: ./embeddings.db + +agents: + root: + rag: [docs] +``` + +### Retrieval strategies + +All strategies support chunking configuration. Chunk size and overlap are +measured in characters (Unicode code points), not tokens. + +#### Chunked-embeddings + +Direct semantic search using vector embeddings. Best for understanding intent, +synonyms, and paraphrasing. + +| Field | Type | Default | +| ---------------------------------- | ------- | ------- | +| `embedding_model` | string | - | +| `database` | string | - | +| `vector_dimensions` | integer | - | +| `similarity_metric` | string | cosine | +| `threshold` | float | 0.5 | +| `limit` | integer | 5 | +| `chunking.size` | integer | 1000 | +| `chunking.overlap` | integer | 75 | +| `chunking.respect_word_boundaries` | boolean | true | +| `chunking.code_aware` | boolean | false | + +```yaml +- type: chunked-embeddings + embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 + database: ./vector.db + similarity_metric: cosine_similarity + threshold: 0.5 + limit: 10 + chunking: + size: 1000 + overlap: 100 +``` + +#### Semantic-embeddings + +LLM-enhanced semantic search. Uses a language model to generate rich semantic +summaries of each chunk before embedding, capturing deeper meaning. Best for complex documents where context and relationships between concepts matter. + +| Field | Type | Default | +| ---------------------------------- | ------- | ------- | +| `embedding_model` | string | - | +| `chat_model` | string | - | +| `database` | string | - | +| `vector_dimensions` | integer | - | +| `similarity_metric` | string | cosine | +| `threshold` | float | 0.5 | +| `limit` | integer | 5 | +| `ast_context` | boolean | false | +| `semantic_prompt` | string | - | +| `chunking.size` | integer | 1000 | +| `chunking.overlap` | integer | 75 | +| `chunking.respect_word_boundaries` | boolean | true | +| `chunking.code_aware` | boolean | false | + +```yaml +- type: semantic-embeddings + embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 + chat_model: openai/gpt-5-mini + database: ./semantic.db + threshold: 0.3 + limit: 10 + chunking: + size: 1000 + overlap: 100 +``` + +#### BM25 + +Keyword-based search using BM25 algorithm. Best for exact terms, technical +jargon, and code identifiers. + +| Field | Type | Default | +| ---------------------------------- | ------- | ------- | +| `database` | string | - | +| `k1` | float | 1.5 | +| `b` | float | 0.75 | +| `threshold` | float | 0.0 | +| `limit` | integer | 5 | +| `chunking.size` | integer | 1000 | +| `chunking.overlap` | integer | 75 | +| `chunking.respect_word_boundaries` | boolean | true | +| `chunking.code_aware` | boolean | false | + +```yaml +- type: bm25 + database: ./bm25.db + k1: 1.5 + b: 0.75 + threshold: 0.3 + limit: 10 + chunking: + size: 1000 + overlap: 100 +``` + +### Hybrid retrieval + +Combine multiple strategies with fusion: + +```yaml +strategies: + - type: chunked-embeddings + embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 + database: ./vector.db + limit: 20 + - type: bm25 + database: ./bm25.db + limit: 15 + +results: + fusion: + strategy: rrf # Options: rrf, weighted, max + k: 60 # RRF smoothing parameter + deduplicate: true + limit: 5 +``` + +Fusion strategies: + +- `rrf`: Reciprocal Rank Fusion (recommended, rank-based, no normalization + needed) +- `weighted`: Weighted combination (`fusion.weights: {chunked-embeddings: 0.7, +bm25: 0.3}`) +- `max`: Maximum score across strategies + +### Reranking + +Re-score results with a specialized model for improved relevance: + +```yaml +results: + reranking: + model: openai/gpt-5-mini + top_k: 10 # Only rerank top K (0 = all) + threshold: 0.3 # Minimum score after reranking + criteria: | # Optional domain-specific guidance + Prioritize official docs over blog posts + limit: 5 +``` + +DMR native reranking: + +```yaml +models: + reranker: + provider: dmr + model: hf.co/ggml-org/qwen3-reranker-0.6b-q8_0-gguf + +results: + reranking: + model: reranker +``` + +### Code-aware chunking + +For source code, use AST-based chunking. With semantic-embeddings, you can +include AST metadata in the LLM prompts: + +```yaml +- type: semantic-embeddings + embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 + chat_model: openai/gpt-5-mini + database: ./code.db + ast_context: true # Include AST metadata in semantic prompts + chunking: + size: 2000 + code_aware: true # Enable AST-based chunking +``` + +### RAG properties + +Top-level RAG source: + +| Field | Type | Description | +| ------------ | -------- | --------------------------------------------------------------- | +| `docs` | []string | Document paths (supports glob patterns, respects `.gitignore`) | +| `tool` | object | Customize RAG tool name/description/instruction | +| `strategies` | []object | Retrieval strategies (see above for strategy-specific fields) | +| `results` | object | Post-processing (fusion, reranking, limits) | + +Results: + +| Field | Type | Default | +| --------------------- | ------- | ------- | +| `limit` | integer | 15 | +| `deduplicate` | boolean | true | +| `include_score` | boolean | false | +| `fusion.strategy` | string | - | +| `fusion.k` | integer | 60 | +| `fusion.weights` | object | - | +| `reranking.model` | string | - | +| `reranking.top_k` | integer | 0 | +| `reranking.threshold` | float | 0.5 | +| `reranking.criteria` | string | "" | +| `return_full_content` | boolean | false | + +## Metadata + +Documentation and sharing information: + +| Property | Type | Description | +| --------- | -------- | ----------------------------------------- | +| `author` | string | Author name | +| `license` | string | License (e.g., MIT, Apache-2.0) | +| `readme` | string | Usage documentation | +| `version` | string | Semantic version string | +| `tags` | []string | Tags for categorization and discovery | + +```yaml +metadata: + author: Your Name + license: MIT + version: "1.0.0" + tags: [coding, review] + readme: | + Description and usage instructions +``` + +## Example configuration + +Complete configuration demonstrating key features: + +```yaml +agents: + root: + model: claude + description: Technical lead + instruction: Coordinate development tasks and delegate to specialists + sub_agents: [developer, reviewer] + toolsets: + - type: filesystem + - type: mcp + ref: docker:duckduckgo + rag: [readmes] + commands: + status: "Check project status" + + developer: + model: gpt + description: Software developer + instruction: Write clean, maintainable code + toolsets: + - type: filesystem + - type: shell + + reviewer: + model: claude + description: Code reviewer + instruction: Review for quality and security + toolsets: + - type: filesystem + +models: + gpt: + provider: openai + model: gpt-5 + + claude: + provider: anthropic + model: claude-sonnet-4-5 + max_tokens: 64000 + +rag: + readmes: + docs: ["**/README.md"] + strategies: + - type: chunked-embeddings + embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 + database: ./embeddings.db + limit: 10 + - type: bm25 + database: ./bm25.db + limit: 10 + results: + fusion: + strategy: rrf + k: 60 + limit: 5 +``` + +## What's next + +- Read the [Toolsets reference](./toolsets.md) for detailed toolset + documentation +- Review the [CLI reference](./cli.md) for command-line options +- Browse [example + configurations](https://github.com/docker/docker-agent/tree/main/examples) +- Learn about [sharing agents](../sharing-agents.md) From 0c8afc58964cf5accb5e02c43d69f37d771fcf7c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Mon, 13 Jul 2026 04:11:30 +0000 Subject: [PATCH 2/2] docs: update docs for docker/docker-agent#3611 Document the new TUI agent delegation feedback UI: - Transfer box: animated sidebar box during transfer_task delegation - Return box: reverse-direction animation when control returns to parent - Chat transition: non-persisted return transition line in message stream --- .../docker-agent/docs/features/tui/index.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) 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 922b1105958..c42809206d3 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md @@ -136,6 +136,36 @@ The **effort gauge** is a fixed-width six-cell indicator (`▰` filled, `▱` em Harness-backed agents (e.g. `claude-code`) show the harness type as their model and no thinking gauge. Press **Shift+Tab** to cycle the current model's thinking-effort level; a `✻ Thinking: ` toast confirms the change (useful when the sidebar is hidden). +### Agent Delegation Feedback + +When a parent agent calls `transfer_task` to delegate work to a sub-agent, the TUI provides live visual feedback in both the sidebar and the chat. + +**Sidebar — Transfer box:** As soon as the delegation starts, an animated **Transfer** box appears below the agent roster, showing the direction of the handoff with a traveling dot: + +```text +╭─ Transfer ─────────────────╮ +│ parent ●──────► child │ +╰────────────────────────────╯ +``` + +The box stays visible for at least 1.5 seconds. Once the sub-agent produces its first message, reasoning, or tool output, the box hides (still honoring the minimum window) to keep the sidebar focused on the active agent. If the sub-agent is slow or silent, the box hides after a 3-second maximum cutoff. The header shows a `↔` marker while any delegation is still in flight, even after the box hides. + +**Sidebar — Return box:** When the sub-agent finishes and control returns to the parent, a brief **Return** box animates the reverse direction for up to 1.5 seconds, then disappears: + +```text +╭─ Return ───────────────────╮ +│ child ●──────► parent │ +╰────────────────────────────╯ +``` + +**Chat — return transition:** Alongside the sidebar Return animation, the chat shows a one-line static transition between the two agent badges: + +```text +[child] returned control to [parent] +``` + +This transition is not persisted — it does not reappear when you reload the session. + ### Thinking and Tool Details Reasoning/thinking blocks are collapsed by default and carry a `Thinking` header badge. When collapsed, the TUI shows a short preview and compact tool summaries. Expand a block to see the full thinking content and the real tool renderers, including detailed tool output such as file edit diffs.