diff --git a/.github/workflows/docs-upstream.yml b/.github/workflows/docs-upstream.yml new file mode 100644 index 0000000000..b16f1c5071 --- /dev/null +++ b/.github/workflows/docs-upstream.yml @@ -0,0 +1,33 @@ +# Validates that changes under docs/** still build correctly on +# docs.docker.com, by running docker/docs' reusable validate-upstream +# workflow against this repo's commit (same pattern as buildx/compose). +# +# Until docker/docs mounts the docker-agent Hugo module (phase 2.1 of +# https://github.com/docker/docker-agent/issues/3371), the validation +# builds docs.docker.com without mounting these pages and is a no-op. +name: docs-upstream + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +on: + push: + branches: [main] + paths: + - ".github/workflows/docs-upstream.yml" + - "docs/**" + pull_request: + paths: + - ".github/workflows/docs-upstream.yml" + - "docs/**" + +jobs: + validate: + # Tracks docker/docs main; bump the pin when validation needs newer docs changes. + uses: docker/docs/.github/workflows/validate-upstream.yml@8255e2bd5f08f1645c0ef677598d2c5f0555e336 # main + with: + module-name: docker/docker-agent diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000000..556b15dc22 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,46 @@ +name: docs + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.ref != 'refs/heads/main' }} + +on: + push: + branches: [main] + paths: + - "docs/**" + - ".github/workflows/docs.yml" + pull_request: + paths: + - "docs/**" + - ".github/workflows/docs.yml" + +jobs: + markdownlint: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + + # docs/.markdownlint-cli2.yaml is auto-discovered; passing it via + # `config:` would merge its `**/*.md` globs and lint the whole repo. + - name: Lint Markdown + uses: DavidAnson/markdownlint-cli2-action@992badcdf24e3b8eb7e87ff9287fe931bcb00c6e # v20.0.0 + with: + globs: "docs/**/*.md" + + link-check: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + + - name: Check internal links + uses: lycheeverse/lychee-action@a8c4c7cb88f0c7386610c35eb25108e448569cb0 # v2.7.0 + with: + # 404.md is Jekyll-only and keeps a Liquid href; skip it. + args: --offline --include-fragments --no-progress --root-dir "${{ github.workspace }}/docs" --exclude-path docs/404.md "docs/**/*.md" + fail: true diff --git a/docs/.markdownlint-cli2.yaml b/docs/.markdownlint-cli2.yaml index 9eb58cc204..c66deacafa 100644 --- a/docs/.markdownlint-cli2.yaml +++ b/docs/.markdownlint-cli2.yaml @@ -1,12 +1,13 @@ -# markdownlint configuration for Jekyll docs +# markdownlint configuration for the docs # -# These docs mix Markdown with HTML blocks (callouts, cards, feature grids). -# Rules that conflict with this pattern are disabled. +# The docs are portable Markdown rendered by both Jekyll (github.io) and +# Hugo (docs.docker.com via module mount). Rules that conflict with the +# established docs style are disabled. config: default: true - # Allow inline HTML — callouts, cards, and feature-grids are HTML + # Allow inline HTML — the landing page and a few widgets (, images) use it MD033: false # Don't enforce line length — HTML blocks and tables often exceed 80 chars @@ -15,6 +16,15 @@ config: # Allow multiple top-level headings — front matter title + # Heading is normal MD025: false + # Shell samples deliberately use "$ " prompts (see STYLE.md § Code samples) + MD014: false + + # Adjacent > [!NOTE] alerts are separated by a blank line by design + MD028: false + + # Don't enforce table pipe alignment + MD060: false + # Allow duplicate headings — different sections may reuse heading text MD024: siblings_only: true diff --git a/docs/STYLE.md b/docs/STYLE.md index a378e8aaed..726998448b 100644 --- a/docs/STYLE.md +++ b/docs/STYLE.md @@ -13,6 +13,7 @@ and examples consistent across every page on this site. | Internal identifiers / package names | as defined in code (e.g. `cagent`) — never invent new spellings in prose | mixing internal identifiers into user-facing copy | A simple rule of thumb: + - **Talking about the product?** → "Docker Agent" - **Showing a command the user types?** → `docker agent run agent.yaml` @@ -28,7 +29,7 @@ A simple rule of thumb: ## Code samples -- All shell prompts use `$ ` (dollar + space) and the command on the +- All shell prompts use `$` followed by a space, with the command on the same line. Output, when shown, has no prompt. - YAML/HCL examples should be runnable as-is when reasonable, or end in `# ...` to make truncation explicit. @@ -38,21 +39,34 @@ A simple rule of thumb: ## Callouts -Use the existing pattern; the new visual style does the rest: +Use GitHub-style alerts — they render natively on docs.docker.com and +are upgraded to the styled callout panels on github.io: ```markdown -
-
When to use it
-

Body text.

-
+> [!TIP] +> **When to use it**: Body text. ``` -- `callout-info` — neutral context -- `callout-tip` — positive, "consider this" -- `callout-warning` — caution, breaking, security +- `[!NOTE]` — neutral context +- `[!TIP]` — positive, "consider this" +- `[!WARNING]` — caution, breaking, security + +An optional bold lead-in (`**Title**:`) names the callout; skip it when +the kind alone says enough. Don't prefix it with an emoji — the icon +badge already provides one. + +## Links + +Use plain relative Markdown links between pages, including the +`index.md` filename, so both renderers resolve them. From a page two +levels deep (e.g. `concepts/agents/index.md`): + +```markdown +See [Models](../../concepts/models/index.md) for details. +``` -Don't prefix the title with an emoji — the icon badge already provides -one. +Never use Liquid (`relative_url`) or root-absolute paths — they break +when the docs are mounted on docs.docker.com. ## Glossary one-liners diff --git a/docs/community/contributing/index.md b/docs/community/contributing/index.md index a08a268ab7..e37cef6b3e 100644 --- a/docs/community/contributing/index.md +++ b/docs/community/contributing/index.md @@ -1,7 +1,7 @@ --- title: "Contributing" description: "docker-agent is open source. Here's how to set up your development environment and contribute." -permalink: /community/contributing/ +keywords: docker agent, ai agents, community, contributing --- # Contributing @@ -17,12 +17,8 @@ _docker-agent is open source. Here's how to set up your development environment - [Task](https://taskfile.dev/installation/) - [golangci-lint](https://golangci-lint.run/docs/welcome/install/local/) -
-
Platform Support -
-

macOS and Linux are fully supported for development. On Windows, use task build-local to build via Docker.

- -
+> [!NOTE] +> **Platform Support**: macOS and Linux are fully supported for development. On Windows, use `task build-local` to build via Docker. ### Build from Source @@ -86,12 +82,8 @@ Key conventions: File issues on the [GitHub issue tracker](https://github.com/docker/docker-agent/issues). Please: -
-
See also -
- Troubleshooting — Common issues and debug mode. Telemetry — What data is collected and how to opt out. - -
+> [!NOTE] +> **See also**: [Troubleshooting](../troubleshooting/index.md) — Common issues and debug mode. [Telemetry](../telemetry/index.md) — What data is collected and how to opt out. - Use the included issue template - Search for existing issues before creating new ones @@ -105,12 +97,8 @@ File issues on the [GitHub issue tracker](https://github.com/docker/docker-agent 4. **Sign** your commits with `git commit -s` (DCO required) 5. **Open a pull request** against the `main` branch -
-
Tip -
-

Use the dogfooding agent (docker agent run ./golang_developer.yaml) to help write and review your changes before submitting.

- -
+> [!TIP] +> Use the dogfooding agent (`docker agent run ./golang_developer.yaml`) to help write and review your changes before submitting. ## Sign Your Work diff --git a/docs/community/opentelemetry/index.md b/docs/community/opentelemetry/index.md index 49eb98d2ff..bfe59f4767 100644 --- a/docs/community/opentelemetry/index.md +++ b/docs/community/opentelemetry/index.md @@ -1,12 +1,12 @@ --- title: "OpenTelemetry Tracing" description: "Export docker-agent traces to any OTLP backend, including Langfuse and LangSmith, for debugging agentic workflows." -permalink: /community/opentelemetry/ +keywords: docker agent, ai agents, community, opentelemetry tracing --- # OpenTelemetry Tracing -_docker-agent can export OpenTelemetry traces of an agent run to any OTLP/HTTP backend. This is separate from [product-analytics telemetry](/community/telemetry/) and is opt-in via the `--otel` flag._ +_docker-agent can export OpenTelemetry traces of an agent run to any OTLP/HTTP backend. This is separate from [product-analytics telemetry](../telemetry/index.md) and is opt-in via the `--otel` flag._ When enabled, docker-agent emits OpenTelemetry GenAI (`gen_ai.*`) and MCP (`mcp.*`) spans following the [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). Spans cover the agent turn, model calls (with token usage and cost attributes), tool calls, MCP client/server activity, sub-agent hand-offs, and provider fallbacks. W3C `traceparent` context is propagated so the whole run renders as a single connected trace tree. @@ -29,19 +29,13 @@ docker-agent reads the standard OTLP environment variables: | `OTEL_RESOURCE_ATTRIBUTES` | Extra resource attributes merged into every span. | | `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | Set to `true` to capture prompt and response message content as span attributes. Off by default. | -
-
Base endpoint, not the full signal URL -
-

Set OTEL_EXPORTER_OTLP_ENDPOINT to the base endpoint (for example https://cloud.langfuse.com/api/public/otel). docker-agent appends /v1/traces for you, matching the value documented by Langfuse and LangSmith. A bare host:port is also accepted and gets https:// (or http:// for localhost).

+> [!NOTE] +> **Base endpoint, not the full signal URL**: Set `OTEL_EXPORTER_OTLP_ENDPOINT` to the **base** endpoint (for example `https://cloud.langfuse.com/api/public/otel`). docker-agent appends `/v1/traces` for you, matching the value documented by Langfuse and LangSmith. A bare `host:port` is also accepted and gets `https://` (or `http://` for localhost). -
- -
-
Message content can contain sensitive data -
-

OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT is off by default because chat history routinely contains PII, secrets, and internal documents. Enable it only for backends and environments where exporting that content is acceptable.

- -
+> [!WARNING] +> **Message content can contain sensitive data**: +> +> `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` is off by default because chat history routinely contains PII, secrets, and internal documents. Enable it only for backends and environments where exporting that content is acceptable. ## Backends @@ -89,12 +83,8 @@ export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318" docker agent run agent.yaml --otel ``` -
-
Langfuse and LangSmith ingest traces only -
-

Both backends accept the traces signal only. docker-agent also wires metric and log exporters at the same endpoint, so their periodic exports return 404 against trace-only backends. This is harmless to traces but appears in the debug log. Point a full OTLP collector at the endpoint if you also want metrics and logs.

- -
+> [!NOTE] +> **Langfuse and LangSmith ingest traces only**: Both backends accept the traces signal only. docker-agent also wires metric and log exporters at the same endpoint, so their periodic exports return `404` against trace-only backends. This is harmless to traces but appears in the debug log. Point a full OTLP collector at the endpoint if you also want metrics and logs. ## Inspecting traces locally diff --git a/docs/community/telemetry/index.md b/docs/community/telemetry/index.md index 1a2d5d2116..864aa18375 100644 --- a/docs/community/telemetry/index.md +++ b/docs/community/telemetry/index.md @@ -1,7 +1,7 @@ --- title: "Telemetry" description: "docker-agent collects anonymous usage data to help improve the tool. Telemetry can be disabled at any time." -permalink: /community/telemetry/ +keywords: docker agent, ai agents, community, telemetry --- # Telemetry @@ -20,12 +20,8 @@ $ TELEMETRY_ENABLED=false docker agent run agent.yaml $ export TELEMETRY_ENABLED=false ``` -
-
Default -
-

Telemetry is **enabled by default**. Set TELEMETRY_ENABLED=false to opt out.

- -
+> [!NOTE] +> **Default**: Telemetry is **enabled by default**. Set `TELEMETRY_ENABLED=false` to opt out. ## What's Collected ✅ @@ -43,12 +39,8 @@ $ export TELEMETRY_ENABLED=false - API keys or credentials - Personally identifying information (PII) -
-
See events locally -
-

Use --debug to see telemetry events printed to the debug log without sending them anywhere additional.

- -
+> [!TIP] +> **See events locally**: Use `--debug` to see telemetry events printed to the debug log without sending them anywhere additional. ```bash docker agent run agent.yaml --debug diff --git a/docs/community/troubleshooting/index.md b/docs/community/troubleshooting/index.md index e335175802..42d8a5b088 100644 --- a/docs/community/troubleshooting/index.md +++ b/docs/community/troubleshooting/index.md @@ -1,7 +1,7 @@ --- title: "Troubleshooting" description: "Common issues and how to resolve them when working with docker-agent." -permalink: /community/troubleshooting/ +keywords: docker agent, ai agents, community, troubleshooting --- # Troubleshooting @@ -62,12 +62,8 @@ $ docker agent run config.yaml --debug --log-file ./debug.log $ docker agent run config.yaml --otel ``` -
-
Tip -
-

Always enable --debug when reporting issues. The log file contains detailed traces of API calls, tool executions, and agent interactions.

- -
+> [!TIP] +> Always enable `--debug` when reporting issues. The log file contains detailed traces of API calls, tool executions, and agent interactions. ## Agent Not Responding @@ -137,13 +133,10 @@ MCP tools using stdio transport must complete the initialization handshake befor 3. Check that the MCP server process starts and responds to `initialize` 4. Verify environment variables required by the tool are set (check `env` and `env_file` in the toolset config) -
-
Startup tool-listing timeout -
-

At startup, docker-agent queries each toolset for its tool list. If a toolset does not respond within 10 seconds (e.g. a wedged MCP stdio server that never answers tools/list), that toolset is skipped with a warning and the remaining toolsets load normally. The sidebar resolves showing whichever tools did load — no infinite spinner. Enable --debug to see the warning message, and use /toolset-restart <name> once the server becomes responsive.

-
+> [!NOTE] +> **Startup tool-listing timeout**: At startup, docker-agent queries each toolset for its tool list. If a toolset does not respond within 10 seconds (e.g. a wedged MCP stdio server that never answers `tools/list`), that toolset is skipped with a warning and the remaining toolsets load normally. The sidebar resolves showing whichever tools did load — no infinite spinner. Enable `--debug` to see the warning message, and use `/toolset-restart ` once the server becomes responsive. -If a toolset keeps crashing in a tight loop, tune the [`lifecycle`]({{ '/configuration/tools/#toolset-lifecycle' | relative_url }}) block on the toolset (e.g. raise `backoff.initial`, lower `max_restarts`, or switch to the `best-effort` profile) so a flaky dependency does not amplify into a restart storm. +If a toolset keeps crashing in a tight loop, tune the [`lifecycle`](../../configuration/tools/index.md#toolset-lifecycle) block on the toolset (e.g. raise `backoff.initial`, lower `max_restarts`, or switch to the `best-effort` profile) so a flaky dependency does not amplify into a restart storm. ## Configuration Errors @@ -167,12 +160,8 @@ docker-agent validates config at startup and reports errors with line numbers. C - MCP toolsets need either `command` (stdio), `remote` (Streamable HTTP/SSE), or `ref` (Docker) - Provider names must be one of: `openai`, `anthropic`, `google`, `amazon-bedrock`, `dmr`, etc. -
-
Schema Validation -
-

Use the JSON schema in your editor for real-time config validation and autocompletion.

- -
+> [!NOTE] +> **Schema Validation**: Use the [JSON schema](https://github.com/docker/docker-agent/blob/main/agent-schema.json) in your editor for real-time config validation and autocompletion. ## Session & Connectivity Issues @@ -217,7 +206,7 @@ The API server stores every conversation as a distinct session in the SQLite dat - Check if MCP tools are adding latency (visible in debug logs) - Use the `/cost` command in TUI to see token usage and identify expensive interactions -- For DMR, consider enabling [speculative decoding]({{ '/providers/dmr/' | relative_url }}) for faster inference +- For DMR, consider enabling [speculative decoding](../../providers/dmr/index.md) for faster inference ### Tool resource leaks @@ -251,14 +240,10 @@ When reviewing debug logs, search for these key patterns: | `"Tool call"` | A tool is being executed | | `"Tool call result"` | Tool execution completed | | `"Stream stopped"` | Agent finished processing | -| `HTTP 429` | Rate limiting — consider adding a [fallback model]({{ '/configuration/agents/' | relative_url }}) | +| `HTTP 429` | Rate limiting — consider adding a [fallback model](../../configuration/agents/index.md) | | `context canceled` | Operation was interrupted (timeout or user cancel) | | `[RAG Manager]` | RAG retrieval operations | | `[Reranker]` | Reranking operations | -
-
Still stuck? -
-

If these steps don't resolve your issue, file a bug on the GitHub issue tracker with your debug log attached, or ask on Slack.

- -
+> [!WARNING] +> **Still stuck?** If these steps don't resolve your issue, file a bug on the [GitHub issue tracker](https://github.com/docker/docker-agent/issues) with your debug log attached, or ask on [Slack](https://dockercommunity.slack.com/archives/C09DASHHRU4). diff --git a/docs/concepts/agents/index.md b/docs/concepts/agents/index.md index e7f5fc9a08..c3bb5d6d8d 100644 --- a/docs/concepts/agents/index.md +++ b/docs/concepts/agents/index.md @@ -1,7 +1,7 @@ --- title: "Agents" description: "Agents are the core building blocks of docker-agent. Each agent is an AI-powered entity with a model, instructions, tools, and optional sub-agents." -permalink: /concepts/agents/ +keywords: docker agent, ai agents, concepts, agents --- # Agents @@ -12,7 +12,7 @@ _Agents are the core building blocks of docker-agent. Each agent is an AI-powere An agent in docker-agent is defined by: -- **Model** — The AI model powering it (e.g., Claude, GPT-5, Gemini). See [Models]({{ '/concepts/models/' | relative_url }}). +- **Model** — The AI model powering it (e.g., Claude, GPT-5, Gemini). See [Models](../models/index.md). - **Description** — A brief summary of what the agent does (used by other agents for delegation) - **Instruction** — The system prompt that defines the agent's behavior and personality - **Tools** — Capabilities like filesystem access, shell commands, or external APIs @@ -36,12 +36,8 @@ agents: Every docker-agent configuration has a **root agent** — the entry point that receives user messages. In a single-agent setup, this is the only agent. In a multi-agent setup, the root agent acts as a coordinator, delegating tasks to specialized sub-agents. -
-
Naming -
-

The first agent defined in your YAML (or the one named root) is the root agent by default. You can also specify which agent to start with using docker agent run config.yaml -a agent_name.

- -
+> [!NOTE] +> **Naming**: The first agent defined in your YAML (or the one named `root`) is the root agent by default. You can also specify which agent to start with using `docker agent run config.yaml -a agent_name`. ## Agent Properties @@ -110,9 +106,5 @@ $ docker agent alias add default /path/to/my-agent.yaml $ docker agent run # now runs your custom agent ``` -
-
See also -
-

For reusable task-specific instructions, see Skills. For multi-agent patterns, see Multi-Agent. For full config reference, see Agent Config.

- -
+> [!TIP] +> **See also**: For reusable task-specific instructions, see [Skills](../../features/skills/index.md). For multi-agent patterns, see [Multi-Agent](../multi-agent/index.md). For full config reference, see [Agent Config](../../configuration/agents/index.md). diff --git a/docs/concepts/distribution/index.md b/docs/concepts/distribution/index.md index 4d77b22111..cd2286e7eb 100644 --- a/docs/concepts/distribution/index.md +++ b/docs/concepts/distribution/index.md @@ -1,7 +1,7 @@ --- title: "Agent Distribution" description: "Package, share, and run agents via OCI-compatible registries — just like container images." -permalink: /concepts/distribution/ +keywords: docker agent, ai agents, concepts, agent distribution --- # Agent Distribution @@ -12,12 +12,8 @@ _Package, share, and run agents via OCI-compatible registries — just like cont docker-agent agents can be pushed to any OCI-compatible registry (Docker Hub, GitHub Container Registry, etc.) and pulled/run anywhere. This makes sharing agents as easy as sharing Docker images. -
-
Tip -
-

For CLI commands related to distribution, see CLI Reference (docker agent share push, docker agent share pull, docker agent alias).

- -
+> [!TIP] +> For CLI commands related to distribution, see [CLI Reference](../../features/cli/index.md) (`docker agent share push`, `docker agent share pull`, `docker agent alias`). ## Pushing Agents @@ -85,7 +81,7 @@ External sub-agents are automatically named after their last path segment. Use t Tag references are checked against the registry on every `docker agent run`, which adds a network round-trip per sub-agent at startup. Pin them to a digest (`agentcatalog/pirate@sha256:…`) to serve them from cache instead. -See [Pin external sub-agents to a digest]({{ '/concepts/multi-agent/#pin-external-sub-agents-to-a-digest' | relative_url }}) and [External Sub-Agents]({{ '/concepts/multi-agent/#external-sub-agents-from-registries' | relative_url }}) for details. +See [Pin external sub-agents to a digest](../multi-agent/index.md#pin-external-sub-agents-to-a-digest) and [External Sub-Agents](../multi-agent/index.md#external-sub-agents-from-registries) for details. ## Using with Aliases @@ -121,19 +117,13 @@ $ docker agent share push ./agent.yaml docker.io/myorg/private-agent:latest $ docker agent run docker.io/myorg/private-agent:latest ``` -
-
Docker Desktop credentials -
-

When pulling or running an agent from a docker.com or *.docker.com HTTPS URL (e.g. desktop.docker.com), docker-agent automatically forwards your Docker Desktop JWT for authentication — no explicit login required when Docker Desktop is running and signed in.

-

Note: docker.io (the standard Docker Hub registry domain) is a separate domain and is not covered by automatic JWT forwarding. Agents pulled from docker.io or registry-1.docker.io still require docker login docker.io for private repositories.

-
- -
-
Troubleshooting -
-

Having issues with push/pull? See Troubleshooting for common registry issues.

+> [!NOTE] +> **Docker Desktop credentials**: When pulling or running an agent from a `docker.com` or `*.docker.com` HTTPS URL (e.g. `desktop.docker.com`), docker-agent automatically forwards your Docker Desktop JWT for authentication — no explicit login required when Docker Desktop is running and signed in. +> +> Note: `docker.io` (the standard Docker Hub registry domain) is a separate domain and is **not** covered by automatic JWT forwarding. Agents pulled from `docker.io` or `registry-1.docker.io` still require `docker login docker.io` for private repositories. -
+> [!NOTE] +> **Troubleshooting**: Having issues with push/pull? See [Troubleshooting](../../community/troubleshooting/index.md) for common registry issues. ## Local Development diff --git a/docs/concepts/models/index.md b/docs/concepts/models/index.md index 8ff8eecc5f..f52dd04951 100644 --- a/docs/concepts/models/index.md +++ b/docs/concepts/models/index.md @@ -1,7 +1,7 @@ --- title: "Models" description: "Models are the AI brains behind your agents. docker-agent supports multiple providers and flexible configuration." -permalink: /concepts/models/ +keywords: docker agent, ai agents, concepts, models --- # Models @@ -65,7 +65,7 @@ agents: At load time, docker-agent selects the first candidate whose credentials are configured. You only need credentials for one candidate. See -[Model Configuration]({{ '/configuration/models/#first-available-models' | relative_url }}) +[Model Configuration](../../configuration/models/index.md#first-available-models) for details. ## Supported Providers @@ -99,7 +99,7 @@ for details. | Ollama | `ollama` | Any local Ollama model | None (local; optional `base_url`) | | GitHub Copilot | `github-copilot` | Copilot-hosted OpenAI/Anthropic | `GITHUB_TOKEN` (PAT with `copilot`) | -See the [Model Providers]({{ '/providers/overview/' | relative_url }}) section for detailed configuration guides. +See the [Model Providers](../../providers/overview/index.md) section for detailed configuration guides. ## Model Properties @@ -142,12 +142,8 @@ models: thinking_budget: none # disable thinking ``` -
-
Multi-provider teams -
-

Different agents can use different providers in the same config. See Multi-Agent for patterns.

- -
+> [!NOTE] +> **Multi-provider teams**: Different agents can use different providers in the same config. See [Multi-Agent](../multi-agent/index.md) for patterns. ## Alloy Models diff --git a/docs/concepts/multi-agent/index.md b/docs/concepts/multi-agent/index.md index 84ee511018..32e7b0a85e 100644 --- a/docs/concepts/multi-agent/index.md +++ b/docs/concepts/multi-agent/index.md @@ -1,7 +1,7 @@ --- title: "Multi-Agent Systems" description: "Build teams of specialized agents that collaborate and delegate tasks to each other." -permalink: /concepts/multi-agent/ +keywords: docker agent, ai agents, concepts, multi-agent systems --- # Multi-Agent Systems @@ -34,14 +34,12 @@ Docker Agent supports two multi-agent patterns: You can combine both patterns in the same configuration — an agent can have both `sub_agents` and `handoffs`. -
-
When to use which -
-

sub_agents — Use when a coordinator needs to send tasks to specialists and synthesize their results.

-

handoffs — Use when agents should take turns processing the same conversation (pipelines, routing).

-

background_agents — Use when multiple independent tasks can run simultaneously.

- -
+> [!TIP] +> **When to use which**: **`sub_agents`** — Use when a coordinator needs to send tasks to specialists and synthesize their results. +> +> **`handoffs`** — Use when agents should take turns processing the same conversation (pipelines, routing). +> +> **`background_agents`** — Use when multiple independent tasks can run simultaneously. ## Delegation with `sub_agents` @@ -62,12 +60,8 @@ transfer_task( ) ``` -
-
Auto-Approved -
-

Unlike other tools, transfer_task is always auto-approved — no user confirmation needed. This allows seamless delegation between agents.

- -
+> [!NOTE] +> **Auto-Approved**: Unlike other tools, `transfer_task` is always auto-approved — no user confirmation needed. This allows seamless delegation between agents. ## Handoffs Routing @@ -94,18 +88,14 @@ handoff( ) ``` -
-
Scoped Handoff Targets -
-

Each agent can only hand off to agents listed in its own handoffs array. The handoff tool is automatically injected — you don't need to add it manually.

- -
+> [!NOTE] +> **Scoped Handoff Targets**: Each agent can only hand off to agents listed in its own `handoffs` array. The `handoff` tool is automatically injected — you don't need to add it manually. ### Example A coordinator routes to a researcher, who hands off to a summarizer, who returns to the coordinator: -``` +```text Root ──→ Researcher ──→ Summarizer ──→ Root ``` @@ -140,12 +130,8 @@ agents: - root ``` -
-
Full pipeline example -
-

For a more complex handoff graph with branching and multiple processing stages, see examples/handoff.yaml.

- -
+> [!TIP] +> **Full pipeline example**: For a more complex handoff graph with branching and multiple processing stages, see [`examples/handoff.yaml`](https://github.com/docker/docker-agent/blob/main/examples/handoff.yaml). ### Forced Handoffs @@ -173,7 +159,7 @@ Rules enforced at config load time: - An agent cannot `force_handoff` to itself - Chains of `force_handoff` edges must not form a cycle (A → B → A is rejected) -See examples/force_handoff.yaml for a runnable example. +See [`examples/force_handoff.yaml`](https://github.com/docker/docker-agent/blob/main/examples/force_handoff.yaml) for a runnable example. ## Parallel Delegation with Background Agents @@ -255,13 +241,10 @@ Copy the digest from your registry (Docker Hub shows it next to the tag) or read External references in `handoffs` and `force_handoff` carry the same per-run cost, so pin those to a digest too. -
-
Tip -
-

External sub-agents work with any OCI-compatible registry, not just the Docker Agent Catalog. See Agent Distribution for more on registry references.

-

See examples/sub-agents-from-catalog.yaml for a complete example mixing local and catalog sub-agents.

- -
+> [!TIP] +> External sub-agents work with any OCI-compatible registry, not just the Docker Agent Catalog. See [Agent Distribution](../distribution/index.md) for more on registry references. +> +> See [`examples/sub-agents-from-catalog.yaml`](https://github.com/docker/docker-agent/blob/main/examples/sub-agents-from-catalog.yaml) for a complete example mixing local and catalog sub-agents. ## Harness-Backed Sub-Agents @@ -292,15 +275,11 @@ agents: The orchestrator uses `transfer_task` to send work to a harness sub-agent just like any other sub-agent. Docker Agent handles the orchestration and hooks; the external CLI drives the coding loop. -
-
Learn more -
-

See Coding Harnesses for the full field reference, parallel dispatch patterns, and what does not work inside harness agents.

-
+> [!TIP] +> **Learn more**: See [Coding Harnesses](../../features/harnesses/index.md) for the full field reference, parallel dispatch patterns, and what does not work inside harness agents. ## Example: Development Team - ```yaml agents: root: @@ -425,9 +404,5 @@ toolsets: - **Use the right model** — Use capable models for complex reasoning, cheap models for simple tasks - **Choose the right pattern** — Use `sub_agents` for hierarchical task delegation, `handoffs` for pipeline workflows and conversational routing -
-
Beyond Docker Agent -
-

For interoperability with other agent frameworks, Docker Agent supports the A2A protocol and can expose agents via MCP Mode.

- -
+> [!NOTE] +> **Beyond Docker Agent**: For interoperability with other agent frameworks, Docker Agent supports the [A2A protocol](../../features/a2a/index.md) and can expose agents via [MCP Mode](../../features/mcp-mode/index.md). diff --git a/docs/concepts/tools/index.md b/docs/concepts/tools/index.md index 983b405638..b3ad10b4d3 100644 --- a/docs/concepts/tools/index.md +++ b/docs/concepts/tools/index.md @@ -1,7 +1,7 @@ --- title: "Tools" description: "Tools give agents the ability to interact with the world — read files, run commands, search the web, query databases, and more." -permalink: /concepts/tools/ +keywords: docker agent, ai agents, concepts, tools --- # Tools @@ -17,11 +17,8 @@ When an agent needs to perform an action, it makes a **tool call**. The docker-a 3. docker-agent executes the tool and returns the result 4. Agent incorporates the result and responds -
-
Tool Confirmation -
-

By default, docker-agent asks for user confirmation before executing tools that have side effects (shell commands, file writes). Use --yolo to auto-approve all tool calls.

-
+> [!NOTE] +> **Tool Confirmation**: By default, docker-agent asks for user confirmation before executing tools that have side effects (shell commands, file writes). Use `--yolo` to auto-approve all tool calls. ## Built-in Tools @@ -29,26 +26,26 @@ docker-agent ships with several built-in tools that require no external dependen | Tool | Description | | --- | --- | -| [Filesystem]({{ '/tools/filesystem/' | relative_url }}) | Read, write, list, search, and navigate files and directories | -| [Shell]({{ '/tools/shell/' | relative_url }}) | Execute synchronous and background shell commands | -| [Think]({{ '/tools/think/' | relative_url }}) | Step-by-step reasoning scratchpad for planning and decision-making | -| [Todo]({{ '/tools/todo/' | relative_url }}) | Task list management for complex multi-step workflows | -| [Tasks]({{ '/tools/tasks/' | relative_url }}) | Persistent task database shared across sessions | -| [Memory]({{ '/tools/memory/' | relative_url }}) | Persistent key-value storage backed by SQLite | -| [Fetch]({{ '/tools/fetch/' | relative_url }}) | Read content from HTTP/HTTPS URLs (GET only) | -| [Script]({{ '/tools/script/' | relative_url }}) | Define custom shell scripts as named tools | -| [LSP]({{ '/tools/lsp/' | relative_url }}) | Connect to Language Server Protocol servers for code intelligence | -| [API]({{ '/tools/api/' | relative_url }}) | Create custom tools that call HTTP APIs without writing code | -| [OpenAPI]({{ '/tools/openapi/' | relative_url }}) | Generate tools from an OpenAPI 3.x document | -| [RAG]({{ '/tools/rag/' | relative_url }}) | Retrieval-augmented generation over indexed sources | -| [Model Picker]({{ '/tools/model-picker/' | relative_url }}) | Let the agent pick between several models per turn | -| [User Prompt]({{ '/tools/user-prompt/' | relative_url }}) | Ask users questions and collect interactive input | -| [Open URL]({{ '/tools/open-url/' | relative_url }}) | Open a fixed URL in the user's default browser | -| [Transfer Task]({{ '/tools/transfer-task/' | relative_url }}) | Delegate tasks to sub-agents (auto-enabled with `sub_agents`) | -| [Background Agents]({{ '/tools/background-agents/' | relative_url }}) | Dispatch work to sub-agents concurrently | -| [Handoff]({{ '/tools/handoff/' | relative_url }}) | Hand the conversation off to another local agent in the same config (auto-enabled with `handoffs:`) | -| [A2A]({{ '/tools/a2a/' | relative_url }}) | Connect to remote agents via the Agent-to-Agent protocol | -| [MCP Catalog]({{ '/tools/mcp-catalog/' | relative_url }}) | Discover and activate remote MCP servers from the Docker MCP Catalog on demand | +| [Filesystem](../../tools/filesystem/index.md) | Read, write, list, search, and navigate files and directories | +| [Shell](../../tools/shell/index.md) | Execute synchronous and background shell commands | +| [Think](../../tools/think/index.md) | Step-by-step reasoning scratchpad for planning and decision-making | +| [Todo](../../tools/todo/index.md) | Task list management for complex multi-step workflows | +| [Tasks](../../tools/tasks/index.md) | Persistent task database shared across sessions | +| [Memory](../../tools/memory/index.md) | Persistent key-value storage backed by SQLite | +| [Fetch](../../tools/fetch/index.md) | Read content from HTTP/HTTPS URLs (GET only) | +| [Script](../../tools/script/index.md) | Define custom shell scripts as named tools | +| [LSP](../../tools/lsp/index.md) | Connect to Language Server Protocol servers for code intelligence | +| [API](../../tools/api/index.md) | Create custom tools that call HTTP APIs without writing code | +| [OpenAPI](../../tools/openapi/index.md) | Generate tools from an OpenAPI 3.x document | +| [RAG](../../tools/rag/index.md) | Retrieval-augmented generation over indexed sources | +| [Model Picker](../../tools/model-picker/index.md) | Let the agent pick between several models per turn | +| [User Prompt](../../tools/user-prompt/index.md) | Ask users questions and collect interactive input | +| [Open URL](../../tools/open-url/index.md) | Open a fixed URL in the user's default browser | +| [Transfer Task](../../tools/transfer-task/index.md) | Delegate tasks to sub-agents (auto-enabled with `sub_agents`) | +| [Background Agents](../../tools/background-agents/index.md) | Dispatch work to sub-agents concurrently | +| [Handoff](../../tools/handoff/index.md) | Hand the conversation off to another local agent in the same config (auto-enabled with `handoffs:`) | +| [A2A](../../tools/a2a/index.md) | Connect to remote agents via the Agent-to-Agent protocol | +| [MCP Catalog](../../tools/mcp-catalog/index.md) | Discover and activate remote MCP servers from the Docker MCP Catalog on demand | ## MCP Tools @@ -56,7 +53,7 @@ docker-agent supports the [Model Context Protocol (MCP)](https://modelcontextpro - **Docker MCP** (recommended) — Run MCP servers in Docker containers via the [MCP Gateway](https://github.com/docker/mcp-gateway). Browse the [Docker MCP Catalog](https://hub.docker.com/search?q=&type=mcp). - **Local MCP (stdio)** — Run MCP servers as local processes communicating over stdin/stdout. -- **Remote MCP (Streamable HTTP / SSE)** — Connect to MCP servers running on a network. See [Remote MCP Servers]({{ '/features/remote-mcp/' | relative_url }}). +- **Remote MCP (Streamable HTTP / SSE)** — Connect to MCP servers running on a network. See [Remote MCP Servers](../../features/remote-mcp/index.md). ```yaml toolsets: @@ -64,10 +61,7 @@ toolsets: ref: docker:duckduckgo ``` -See [Tool Config]({{ '/configuration/tools/#mcp-tools' | relative_url }}) for full MCP configuration reference. +See [Tool Config](../../configuration/tools/index.md#mcp-tools) for full MCP configuration reference. -
-
See also -
-

For full configuration reference, see Tool Config.

-
+> [!TIP] +> **See also**: For full configuration reference, see [Tool Config](../../configuration/tools/index.md). diff --git a/docs/configuration/agents/index.md b/docs/configuration/agents/index.md index 290bf5fcfb..8a49b7648e 100644 --- a/docs/configuration/agents/index.md +++ b/docs/configuration/agents/index.md @@ -1,7 +1,7 @@ --- title: "Agent Configuration" description: "Complete reference for defining agents in your YAML configuration." -permalink: /configuration/agents/ +keywords: docker agent, ai agents, configuration, agent configuration --- # Agent Configuration @@ -69,12 +69,8 @@ agents: thinking: boolean # opencode only: enable extended thinking ``` -
-
See also -
-

For model parameters, see Model Config. For tool details, see Tool Config. For multi-agent patterns, see Multi-Agent.

- -
+> [!TIP] +> **See also**: For model parameters, see [Model Config](../models/index.md). For tool details, see [Tool Config](../tools/index.md). For multi-agent patterns, see [Multi-Agent](../../concepts/multi-agent/index.md). ## Properties Reference @@ -84,8 +80,8 @@ agents: | `description` | string | ✓ | Brief description of the agent's purpose. Used by coordinators to decide delegation. | | `instruction` | string | ✓ | System prompt that defines the agent's behavior, personality, and constraints. Required unless `instruction_file` is set. | | `instruction_file` | string \| array | ✗ | Path(s) to a file or files (relative to the config file's directory) whose contents become the agent's instruction, loaded at startup. Accepts a single path or a list; multiple files are concatenated in order, separated by a blank line. Mutually exclusive with `instruction`. Each path must be a local relative path inside the config directory (absolute paths and `..` traversal are rejected). Only supported for local file-based configs, not OCI/URL sources. See [External Instruction Files](#external-instruction-files) below. | -| `sub_agents` | array | ✗ | List of agent names or external OCI references this agent can delegate to. Supports local agents, registry references (e.g., `agentcatalog/pirate`), and named references (`name:reference`). Automatically enables the `transfer_task` tool. Pin external OCI references to a digest (`name@sha256:…`) to skip the per-run registry lookup that tag references incur. See [External Sub-Agents]({{ '/concepts/multi-agent/#external-sub-agents-from-registries' | relative_url }}). | -| `toolsets` | array | ✗ | List of tool configurations. See [Tool Config]({{ '/configuration/tools/' | relative_url }}). | +| `sub_agents` | array | ✗ | List of agent names or external OCI references this agent can delegate to. Supports local agents, registry references (e.g., `agentcatalog/pirate`), and named references (`name:reference`). Automatically enables the `transfer_task` tool. Pin external OCI references to a digest (`name@sha256:…`) to skip the per-run registry lookup that tag references incur. See [External Sub-Agents](../../concepts/multi-agent/index.md#external-sub-agents-from-registries). | +| `toolsets` | array | ✗ | List of tool configurations. See [Tool Config](../tools/index.md). | | `fallback` | object | ✗ | Automatic model failover configuration. | | `add_date` | boolean | ✗ | When `true`, injects the current date into the agent's context. | | `add_environment_info` | boolean | ✗ | When `true`, injects working directory, OS, CPU architecture, and git info into context. | @@ -97,26 +93,22 @@ agents: | `max_consecutive_tool_calls` | int | ✗ | Maximum consecutive identical tool calls before the agent is terminated, preventing degenerate loops. Default: `5`. | | `max_old_tool_call_tokens` | int | ✗ | Maximum number of tokens to keep from old tool call arguments and results. Older tool calls beyond this budget have their content replaced with a placeholder, saving context space. Tokens are approximated as `len/4`. Truncation is disabled by default; set a positive value to enable it. Set to `-1` to disable truncation (unlimited). | | `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). | -| `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/' | relative_url }}). | +| `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: `[]`. | | `use_skills` | list of string | ✗ | Names of top-level `skills` groups to merge into this agent. Inline skills are deduplicated by name against merged entries. Default: `[]`. | -| `use_toolsets` | list of string | ✗ | Names of top-level `toolsets` groups to merge into this agent. See [Reusable Toolsets]({{ '/configuration/overview/#reusable-toolsets-toolsets' | relative_url }}). Default: `[]`. | +| `use_toolsets` | list of string | ✗ | Names of top-level `toolsets` groups to merge into this agent. See [Reusable Toolsets](../overview/index.md#reusable-toolsets-toolsets). Default: `[]`. | | `readonly` | boolean | ✗ | When `true`, every toolset on this agent is filtered to expose only read-only tools (those annotated with a read-only hint). Mutating tools are removed at load time and cannot be called even if the model tries. See [Read-Only Agents](#read-only-agents) below. | | `welcome_message` | string | ✗ | Message displayed to the user when a session starts. Rendered as Markdown in the TUI. **Not sent to the model** — it exists purely for the user's benefit. Useful for telling users what the agent can do and what commands are available. | -| `handoffs` | array | ✗ | List of agent names this agent can hand off the conversation to. Enables the `handoff` tool. See [Handoffs Routing]({{ '/concepts/multi-agent/#handoffs-routing' | relative_url }}). | -| `force_handoff` | string | ✗ | Name of an agent that unconditionally receives the conversation whenever this agent produces a final response. The runtime performs the switch itself, bypassing the LLM's tool-calling, guaranteeing deterministic pipelines. Must not reference the agent itself, and chains must not form a cycle. See [Forced Handoffs]({{ '/concepts/multi-agent/#forced-handoffs' | relative_url }}). | -| `hooks` | object | ✗ | Lifecycle hooks for running commands at various points. See [Hooks]({{ '/configuration/hooks/' | relative_url }}). | -| `structured_output` | object | ✗ | Constrain agent output to match a JSON schema. See [Structured Output]({{ '/configuration/structured-output/' | relative_url }}). | +| `handoffs` | array | ✗ | List of agent names this agent can hand off the conversation to. Enables the `handoff` tool. See [Handoffs Routing](../../concepts/multi-agent/index.md#handoffs-routing). | +| `force_handoff` | string | ✗ | Name of an agent that unconditionally receives the conversation whenever this agent produces a final response. The runtime performs the switch itself, bypassing the LLM's tool-calling, guaranteeing deterministic pipelines. Must not reference the agent itself, and chains must not form a cycle. See [Forced Handoffs](../../concepts/multi-agent/index.md#forced-handoffs). | +| `hooks` | object | ✗ | Lifecycle hooks for running commands at various points. See [Hooks](../hooks/index.md). | +| `structured_output` | object | ✗ | Constrain agent output to match a JSON schema. See [Structured Output](../structured-output/index.md). | | `cache` | object | ✗ | Response cache. When the same user question is asked again, the previous answer is replayed verbatim and the model is not called. See [Response Cache](#response-cache) below. | -| `harness` | object | ✗ | Run this agent through an external coding CLI instead of a model. **Note:** Any `toolsets:` defined on the same agent are silently ignored when `harness:` is set — the external CLI brings its own tools. See [Coding Harnesses]({{ '/features/harnesses/' | relative_url }}). | - -
-
max_iterations -
-

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.

+| `harness` | object | ✗ | Run this agent through an external coding CLI instead of a model. **Note:** Any `toolsets:` defined on the same agent are silently ignored when `harness:` is set — the external CLI brings its own tools. See [Coding Harnesses](../../features/harnesses/index.md). | -
+> [!WARNING] +> **max_iterations**: 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. ## External Instruction Files @@ -191,20 +183,20 @@ agents: | `trim_spaces` | boolean | `false` | When `true`, leading and trailing whitespace is stripped from the question before it is compared. | | `path` | string | _empty_ | When set, cache entries are persisted to a JSON file at the given path and reloaded on startup so the cache survives restarts. Relative paths resolve against the agent config directory. When empty, the cache lives in memory only. | -**How it works** +### How it works - The cache key is the latest user message in the session, normalized according to `case_sensitive` and `trim_spaces`. - On a hit, the cached reply is added to the session as the assistant message and stop hooks fire normally — the rest of the agent (tools, sub-agents, the model) is bypassed. - On a miss, the agent runs normally; the final assistant message produced by the first stop of the run is then stored under the question's key. - Only the response to the original user question of a run is cached; follow-up turns inside the same `RunStream` are not. -**File-backed storage** +### File-backed storage When `path` is set, every `Store` rewrites the entire cache file. Writes are **atomic**: the new content is written to a sibling temp file, `fsync`'d, and renamed over the destination, so a concurrent reader (or a process that crashes mid-write) will always see either the previous content or the new content in full — never a partially written file. The parent directory is also `fsync`'d after the rename so the rename itself is durable. -**Cross-process sharing** +### Cross-process sharing -Multiple processes can share the same `path:` cache file safely. Every `Store` takes an exclusive advisory lock on a sibling `.lock` file (POSIX `flock(2)` on Unix, `LockFileEx` on Windows), reloads the current on-disk state under the lock, merges the new entry, and writes back atomically. Two processes that store *different* keys at the same time both see their writes preserved on disk; the lock window is short (one read + one fsync'd write). +Multiple processes can share the same `path:` cache file safely. Every `Store` takes an exclusive advisory lock on a sibling `.lock` file (POSIX `flock(2)` on Unix, `LockFileEx` on Windows), reloads the current on-disk state under the lock, merges the new entry, and writes back atomically. Two processes that store _different_ keys at the same time both see their writes preserved on disk; the lock window is short (one read + one fsync'd write). `Lookup` watches the file's modification time and reloads the in-memory map when the file has advanced since its last load, so writes from a sibling process become visible without a restart. The `.lock` sentinel file is created on first write and never deleted: removing it would let two processes lock different inodes and lose mutual exclusion. @@ -240,17 +232,11 @@ Detection uses the [portcullis](https://github.com/docker/portcullis) ruleset, w Each detected span is replaced with the literal string `[REDACTED]`; the surrounding text is preserved so a redacted argument still looks like a legitimate flag (e.g. `--token=[REDACTED]`). Redaction is idempotent — applying it twice yields the same result. -
-
False positives vs. false negatives -
-

False positives are extremely rare: every rule pairs a regex with a discriminating keyword, so plain English never trips detection. False negatives are possible — only patterns the ruleset recognises are scrubbed, so this is a defense-in-depth feature, not a substitute for keeping secrets out of the conversation in the first place. Pair it with a proper secret manager for the credentials your agent actually needs.

-
+> [!NOTE] +> **False positives vs. false negatives**: False positives are extremely rare: every rule pairs a regex with a discriminating keyword, so plain English never trips detection. **False negatives are possible** — only patterns the ruleset recognises are scrubbed, so this is a defense-in-depth feature, not a substitute for keeping secrets out of the conversation in the first place. Pair it with a proper [secret manager](../../guides/secrets/index.md) for the credentials your agent actually needs. -
-
Equivalent hook entry -
-

Setting redact_secrets: true on the agent is shorthand for auto-registering all three legs of the feature as hook entries. They share the same built-in name (type: builtin, command: redact_secrets) on pre_tool_use, before_llm_call, and tool_response_transform respectively — the implementation dispatches on the hook event. You can spell them out by hand to scope a leg to a subset of tools (set matcher: to a regex), stack them with other rewriters in a specific order, or enable just one or two legs. See examples/redact_secrets_hooks.yaml for a complete manual wiring and the Hooks reference for the builtin's event coverage.

-
+> [!NOTE] +> **Equivalent hook entry**: Setting `redact_secrets: true` on the agent is shorthand for auto-registering all three legs of the feature as hook entries. They share the _same_ built-in name (`type: builtin`, `command: redact_secrets`) on `pre_tool_use`, `before_llm_call`, and `tool_response_transform` respectively — the implementation dispatches on the hook event. You can spell them out by hand to scope a leg to a subset of tools (set `matcher:` to a regex), stack them with other rewriters in a specific order, or enable just one or two legs. See [`examples/redact_secrets_hooks.yaml`](https://github.com/docker/docker-agent/blob/main/examples/redact_secrets_hooks.yaml) for a complete manual wiring and the [Hooks reference](../hooks/index.md#available-built-ins) for the builtin's event coverage. ## Welcome Message @@ -275,7 +261,7 @@ agents: ## Deferred Tool Loading -Toolsets support `defer` to load tools on-demand and speed up agent startup. See [Deferred Tool Loading]({{ '/configuration/tools/#deferred-tool-loading' | relative_url }}) for details. +Toolsets support `defer` to load tools on-demand and speed up agent startup. See [Deferred Tool Loading](../tools/index.md#deferred-tool-loading) for details. ```yaml agents: @@ -349,17 +335,18 @@ agents: url: https://docs.docker.com/ ``` - ### Command Formats Commands support three formats: 1. **Simple string format**: The string becomes the instruction sent to the current agent + ```yaml df: "Check disk space" ``` 2. **Advanced object format**: Supports agent switching and optional instructions + ```yaml plan: agent: planner # Required: name of sub-agent to switch to @@ -368,6 +355,7 @@ Commands support three formats: ``` 3. **URL format**: Opens a link in the browser instead of messaging the agent + ```yaml docs: url: https://docs.docker.com/ # Required: URL to open @@ -420,7 +408,7 @@ agents: **Agent-switching vs. `transfer_task`** -`transfer_task` launches a **sub-session**: the root agent sends a task, the child runs in isolation, and the result is returned to the root. The root agent stays in control and the child's work is never in the main conversation. 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. +`transfer_task` launches a **sub-session**: the root agent sends a task, the child runs in isolation, and the result is returned to the root. The root agent stays in control and the child's work is never in the main conversation. 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. @@ -435,7 +423,7 @@ Commands use JavaScript template literal syntax (`${env.VAR}`) for environment v The same syntax is also expanded in agent and toolset instructions: `agents..instruction` and `toolsets[*].instruction` support `${env.X}` placeholders (with optional `||` defaults and ternary expressions). `agents..description` and `agents..welcome_message` also support it. -Note that path-like fields (`working_dir`, `path`) primarily use a shell-style syntax (`$VAR`, `${VAR}`, `~`), and also accept `${env.X}` as an alias (though not richer JS expressions). See [Variable Expansion in Config Fields]({{ '/configuration/overview/#variable-expansion-in-config-fields' | relative_url }}) for the full table. +Note that path-like fields (`working_dir`, `path`) primarily use a shell-style syntax (`$VAR`, `${VAR}`, `~`), and also accept `${env.X}` as an alias (though not richer JS expressions). See [Variable Expansion in Config Fields](../overview/index.md#variable-expansion-in-config-fields) for the full table. ### URL Commands @@ -497,11 +485,8 @@ agents: See [`examples/readonly.yaml`](https://github.com/docker/docker-agent/blob/main/examples/readonly.yaml) for a complete example. -
-
Which tools are read-only? -
-

Whether a tool is read-only is determined by its ReadOnlyHint annotation. For built-in tools, read-only operations (list/read/search) carry the hint; mutating operations (write/delete/execute) do not. Custom and MCP tools expose the hint via their own annotations.

-
+> [!NOTE] +> **Which tools are read-only?** Whether a tool is read-only is determined by its `ReadOnlyHint` annotation. For built-in tools, read-only operations (list/read/search) carry the hint; mutating operations (write/delete/execute) do not. Custom and MCP tools expose the hint via their own annotations. ## Complete Example diff --git a/docs/configuration/hcl/index.md b/docs/configuration/hcl/index.md index c643d4c2ba..33c1e39c1d 100644 --- a/docs/configuration/hcl/index.md +++ b/docs/configuration/hcl/index.md @@ -1,7 +1,7 @@ --- title: "HCL Configuration" description: "Write docker-agent configs in HCL instead of YAML, using labeled blocks, heredocs, and the same underlying schema." -permalink: /configuration/hcl/ +keywords: docker agent, ai agents, configuration, hcl configuration --- # HCL Configuration @@ -10,11 +10,8 @@ _Write docker-agent configs in HCL instead of YAML. It maps to the same docker-a `docker-agent` supports `.hcl` config files anywhere it supports `.yaml` or `.yml` files. HCL is useful if you prefer labeled blocks, less punctuation, and heredocs for long prompts. -
-
Same config model, different syntax -
-

YAML and HCL are just two syntaxes for the same docker-agent configuration model. docker-agent converts HCL to the equivalent YAML structure internally, then runs the normal schema validation and loading pipeline.

-
+> [!TIP] +> **Same config model, different syntax**: YAML and HCL are just two syntaxes for the same docker-agent configuration model. docker-agent converts HCL to the equivalent YAML structure internally, then runs the normal schema validation and loading pipeline. ## Minimal Example @@ -40,11 +37,8 @@ $ docker agent run --exec agent.hcl "Summarize this repository" $ docker agent serve api ./agents/ # directories may mix .yaml, .yml, and .hcl files ``` -
-
See also -
-

HCL changes the syntax, not the meaning of fields. For what each field does, see Agent Config, Model Config, and Tool Config.

-
+> [!TIP] +> **See also**: HCL changes the syntax, not the meaning of fields. For what each field does, see [Agent Config](../agents/index.md), [Model Config](../models/index.md), and [Tool Config](../tools/index.md). ## YAML vs HCL diff --git a/docs/configuration/hooks/index.md b/docs/configuration/hooks/index.md index fa21836026..7648e7ee38 100644 --- a/docs/configuration/hooks/index.md +++ b/docs/configuration/hooks/index.md @@ -1,7 +1,7 @@ --- title: "Hooks" description: "Run shell commands at various points during agent execution for deterministic control over behavior." -permalink: /configuration/hooks/ +keywords: docker agent, ai agents, configuration, hooks --- # Hooks @@ -12,23 +12,20 @@ _Run shell commands at various points during agent execution for deterministic c Hooks allow you to execute shell commands or scripts at key points in an agent's lifecycle. They provide deterministic control that works alongside the LLM's behavior, enabling validation, logging, environment setup, and more. -
-
Use Cases -
- -- Validate or transform tool inputs before execution -- Log all tool calls to an audit file -- Block dangerous operations based on custom rules -- Validate, redact, or enrich user prompts before they reach the model -- Programmatically approve or deny tool calls without prompting the user -- Steer or veto context-window compaction -- Audit sub-agent handoffs in multi-agent setups -- Set up the environment when a session starts -- Clean up resources when a session ends -- Log or validate model responses before returning to the user -- Send external notifications on agent errors or warnings - -
+> [!NOTE] +> **Use Cases**: +> +> - Validate or transform tool inputs before execution +> - Log all tool calls to an audit file +> - Block dangerous operations based on custom rules +> - Validate, redact, or enrich user prompts before they reach the model +> - Programmatically approve or deny tool calls without prompting the user +> - Steer or veto context-window compaction +> - Audit sub-agent handoffs in multi-agent setups +> - Set up the environment when a session starts +> - Clean up resources when a session ends +> - Log or validate model responses before returning to the user +> - Send external notifications on agent errors or warnings ## Hook Types @@ -63,11 +60,10 @@ docker-agent dispatches the following hook events: | `on_tool_approval_decision` | After the runtime's approval chain (yolo / permissions / readonly / ask) resolves | No | | `worktree_create` | After `docker agent run --worktree` creates a git worktree, before the session | Yes | -
-
Two compaction events -
-

pre_compact and before_compaction both fire just before a compaction. pre_compact is the original event and is best-suited to steering the LLM-generated summary by appending guidance via additional_context. before_compaction is the newer, structured event: it carries the input/output token counts, the model's context limit, and a compaction_reason so handlers can decide based on real session pressure, and it can replace the LLM-generated summary verbatim via hook_specific_output.summary.

-
+> [!NOTE] +> **Two compaction events**: +> +> `pre_compact` and `before_compaction` both fire just before a compaction. `pre_compact` is the original event and is best-suited to _steering_ the LLM-generated summary by appending guidance via `additional_context`. `before_compaction` is the newer, structured event: it carries the input/output token counts, the model's context limit, and a `compaction_reason` so handlers can decide based on real session pressure, and it can _replace_ the LLM-generated summary verbatim via `hook_specific_output.summary`. ## Configuration @@ -163,18 +159,15 @@ Built-ins are typically zero-config and faster than equivalent shell hooks becau | `safer_shell` | `pre_tool_use` (with `preempt_yolo: true`) | _none_ | Classifies shell commands against an embedded taxonomy. Destructive matches (rm -rf, docker volume rm, mkfs, …) get an Ask verdict with `blast_radius` / `category` metadata; known-safe reads (ls, git status, docker ps, …) flow through silently; everything else asks with `blast_radius=unknown`. Filters by tool name internally (no-op for non-shell calls). Registered with `preempt_yolo: true` so the entry fires before `Decide()` / `--yolo`. Auto-registered by `safer: true` on a shell toolset — see [`examples/shell_safer.yaml`](https://github.com/docker/docker-agent/blob/main/examples/shell_safer.yaml). | | `unload` | `on_agent_switch` | _none_ | POSTs `{"model": ""}` to each of the previous agent's DMR model endpoints (`/_unload` by default, overridable per-model via `unload_api`) to free the GPU/RAM the just-departing model was holding. Pure HTTP — reads the model snapshot the runtime ships on `on_agent_switch` and depends on no provider-specific runtime state. Non-DMR providers (OpenAI, Anthropic, …) are silently skipped, so cross-provider chains are safe. Errors are logged and swallowed; agent switching never blocks on a slow or unreachable engine (each call has a 10 s timeout). See [`examples/unload_on_switch.yaml`](https://github.com/docker/docker-agent/blob/main/examples/unload_on_switch.yaml). | -
-
Per-turn vs. per-session -
-

turn_start built-ins recompute every turn and contribute transient context that is not persisted to the session — perfect for fast-moving signals like the date or current git state. session_start built-ins run once per session and their context persists across turns and resumes — pick this for stable context like the OS user or the initial directory listing.

-
+> [!NOTE] +> **Per-turn vs. per-session**: +> +> `turn_start` built-ins recompute every turn and contribute **transient** context that is _not_ persisted to the session — perfect for fast-moving signals like the date or current git state. `session_start` built-ins run once per session and their context **persists** across turns and resumes — pick this for stable context like the OS user or the initial directory listing. -
-
Auto-injected built-ins -
-

The agent flags add_date: true, add_environment_info: true, add_prompt_files: [...], and redact_secrets: true are shorthands that auto-register the matching built-in hook. You don't need to repeat them under hooks: — set the flag or the hook entry(ies), not both. redact_secrets: true auto-registers the same builtin on all three of pre_tool_use, before_llm_call, and tool_response_transform; you can also wire any subset of them by hand for finer-grained control (per-tool matchers, ordering with other rewriters, …).

-

limit_large_tool_results is injected unconditionally by the runtime — it is always active and cannot be removed from config.

-
+> [!NOTE] +> **Auto-injected built-ins**: The agent flags `add_date: true`, `add_environment_info: true`, `add_prompt_files: [...]`, and `redact_secrets: true` are shorthands that auto-register the matching built-in hook. You don't need to repeat them under `hooks:` — set the flag _or_ the hook entry(ies), not both. `redact_secrets: true` auto-registers the same builtin on all three of `pre_tool_use`, `before_llm_call`, and `tool_response_transform`; you can also wire any subset of them by hand for finer-grained control (per-tool matchers, ordering with other rewriters, …). +> +> `limit_large_tool_results` is injected unconditionally by the runtime — it is always active and cannot be removed from config. A minimal snapshot wiring looks like this: @@ -202,13 +195,10 @@ settings: Omit `snapshot` or set it to `false` to leave automatic snapshots off; manually configured snapshot hooks still run. -See [`examples/snapshot_hooks.yaml`](https://github.com/docker/docker-agent/blob/main/examples/snapshot_hooks.yaml) for a complete snapshot hook configuration. For an overview of the snapshot feature and the `/undo` / `/snapshots` commands, see [Snapshots]({{ '/features/snapshots/' | relative_url }}). +See [`examples/snapshot_hooks.yaml`](https://github.com/docker/docker-agent/blob/main/examples/snapshot_hooks.yaml) for a complete snapshot hook configuration. For an overview of the snapshot feature and the `/undo` / `/snapshots` commands, see [Snapshots](../../features/snapshots/index.md). -
-
Two flavors of max_iterations -
-

The max_iterations agent field has its own UX (it pauses and asks the user to resume past the limit). The max_iterations built-in hook is a hard stop with no resume — when its counter trips, the agent terminates with a block decision. Use the agent field for interactive sessions and the built-in hook to enforce non-negotiable caps in unattended runs.

-
+> [!WARNING] +> **Two flavors of `max_iterations`**: The `max_iterations` agent field has its own UX (it pauses and asks the user to resume past the limit). The `max_iterations` built-in hook is a **hard stop with no resume** — when its counter trips, the agent terminates with a block decision. Use the agent field for interactive sessions and the built-in hook to enforce non-negotiable caps in unattended runs. ## Matcher Patterns @@ -290,9 +280,9 @@ Notes: - `steering_messages` is only populated for `user_steering_messages_submit`. It carries the user messages the runtime just drained from the steering queue — messages submitted while the agent was already working (mid-turn, after the model stopped, or while idle before the first model call). - `prompt` is also populated for `user_followup_submit`, carrying the text of the dequeued follow-up message (a user message queued for end-of-turn processing via the FollowUp API / queue, as opposed to mid-turn steering). - `stop_response` carries the model's final assistant text for `stop`, `after_llm_call`, and `subagent_stop`. `last_user_message` carries the latest user message at dispatch time. -- `model_id` is populated for `after_llm_call` (and `before_llm_call`) in the canonical `/` form (e.g. `anthropic/claude-sonnet-4-5`). For harness agents, `model_id` is the harness label (e.g. `claude-code`) rather than a canonical model name — see [Coding Harnesses]({{ '/features/harnesses/' | relative_url }}). +- `model_id` is populated for `after_llm_call` (and `before_llm_call`) in the canonical `/` form (e.g. `anthropic/claude-sonnet-4-5`). For harness agents, `model_id` is the harness label (e.g. `claude-code`) rather than a canonical model name — see [Coding Harnesses](../../features/harnesses/index.md). - `usage` and `cost` are populated for `after_llm_call` only. `usage` is the per-call token usage object (`input_tokens`, `output_tokens`, `cached_input_tokens`, `cached_write_tokens`, and `reasoning_tokens` — the last is itself omitted for non-reasoning models); the whole object is absent when the provider reported no usage. `cost` is the USD price of that one model response. For a **native model call** it is the price computed from `usage` and the model's pricing table, and equals the cost the session records for the turn: it is **absent** when the response is unpriced (no pricing data on file, or no usage) and an explicit `0` for a priced call that was free — so a present `cost` is authoritative and an absent one means "unpriced", with no need to cross-check `usage`. (For harness agents the meaning differs — see the next note.) A cost ledger can therefore record per-call spend from the payload alone, without subscribing to the runtime event channel. -- For [harness agents]({{ '/features/harnesses/' | relative_url }}), `cost` is the harness's own reported total for the call rather than a computed price, and is present only when the harness reported a non-zero cost (some harnesses, e.g. `codex`, report token counts but no cost — those turns carry `usage` with `cost` absent, even though the recorded message stores `0`). +- For [harness agents](../../features/harnesses/index.md), `cost` is the harness's own reported total for the call rather than a computed price, and is present only when the harness reported a non-zero cost (some harnesses, e.g. `codex`, report token counts but no cost — those turns carry `usage` with `cost` absent, even though the recorded message stores `0`). - `after_llm_call` fires for **every** model call, including calls made inside sub-sessions (transferred tasks, background agents, skills). For those, `session_id` is the sub-session's id. Summing `cost` across `after_llm_call` events therefore captures **all** spend, including sub-sessions (and even sub-sessions that error before their cost is persisted). Do **not** add a separately-queried session cost total on top: the runtime's own total already recurses into and includes completed sub-session spend, so combining the two double-counts. Pick one source — the summed hook costs — as the authoritative ledger. - `context_limit` is `0` when the model definition is unavailable (treat `0` as "unknown", not as a real limit). - `approval_decision` is one of `allow`, `deny`, `canceled`. `approval_source` is a stable classifier of which step decided (e.g. `yolo`, `session_permissions_allow`, `session_permissions_deny`, `team_permissions_allow`, `team_permissions_deny`, `pre_tool_use_hook_allow`, `pre_tool_use_hook_deny`, `readonly_hint`, `user_approved`, `user_approved_session`, `user_approved_tool`, `user_rejected`, `context_canceled`). @@ -453,19 +443,13 @@ hooks: `working_dir` and `env` apply to `command` and `builtin` hooks. For `builtin` hooks, `working_dir` is resolved with the same logic as `command` hooks (absolute path wins; relative paths join onto the executor directory). For `model` hooks, both fields are accepted by the schema but have no effect: model hooks render a prompt template and call the LLM API directly — no subprocess is spawned and no file I/O is performed, so working directory and environment variables have no applicable semantics. -
-
Performance -
-

Hooks run synchronously and can slow down agent execution. Keep hook scripts fast and efficient. Consider using suppress_output: true for logging hooks to reduce noise.

- -
+> [!WARNING] +> **Performance**: Hooks run synchronously and can slow down agent execution. Keep hook scripts fast and efficient. Consider using `suppress_output: true` for logging hooks to reduce noise. -
-
Session End and Cancellation -
-

session_end hooks are designed to run even when the session is interrupted (e.g., Ctrl+C). They are still subject to their configured timeout.

- -
+> [!NOTE] +> **Session End and Cancellation**: +> +> `session_end` hooks are designed to run even when the session is interrupted (e.g., Ctrl+C). They are still subject to their configured timeout. ## Examples @@ -589,7 +573,7 @@ Use `on_error` and `on_max_iterations` instead of `notification` when you want a ### Turn-Start: per-turn context -`turn_start` fires at the start of every agent turn (each model call). Anything you contribute via `additional_context` (or plain stdout) is appended as a **transient** system message for that turn only — it is *not* persisted to the session. Use it for fast-moving signals like the date, current git state, or per-turn prompt files. The built-in hooks `add_date`, `add_prompt_files`, `add_git_status`, and `add_git_diff` all target this event. +`turn_start` fires at the start of every agent turn (each model call). Anything you contribute via `additional_context` (or plain stdout) is appended as a **transient** system message for that turn only — it is _not_ persisted to the session. Use it for fast-moving signals like the date, current git state, or per-turn prompt files. The built-in hooks `add_date`, `add_prompt_files`, `add_git_status`, and `add_git_diff` all target this event. ### Turn-End: per-turn finalizer @@ -622,7 +606,7 @@ The `reason` field classifies the exit: - veto compaction by returning `decision: block` (the runtime skips compaction entirely), or - replace the LLM-generated summary by returning `hook_specific_output.summary` (the runtime applies that summary verbatim and skips the model call). -`after_compaction` fires after a successful compaction. It carries the produced `summary` along with the *pre-compaction* `input_tokens` / `output_tokens` so observability handlers can naturally express "compacted from X to Y". `after_compaction` is purely observational; output is ignored. +`after_compaction` fires after a successful compaction. It carries the produced `summary` along with the _pre-compaction_ `input_tokens` / `output_tokens` so observability handlers can naturally express "compacted from X to Y". `after_compaction` is purely observational; output is ignored. ### Agent-Switch and Session-Resume: observability for multi-agent and long runs @@ -666,7 +650,7 @@ At every transfer the runtime ships a snapshot of the previous agent's model end ### Worktree-Create: prepare an isolated checkout -`worktree_create` fires once, just after `docker agent run --worktree[=name]` creates a fresh [git worktree]({{ '/features/cli/' | relative_url }}) and **before** the session starts. Each hook runs **inside** the new worktree — its working directory (and `cwd` in the input) is the fresh checkout — so setup commands operate on the new tree rather than your original one. The worktree path and branch are in `worktree_path` and `worktree_branch`, and `worktree_source_dir` carries the repository root it was branched from. +`worktree_create` fires once, just after `docker agent run --worktree[=name]` creates a fresh [git worktree](../../features/cli/index.md) and **before** the session starts. Each hook runs **inside** the new worktree — its working directory (and `cwd` in the input) is the fresh checkout — so setup commands operate on the new tree rather than your original one. The worktree path and branch are in `worktree_path` and `worktree_branch`, and `worktree_source_dir` carries the repository root it was branched from. Use it to prepare the checkout before the agent begins: copy untracked files git won't carry over (`.env`, local config), install dependencies, or warm caches. Because the worktree lives under the docker-agent data directory — not next to your checkout — resolve the original files through `worktree_source_dir` rather than a relative path. A hook may **abort the run** by returning `decision: block` / `{"continue": false}` / exit code 2 (for example, when a setup step fails); plain stdout is surfaced as additional context. @@ -760,7 +744,7 @@ hooks: ### Subagent-Stop: observe handoff completions -`subagent_stop` fires whenever a sub-agent finishes — `transfer_task` returns, a background agent completes, or a skill sub-session ends. It runs against the *parent* agent's hooks executor, so handlers configured on the orchestrator see every child completion in one place. The sub-agent's name is in `agent_name`, the parent's session ID in `parent_session_id`, and the child's final assistant message in `stop_response`. +`subagent_stop` fires whenever a sub-agent finishes — `transfer_task` returns, a background agent completes, or a skill sub-session ends. It runs against the _parent_ agent's hooks executor, so handlers configured on the orchestrator see every child completion in one place. The sub-agent's name is in `agent_name`, the parent's session ID in `parent_session_id`, and the child's final assistant message in `stop_response`. ### Permission-Request: programmatic tool approval @@ -887,9 +871,5 @@ $ docker agent run agentcatalog/coder \ --hook-pre-tool-use "./audit.sh" ``` -
-
Merging behavior -
-

CLI hooks are appended to any hooks already defined in the agent's YAML config. They don't replace existing hooks. Pre/post-tool-use hooks added via CLI match all tools (equivalent to matcher: "*").

- -
+> [!NOTE] +> **Merging behavior**: CLI hooks are **appended** to any hooks already defined in the agent's YAML config. They don't replace existing hooks. Pre/post-tool-use hooks added via CLI match all tools (equivalent to `matcher: "*"`). diff --git a/docs/configuration/models/index.md b/docs/configuration/models/index.md index 9e2a33dfff..00b5eb4361 100644 --- a/docs/configuration/models/index.md +++ b/docs/configuration/models/index.md @@ -1,7 +1,7 @@ --- title: "Model Configuration" description: "Complete reference for defining models with providers, parameters, and reasoning settings." -permalink: /configuration/models/ +keywords: docker agent, ai agents, configuration, model configuration --- # Model Configuration @@ -48,7 +48,7 @@ models: | Property | Type | Required | Description | | --------------------- | ---------- | -------- | ------------------------------------------------------------------------------------- | | `first_available` | array | ✗ | Candidate model references tried in order; selects the first whose credentials are configured. Mutually exclusive with other model settings. | -| `provider` | string | ✓/✗ | Required for regular model definitions; omitted for `first_available` selectors. Provider: `openai`, `anthropic`, `google`, `amazon-bedrock`, `dmr`, `mistral`, `xai`, `nebius`, `minimax`, `baseten`, `ovhcloud`, `groq`, `fireworks`, `deepseek`, `cerebras`, `together`, `huggingface`, `moonshot`, `vercel`, `cloudflare-workers-ai`, `cloudflare-ai-gateway`, `requesty`, `openrouter`, `azure`, `ollama`, `github-copilot`, or any [named provider]({{ '/providers/custom/' | relative_url }}). | +| `provider` | string | ✓/✗ | Required for regular model definitions; omitted for `first_available` selectors. Provider: `openai`, `anthropic`, `google`, `amazon-bedrock`, `dmr`, `mistral`, `xai`, `nebius`, `minimax`, `baseten`, `ovhcloud`, `groq`, `fireworks`, `deepseek`, `cerebras`, `together`, `huggingface`, `moonshot`, `vercel`, `cloudflare-workers-ai`, `cloudflare-ai-gateway`, `requesty`, `openrouter`, `azure`, `ollama`, `github-copilot`, or any [named provider](../../providers/custom/index.md). | | `model` | string | ✓/✗ | Required for regular model definitions; omitted for `first_available` selectors. Model name (e.g., `gpt-4o`, `claude-sonnet-4-5`, `gemini-3.5-flash`) | | `temperature` | float | ✗ | Sampling randomness. Range is provider-dependent — typically `0.0–2.0` (Anthropic caps at `1.0`). `0.0` is deterministic. | | `max_tokens` | int | ✗ | Maximum response length in tokens | @@ -61,7 +61,7 @@ models: | `task_budget` | int/object | ✗ | Total token budget for an agentic task (forwarded to Anthropic; see [Task Budget](#task-budget)). | | `parallel_tool_calls` | boolean | ✗ | Allow model to call multiple tools at once | | `track_usage` | boolean | ✗ | Track and report token usage for this model | -| `routing` | array | ✗ | Rule-based routing to different models. See [Model Routing]({{ '/configuration/routing/' | relative_url }}). | +| `routing` | array | ✗ | Rule-based routing to different models. See [Model Routing](../routing/index.md). | | `capabilities` | object | ✗ | Override attachment capabilities for this model. See [Attachment Capability Overrides](#attachment-capability-overrides). | | `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`. | @@ -122,11 +122,10 @@ The value can be a named entry from the `models` stanza or an inline `provider/model` string. When omitted, the agent's primary model generates titles. -
-
Constraint -
-

title_model cannot be combined with first_available model selection — the combination is rejected at validation time.

-
+> [!WARNING] +> **Constraint**: +> +> `title_model` cannot be combined with `first_available` model selection — the combination is rejected at validation time. ## Delegating Session Compaction @@ -153,11 +152,10 @@ call can always ingest the full conversation. Pair the primary with a compaction model whose window is at least as large to keep the proactive trigger aligned with the primary's window. -
-
Constraint -
-

compaction_model cannot be combined with first_available model selection — the combination is rejected at validation time.

-
+> [!WARNING] +> **Constraint**: +> +> `compaction_model` cannot be combined with `first_available` model selection — the combination is rejected at validation time. See [`examples/compaction_model.yaml`](https://github.com/docker/docker-agent/blob/main/examples/compaction_model.yaml) for a complete example. @@ -187,17 +185,13 @@ through the gateway as before. Bypass is propagated transparently through router models: a bypass-flagged routing model passes the flag to all of its routed targets automatically. -
-
Security note -
-

On an untrusted config, a malicious base_url combined with bypass_models_gateway: true could route provider credentials to an attacker-controlled endpoint. Only enable this on configs you control.

-
+> [!WARNING] +> **Security note**: On an untrusted config, a malicious `base_url` combined with `bypass_models_gateway: true` could route provider credentials to an attacker-controlled endpoint. Only enable this on configs you control. -
-
Constraint -
-

bypass_models_gateway: true cannot be combined with first_available — the combination is rejected at validation time.

-
+> [!WARNING] +> **Constraint**: +> +> `bypass_models_gateway: true` cannot be combined with `first_available` — the combination is rejected at validation time. See [`examples/bypass_models_gateway.yaml`](https://github.com/docker/docker-agent/blob/main/examples/bypass_models_gateway.yaml) for a complete example. @@ -314,7 +308,7 @@ thinking_budget: none # or 0 Models that always reason (OpenAI o-series, gpt-5, Gemini 3) fall back to the API default and still reason internally. -See the [Thinking / Reasoning guide]({{ '/guides/thinking/' | relative_url }}) for per-provider details, including AWS Bedrock and Docker Model Runner. +See the [Thinking / Reasoning guide](../../guides/thinking/index.md) for per-provider details, including AWS Bedrock and Docker Model Runner. ## Task Budget @@ -365,7 +359,7 @@ Setting `task_budget: 0` (or omitting the field) disables the feature — the model falls back to the provider's default behavior. Like other inheritable model settings, `task_budget` can also be declared on a -[provider definition]({{ '/providers/custom/' | relative_url }}) and is +[provider definition](../../providers/custom/index.md) and is inherited by every model that references that provider. See [`examples/task_budget.yaml`](https://github.com/docker/docker-agent/blob/main/examples/task_budget.yaml) for a complete example. @@ -399,7 +393,7 @@ models: thinking_display: summarized # "summarized", "display", or "omitted" ``` -See the [Anthropic provider page]({{ '/providers/anthropic/#thinking-display' | relative_url }}) for details. +See the [Anthropic provider page](../../providers/anthropic/index.md#thinking-display) for details. ## Custom HTTP Headers @@ -421,7 +415,7 @@ models: Header names are matched case-insensitively. The `github-copilot` provider automatically sets `Copilot-Integration-Id: copilot-developer-cli` — see the -[GitHub Copilot provider page]({{ '/providers/github-copilot/' | relative_url }}) +[GitHub Copilot provider page](../../providers/github-copilot/index.md) for details. ## Examples by Provider @@ -464,7 +458,7 @@ models: max_tokens: 8192 ``` -For detailed provider setup, see the [Model Providers]({{ '/providers/overview/' | relative_url }}) section. +For detailed provider setup, see the [Model Providers](../../providers/overview/index.md) section. ## Custom Endpoints @@ -503,9 +497,9 @@ models: base_url: "${env.DMR_BASE_URL}" ``` -See [Variable Expansion in Config Fields]({{ '/configuration/overview/#variable-expansion-in-config-fields' | relative_url }}) for the full set of fields and supported syntaxes. +See [Variable Expansion in Config Fields](../overview/index.md#variable-expansion-in-config-fields) for the full set of fields and supported syntaxes. -See [Local Models]({{ '/providers/local/' | relative_url }}) for more examples of custom endpoints. +See [Local Models](../../providers/local/index.md) for more examples of custom endpoints. ## Inheriting from Provider Definitions @@ -532,4 +526,4 @@ models: thinking_budget: 1024 # Overrides provider default ``` -See [Provider Definitions]({{ '/providers/custom/' | relative_url }}) for the full list of inheritable properties. +See [Provider Definitions](../../providers/custom/index.md) for the full list of inheritable properties. diff --git a/docs/configuration/overview/index.md b/docs/configuration/overview/index.md index 89286f9e82..6b2278b211 100644 --- a/docs/configuration/overview/index.md +++ b/docs/configuration/overview/index.md @@ -1,7 +1,7 @@ --- title: "Configuration Overview" description: "docker-agent uses YAML or HCL configuration files to define agents, models, tools, and their relationships." -permalink: /configuration/overview/ +keywords: docker agent, ai agents, configuration, configuration overview --- # Configuration Overview @@ -10,7 +10,7 @@ _docker-agent uses YAML or HCL configuration files to define agents, models, too ## File Structure -A docker-agent config can be written in YAML or HCL. The examples on this page use YAML; see [HCL Configuration]({{ '/configuration/hcl/' | relative_url }}) for the block-based HCL syntax. +A docker-agent config can be written in YAML or HCL. The examples on this page use YAML; see [HCL Configuration](../hcl/index.md) for the block-based HCL syntax. A docker-agent config has these main sections: @@ -107,72 +107,26 @@ agent "root" { Models can be referenced inline or defined in the `models` section: -
-
-

Inline

-

Quick and simple. Use provider/model syntax directly.

- 
model: openai/gpt-5
-
-
-

Named

-

Full control over parameters. Reusable across agents.

- 
model: my_claude
-
-
+- **Inline** — quick and simple. Use `provider/model` syntax directly: `model: openai/gpt-5` +- **Named** — full control over parameters, reusable across agents: `model: my_claude` ## Config Sections -
- -
🧱
-

HCL Configuration

-

Write the same agent schema in HCL using labeled blocks, heredocs, and block-based tool definitions.

- - -
🤖
-

Agent Config

-

All agent properties: model, instruction, tools, sub-agents, hooks, and more.

- - -
🧠
-

Model Config

-

Provider setup, parameters, thinking budget, and provider-specific options.

- - -
🔧
-

Tool Config

-

Built-in tools, MCP tools, Docker MCP, LSP, API tools, and tool filtering.

- -
+- **[HCL Configuration](../hcl/index.md)** — Write the same agent schema in HCL using labeled blocks, heredocs, and block-based tool definitions. +- **[Agent Config](../agents/index.md)** — All agent properties: model, instruction, tools, sub-agents, hooks, and more. +- **[Model Config](../models/index.md)** — Provider setup, parameters, thinking budget, and provider-specific options. +- **[Tool Config](../tools/index.md)** — Built-in tools, MCP tools, Docker MCP, LSP, API tools, and tool filtering. ## Advanced Configuration -
- -
⚡
-

Hooks

-

Run shell commands at lifecycle events like tool calls and session start/end.

- - -
🔐
-

Permissions

-

Control which tools auto-approve, require confirmation, or are blocked.

- - -
📦
-

Sandbox Mode

-

Run agents in an isolated Docker container for security.

- - -
📋
-

Structured Output

-

Constrain agent responses to match a specific JSON schema.

- -
+- **[Hooks](../hooks/index.md)** — Run shell commands at lifecycle events like tool calls and session start/end. +- **[Permissions](../permissions/index.md)** — Control which tools auto-approve, require confirmation, or are blocked. +- **[Sandbox Mode](../sandbox/index.md)** — Run agents in an isolated Docker container for security. +- **[Structured Output](../structured-output/index.md)** — Constrain agent responses to match a specific JSON schema. ## Environment Variables -API keys and secrets are read from environment variables — never stored in config files. See [Managing Secrets]({{ '/guides/secrets/' | relative_url }}) for all the ways to provide credentials (env files, Docker Compose secrets, macOS Keychain, `pass`): +API keys and secrets are read from environment variables — never stored in config files. See [Managing Secrets](../../guides/secrets/index.md) for all the ways to provide credentials (env files, Docker Compose secrets, macOS Keychain, `pass`): | Variable | Provider | | -------------------------- | --------------------------------------------------- | @@ -203,21 +157,13 @@ API keys and secrets are read from environment variables — never stored in con | `DOCKER_AGENT_DEFAULT_MODEL` | Default model used when none is specified, in `provider/model` form (e.g. `openai/gpt-5`). | | `DOCKER_AGENT_MODELS_GATEWAY` | Route model traffic through a gateway. Equivalent to the `--models-gateway` flag. | | `DOCKER_AGENT_HIDE_TELEMETRY_BANNER`| Set to `1` to suppress the first-run telemetry notice. | -| `DOCKER_AGENT_AUTO_UPDATE` | Set to a truthy value (`1`, `true`, `yes`, `on`) to let standalone release binaries self-update before running. See [Optional Self-Updates]({{ '/getting-started/installation/#optional-self-updates' | relative_url }}). | +| `DOCKER_AGENT_AUTO_UPDATE` | Set to a truthy value (`1`, `true`, `yes`, `on`) to let standalone release binaries self-update before running. See [Optional Self-Updates](../../getting-started/installation/index.md#optional-self-updates). | -
-
Legacy CAGENT_* aliases -
-

The same variables are also accepted with the legacy CAGENT_ prefix (e.g. CAGENT_DEFAULT_MODEL, CAGENT_MODELS_GATEWAY, CAGENT_HIDE_TELEMETRY_BANNER) for backward compatibility. Prefer the DOCKER_AGENT_* form in new setups.

+> [!NOTE] +> **Legacy `CAGENT_*` aliases**: The same variables are also accepted with the legacy `CAGENT_` prefix (e.g. `CAGENT_DEFAULT_MODEL`, `CAGENT_MODELS_GATEWAY`, `CAGENT_HIDE_TELEMETRY_BANNER`) for backward compatibility. Prefer the `DOCKER_AGENT_*` form in new setups. -
- -
-
Important -
-

Model references are case-sensitive: openai/gpt-5 is not the same as openai/GPT-5.

- -
+> [!WARNING] +> **Important**: Model references are case-sensitive: `openai/gpt-5` is not the same as `openai/GPT-5`. ## Variable Expansion in Config Fields @@ -362,7 +308,7 @@ metadata: | `version` | Semantic version string | | `tags` | Tags for categorization and discovery | -See [Agent Distribution]({{ '/concepts/distribution/' | relative_url }}) for publishing agents to registries. +See [Agent Distribution](../../concepts/distribution/index.md) for publishing agents to registries. ## Reusable MCP Servers (`mcps:`) @@ -388,7 +334,7 @@ agents: ref: playwright ``` -An `mcps` entry accepts every field a regular `type: mcp` toolset accepts (command/args/env, `remote` with `url`/`transport_type`/`headers`/`oauth`, `tools` filter, `instruction`, `defer`, …) — the `type: mcp` is implicit. See the [Tool Config]({{ '/configuration/tools/' | relative_url }}) page for all options and the [Remote MCP Servers]({{ '/features/remote-mcp/' | relative_url }}) guide for remote setups. +An `mcps` entry accepts every field a regular `type: mcp` toolset accepts (command/args/env, `remote` with `url`/`transport_type`/`headers`/`oauth`, `tools` filter, `instruction`, `defer`, …) — the `type: mcp` is implicit. See the [Tool Config](../tools/index.md) page for all options and the [Remote MCP Servers](../../features/remote-mcp/index.md) guide for remote setups. ## Reusable Toolsets (`toolsets:`) @@ -502,7 +448,7 @@ agents: | `track_usage` | Track token usage by default. | | `provider_opts` | Provider-specific options. | -See [Provider Definitions]({{ '/providers/custom/' | relative_url }}) for more details. +See [Provider Definitions](../../providers/custom/index.md) for more details. ## Reusable YAML (anchors & aliases) @@ -542,15 +488,11 @@ agents: description: Writes documentation. # then override one field ``` -
-
Where anchors can live
-

An anchor has to sit on a real value inside a known section (for example a real agent, model, or MCP entry, as above). Parking anchors in a separate top-level block such as defaults: or prompts: fails, because the parser rejects unknown top-level keys.

-
+> [!WARNING] +> **Where anchors can live**: An anchor has to sit on a real value inside a known section (for example a real agent, model, or MCP entry, as above). Parking anchors in a separate top-level block such as `defaults:` or `prompts:` fails, because the parser rejects unknown top-level keys. -
-
Overriding merged keys
-

Overriding a key that a << merge already set works only in the agents: section, as shown above. Every other section (models:, mcps:, providers:, rag:) is parsed strictly and reports the override as a duplicate key. There, use << only to add new fields, or use the named-reuse sections above when you need per-entry overrides.

-
+> [!WARNING] +> **Overriding merged keys**: Overriding a key that a `<<` merge already set works only in the `agents:` section, as shown above. Every other section (`models:`, `mcps:`, `providers:`, `rag:`) is parsed strictly and reports the override as a duplicate key. There, use `<<` only to add new fields, or use the named-reuse sections above when you need per-entry overrides. Anchors are for static reuse within a single file, not dynamic values or cross-file composition. For environment-specific settings, see [Variable Expansion in Config Fields](#variable-expansion-in-config-fields), which substitutes `${env.VAR}` at load time. Templating tags such as `!include` are not acted on: the tag is ignored and its argument is kept as a plain string, so no other file is loaded. Circular aliases are not detected, so keep references acyclic. diff --git a/docs/configuration/permissions/index.md b/docs/configuration/permissions/index.md index 89a8731c8c..43d3303782 100644 --- a/docs/configuration/permissions/index.md +++ b/docs/configuration/permissions/index.md @@ -1,7 +1,7 @@ --- title: "Permissions" description: "Control which tools can execute automatically, require confirmation, or are blocked entirely." -permalink: /configuration/permissions/ +keywords: docker agent, ai agents, configuration, permissions --- # Permissions @@ -12,12 +12,8 @@ _Control which tools can execute automatically, require confirmation, or are blo Permissions provide fine-grained control over tool execution. You can configure which tools are auto-approved (run without asking), which require user confirmation, and which are completely blocked. -
-
Evaluation Order -
-

Permissions are evaluated in this order: **Deny → Allow → Ask**. Deny patterns take priority, then allow patterns, and anything else defaults to asking for user confirmation.

- -
+> [!NOTE] +> **Evaluation Order**: Permissions are evaluated in this order: **Deny → Allow → Ask**. Deny patterns take priority, then allow patterns, and anything else defaults to asking for user confirmation. ## Permission Levels @@ -89,12 +85,8 @@ When both global and agent-level permissions are present, they are merged into a The evaluation order remains the same after merging: **Deny > Allow > Ask > default Ask**. -
-
Example: Global deny + agent allow -
-

If your global config denies shell:cmd=sudo* and an agent config allows shell:cmd=sudo apt update, the deny wins. Deny patterns always take priority regardless of source.

- -
+> [!TIP] +> **Example: Global deny + agent allow**: If your global config denies `shell:cmd=sudo*` and an agent config allows `shell:cmd=sudo apt update`, the deny wins. Deny patterns always take priority regardless of source. ## Pattern Syntax @@ -158,12 +150,8 @@ Patterns follow filepath.Match semantics with some extensions: Matching is **case-insensitive**. -
-
Trailing Wildcards -
-

Trailing wildcards like sudo* match any characters including spaces, so sudo* matches sudo rm -rf /.

- -
+> [!TIP] +> **Trailing Wildcards**: Trailing wildcards like `sudo*` match any characters including spaces, so `sudo*` matches `sudo rm -rf /`. ## Decision Types @@ -234,7 +222,7 @@ permissions: ## Combining with Hooks -Permissions work alongside [hooks]({{ '/configuration/hooks/' | relative_url }}). The evaluation order is: +Permissions work alongside [hooks](../hooks/index.md). The evaluation order is: 1. Check **deny** patterns — if matched, tool is blocked 2. Check **allow** patterns — if matched, tool is auto-approved @@ -243,9 +231,5 @@ Permissions work alongside [hooks]({{ '/configuration/hooks/' | relative_url }}) Hooks can override allow decisions but cannot override deny decisions. -
-
Security Note -
-

Permissions are enforced client-side. They help prevent accidental operations but should not be relied upon as a security boundary for untrusted agents. For stronger isolation, use sandbox mode.

- -
+> [!WARNING] +> **Security Note**: Permissions are enforced client-side. They help prevent accidental operations but should not be relied upon as a security boundary for untrusted agents. For stronger isolation, use [sandbox mode](../sandbox/index.md). diff --git a/docs/configuration/routing/index.md b/docs/configuration/routing/index.md index faa799676e..c0963c5694 100644 --- a/docs/configuration/routing/index.md +++ b/docs/configuration/routing/index.md @@ -1,7 +1,7 @@ --- title: "Model Routing" description: "Route requests to different models based on the content of user messages." -permalink: /configuration/routing/ +keywords: docker agent, ai agents, configuration, model routing --- # Model Routing @@ -12,12 +12,8 @@ _Route requests to different models based on the content of user messages._ Model routing lets you define a "router" model that automatically selects the best underlying model based on the user's message. This is useful for cost optimization, specialized handling, or load balancing across models. -
-
How It Works -
-

docker-agent uses NLP-based text similarity (via Bleve full-text search) to match user messages against example phrases you define. The route with the best-matching examples wins, and that model handles the request.

- -
+> [!NOTE] +> **How It Works**: docker-agent uses NLP-based text similarity (via Bleve full-text search) to match user messages against example phrases you define. The route with the best-matching examples wins, and that model handles the request. ## Configuration @@ -79,16 +75,13 @@ The router: 4. Selects the route with the highest overall score 5. Falls back to the base model if no good match is found -
-
Writing Good Examples -
- -- Use diverse phrasing that captures the intent -- Include keywords users actually use -- Add 5-10 examples per route for best results -- Examples don't need to be exact matches — the router uses semantic similarity - -
+> [!TIP] +> **Writing Good Examples**: +> +> - Use diverse phrasing that captures the intent +> - Include keywords users actually use +> - Add 5-10 examples per route for best results +> - Examples don't need to be exact matches — the router uses semantic similarity ## Use Cases @@ -167,12 +160,9 @@ Look for log entries like: "Route matched" model=anthropic/claude-sonnet-4-5 score=2.45 ``` -
-
Limitations -
- -- Routing only considers the last user message, not full conversation context -- Very short messages may not match well — consider your fallback carefully -- Each routed model creates a separate provider connection - -
+> [!WARNING] +> **Limitations**: +> +> - Routing only considers the last user message, not full conversation context +> - Very short messages may not match well — consider your fallback carefully +> - Each routed model creates a separate provider connection diff --git a/docs/configuration/sandbox/index.md b/docs/configuration/sandbox/index.md index fa9e3b9ad1..0461c62e23 100644 --- a/docs/configuration/sandbox/index.md +++ b/docs/configuration/sandbox/index.md @@ -1,7 +1,7 @@ --- title: "Sandbox Mode" description: "Run agents in an isolated Docker sandbox VM for enhanced security." -permalink: /configuration/sandbox/ +keywords: docker agent, ai agents, configuration, sandbox mode --- # Sandbox Mode @@ -14,12 +14,8 @@ Sandbox mode runs the entire agent inside a disposable sandbox VM instead of dir The backend is provided by the [`docker sandbox`](https://docs.docker.com/desktop/features/sandbox/) CLI plugin (ships with Docker Desktop) or the standalone [`sbx`](https://github.com/docker/sbx) CLI if it is on `PATH`. -
-
Requirements -
-

Sandbox mode requires Docker Desktop with sandbox support (or a working sbx CLI). docker-agent shells out to these tools, it does not start raw docker run containers.

- -
+> [!NOTE] +> **Requirements**: Sandbox mode requires Docker Desktop with sandbox support (or a working `sbx` CLI). docker-agent shells out to these tools, it does not start raw `docker run` containers. ## Usage @@ -53,7 +49,7 @@ docker agent run --sandbox --no-kit agent.yaml ### Always sandbox a given agent -Add `--sandbox` to an [alias]({{ '/features/cli/' | relative_url }}#aliases) so the +Add `--sandbox` to an [alias](../../features/cli/index.md#docker-agent-alias) so the sandbox path is taken automatically whenever that alias is invoked: ```bash @@ -164,7 +160,7 @@ docker agent run --sandbox agent.yaml 2. A new sandbox VM is created from the image passed via `--template`. 3. The current working directory is mounted into the VM; the agent binary is copied in. 4. The [auto-kit](#auto-kit) is staged on the host and bind-mounted read-only into the VM, so the agent sees its skills and prompt files inside the sandbox. -5. The default-deny network proxy is opened for the configured [models gateway]({{ '/features/cli/' | relative_url }}#runtime-configuration-flags) and any package hosts the auto-installer needs for the agent's MCP/LSP toolsets. +5. The default-deny network proxy is opened for the configured [models gateway](../../features/cli/index.md#runtime-configuration-flags) and any package hosts the auto-installer needs for the agent's MCP/LSP toolsets. 6. All tools (shell, filesystem, background jobs, etc.) run inside the VM. 7. When the session ends, docker-agent exits but does not stop or remove the sandbox VM; both the VM and the kit are kept around so subsequent runs from the same workspace can reuse them. A fresh sandbox is created only when the mount set has changed. @@ -178,7 +174,7 @@ The kit is built whenever `--sandbox` is used with an agent reference. It is opt For the agent referenced on the command line, the kit collects: -- **Local [skills]({{ '/features/skills/' | relative_url }})** — every `SKILL.md` discovered on the host (global `~/.codex/skills/`, `~/.claude/skills/`, `~/.agents/skills/`, plus project `.claude/skills/` and `.agents/skills/`) is copied under `/skills//`. The in-sandbox skills loader reads from the kit instead of the (non-existent) host `$HOME`. +- **Local [skills](../../features/skills/index.md)** — every `SKILL.md` discovered on the host (global `~/.codex/skills/`, `~/.claude/skills/`, `~/.agents/skills/`, plus project `.claude/skills/` and `.agents/skills/`) is copied under `/skills//`. The in-sandbox skills loader reads from the kit instead of the (non-existent) host `$HOME`. - **Prompt files** — every file referenced via the agent's `add_prompt_files` (`AGENTS.md`, `CLAUDE.md`, …) is collected. Files that already live under the working directory are left alone (the live workspace mount surfaces them); files outside it (e.g. an `AGENTS.md` in `$HOME`) are copied under `/prompt_files/`. - **A manifest** — `/manifest.json` records what was staged. The on-disk copy is sanitised so it cannot be used to map the host filesystem from inside the sandbox. @@ -190,7 +186,7 @@ Every text file copied into the kit is run through [portcullis](https://github.c ### Network allowlist -The sandbox templates ship with a default-deny network proxy that allows the major model providers but blocks `*.docker.com` and every package-registry / source host the auto-installer reaches for. When the agent declares MCP or LSP toolsets that have a `command` and an installable `version`, the kit build resolves each toolset's package against the [aqua](https://aquaproj.github.io/) registry and computes the minimal set of hosts the in-sandbox auto-installer will need (Go module proxy + toolchain bootstrap for `go_install` packages, GitHub release hosts for `github_release` packages, …). Those hosts, `models.dev` (needed so the in-sandbox agent can resolve model metadata such as context limits, pricing, and capabilities — without it the first catalog lookup fails with a `403 Blocked by network policy` error), and the configured [`--models-gateway`]({{ '/features/cli/' | relative_url }}#runtime-configuration-flags) — are then allow-listed on the sandbox proxy. If a per-toolset registry lookup fails, a conservative fallback union is used so the run can still succeed; the affected toolsets are surfaced in the printed summary. +The sandbox templates ship with a default-deny network proxy that allows the major model providers but blocks `*.docker.com` and every package-registry / source host the auto-installer reaches for. When the agent declares MCP or LSP toolsets that have a `command` and an installable `version`, the kit build resolves each toolset's package against the [aqua](https://aquaproj.github.io/) registry and computes the minimal set of hosts the in-sandbox auto-installer will need (Go module proxy + toolchain bootstrap for `go_install` packages, GitHub release hosts for `github_release` packages, …). Those hosts, `models.dev` (needed so the in-sandbox agent can resolve model metadata such as context limits, pricing, and capabilities — without it the first catalog lookup fails with a `403 Blocked by network policy` error), and the configured [`--models-gateway`](../../features/cli/index.md#runtime-configuration-flags) — are then allow-listed on the sandbox proxy. If a per-toolset registry lookup fails, a conservative fallback union is used so the run can still succeed; the affected toolsets are surfaced in the printed summary. ### Caching @@ -204,12 +200,9 @@ Pass `--no-kit` to skip the kit build entirely. The agent then runs without any docker agent run --sandbox --no-kit agent.yaml ``` -
-
Limitations -
- -- Sandboxes are reused across runs from the same workspace; if the required mount set changes (e.g. a new kit is staged), the previous sandbox is removed and a fresh one is created. -- Only the working directory, the agent config directory, and (when staged) the kit directory are mounted; other host files are not visible to the agent. -- Network egress is constrained by the sandbox backend's default-deny policy plus the per-run allowlist described above. - -
+> [!WARNING] +> **Limitations**: +> +> - Sandboxes are reused across runs from the same workspace; if the required mount set changes (e.g. a new kit is staged), the previous sandbox is removed and a fresh one is created. +> - Only the working directory, the agent config directory, and (when staged) the kit directory are mounted; other host files are not visible to the agent. +> - Network egress is constrained by the sandbox backend's default-deny policy plus the per-run allowlist described above. diff --git a/docs/configuration/structured-output/index.md b/docs/configuration/structured-output/index.md index e139c67d5d..20e21785c9 100644 --- a/docs/configuration/structured-output/index.md +++ b/docs/configuration/structured-output/index.md @@ -1,7 +1,7 @@ --- title: "Structured Output" description: "Force the agent to respond with JSON matching a specific schema." -permalink: /configuration/structured-output/ +keywords: docker agent, ai agents, configuration, structured output --- # Structured Output @@ -12,15 +12,13 @@ _Force the agent to respond with JSON matching a specific schema._ Structured output constrains the agent's responses to match a predefined JSON schema. This is useful for building agents that need to produce machine-readable output for downstream processing, API responses, or integration with other systems. -
-
When to Use
-
    -
  • Building API endpoints that need consistent JSON responses
    • -
  • Data extraction and transformation pipelines
    • -
  • Agents that feed into other automated systems
    • -
  • Ensuring predictable output format for parsing
    • -
-
+> [!NOTE] +> **When to Use**: +> +> - Building API endpoints that need consistent JSON responses +> - Data extraction and transformation pipelines +> - Agents that feed into other automated systems +> - Ensuring predictable output format for parsing ## Configuration @@ -123,16 +121,8 @@ schema: When `strict: true`, the model is constrained to only produce output that exactly matches the schema. This provides stronger guarantees but may limit the model's flexibility. -
-
-

strict: false (default)

-

Model aims to match schema but may include additional fields or slight variations.

-
-
-

strict: true

-

Model output is constrained to exactly match the schema. Stronger guarantees.

-
-
+- **`strict: false` (default)** — model aims to match the schema but may include additional fields or slight variations. +- **`strict: true`** — model output is constrained to exactly match the schema. Stronger guarantees. ## Provider Support @@ -221,7 +211,5 @@ agents: required: ["category", "priority", "confidence"] ``` -
-
Tool Limitations
-

When using structured output, the agent typically cannot use tools since its response format is constrained to the schema. Design your agent workflow accordingly — structured output agents work best for single-turn analysis or extraction tasks.

-
+> [!WARNING] +> **Tool Limitations**: When using structured output, the agent typically cannot use tools since its response format is constrained to the schema. Design your agent workflow accordingly — structured output agents work best for single-turn analysis or extraction tasks. diff --git a/docs/configuration/tools/index.md b/docs/configuration/tools/index.md index 05038df37d..67946923d1 100644 --- a/docs/configuration/tools/index.md +++ b/docs/configuration/tools/index.md @@ -1,7 +1,7 @@ --- title: "Tool Configuration" description: "Complete reference for configuring built-in tools, MCP tools, and Docker-based tools." -permalink: /configuration/tools/ +keywords: docker agent, ai agents, configuration, tool configuration --- # Tool Configuration @@ -14,29 +14,29 @@ Built-in tools are included with docker-agent and require no external dependenci | Type | Description | Page | | --- | --- | --- | -| `filesystem` | Read, write, list, search, navigate | [Filesystem]({{ '/tools/filesystem/' | relative_url }}) | -| `shell` | Execute shell commands (sync + background jobs) | [Shell]({{ '/tools/shell/' | relative_url }}) | -| `think` | Reasoning scratchpad | [Think]({{ '/tools/think/' | relative_url }}) | -| `plan` | Shared persistent scratchpad for multi-agent collaboration | [Plan]({{ '/tools/plan/' | relative_url }}) | -| `session_plan` | Per-session markdown plan for the draft-review-execute workflow | [Session Plan]({{ '/tools/session_plan/' | relative_url }}) | -| `session_context` | Reference a previous session as context (read-only) | [Session Context]({{ '/tools/session_context/' | relative_url }}) | -| `todo` | Task list management | [Todo]({{ '/tools/todo/' | relative_url }}) | -| `memory` | Persistent key-value storage (SQLite) | [Memory]({{ '/tools/memory/' | relative_url }}) | -| `tasks` | Persistent task database shared across sessions | [Tasks]({{ '/tools/tasks/' | relative_url }}) | -| `fetch` | HTTP `GET` requests with text/markdown/html output | [Fetch]({{ '/tools/fetch/' | relative_url }}) | -| `script` | Custom shell scripts as tools | [Script]({{ '/tools/script/' | relative_url }}) | -| `lsp` | Language Server Protocol integration | [LSP]({{ '/tools/lsp/' | relative_url }}) | -| `api` | Custom HTTP API tools | [API]({{ '/tools/api/' | relative_url }}) | -| `openapi` | Import every operation of an OpenAPI 3.x document as tools | [OpenAPI]({{ '/tools/openapi/' | relative_url }}) | -| `rag` | Retrieval-augmented generation over indexed sources | [RAG]({{ '/tools/rag/' | relative_url }}) | -| `model_picker` | Let the agent pick between several models per turn | [Model Picker]({{ '/tools/model-picker/' | relative_url }}) | -| `user_prompt` | Interactive user input | [User Prompt]({{ '/tools/user-prompt/' | relative_url }}) | -| `open_url` | Open a fixed URL in the user's default browser | [Open URL]({{ '/tools/open-url/' | relative_url }}) | -| `transfer_task` | Delegate to sub-agents (auto-enabled) | [Transfer Task]({{ '/tools/transfer-task/' | relative_url }}) | -| `background_agents` | Parallel sub-agent dispatch | [Background Agents]({{ '/tools/background-agents/' | relative_url }}) | -| `handoff` | Local conversation handoff to another agent in the same config (auto-enabled by `handoffs:`) | [Handoff]({{ '/tools/handoff/' | relative_url }}) | -| `a2a` | A2A remote agent connection | [A2A]({{ '/tools/a2a/' | relative_url }}) | -| `mcp_catalog` | Discover and activate remote MCP servers from the Docker MCP Catalog on demand | [MCP Catalog]({{ '/tools/mcp-catalog/' | relative_url }}) | +| `filesystem` | Read, write, list, search, navigate | [Filesystem](../../tools/filesystem/index.md) | +| `shell` | Execute shell commands (sync + background jobs) | [Shell](../../tools/shell/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) | +| `session_context` | Reference a previous session as context (read-only) | [Session Context](../../tools/session_context/index.md) | +| `todo` | Task list management | [Todo](../../tools/todo/index.md) | +| `memory` | Persistent key-value storage (SQLite) | [Memory](../../tools/memory/index.md) | +| `tasks` | Persistent task database shared across sessions | [Tasks](../../tools/tasks/index.md) | +| `fetch` | HTTP `GET` requests with text/markdown/html output | [Fetch](../../tools/fetch/index.md) | +| `script` | Custom shell scripts as tools | [Script](../../tools/script/index.md) | +| `lsp` | Language Server Protocol integration | [LSP](../../tools/lsp/index.md) | +| `api` | Custom HTTP API tools | [API](../../tools/api/index.md) | +| `openapi` | Import every operation of an OpenAPI 3.x document as tools | [OpenAPI](../../tools/openapi/index.md) | +| `rag` | Retrieval-augmented generation over indexed sources | [RAG](../../tools/rag/index.md) | +| `model_picker` | Let the agent pick between several models per turn | [Model Picker](../../tools/model-picker/index.md) | +| `user_prompt` | Interactive user input | [User Prompt](../../tools/user-prompt/index.md) | +| `open_url` | Open a fixed URL in the user's default browser | [Open URL](../../tools/open-url/index.md) | +| `transfer_task` | Delegate to sub-agents (auto-enabled) | [Transfer Task](../../tools/transfer-task/index.md) | +| `background_agents` | Parallel sub-agent dispatch | [Background Agents](../../tools/background-agents/index.md) | +| `handoff` | Local conversation handoff to another agent in the same config (auto-enabled by `handoffs:`) | [Handoff](../../tools/handoff/index.md) | +| `a2a` | A2A remote agent connection | [A2A](../../tools/a2a/index.md) | +| `mcp_catalog` | Discover and activate remote MCP servers from the Docker MCP Catalog on demand | [MCP Catalog](../../tools/mcp-catalog/index.md) | **Example:** @@ -52,13 +52,10 @@ toolsets: ## MCP Tools -Extend agents with external tools via the [Model Context Protocol](https://modelcontextprotocol.io/). For a standalone overview of the `mcp` toolset see the [MCP tool page]({{ '/tools/mcp/' | relative_url }}). +Extend agents with external tools via the [Model Context Protocol](https://modelcontextprotocol.io/). For a standalone overview of the `mcp` toolset see the [MCP tool page](../../tools/mcp/index.md). -
-
Reusable MCP definitions -
-

Repeated MCP server definitions can be hoisted into the top-level mcps: section and referenced by name with {type: mcp, ref: <name>}. See Reusable MCP Servers.

-
+> [!TIP] +> **Reusable MCP definitions**: Repeated MCP server definitions can be hoisted into the top-level `mcps:` section and referenced by name with `{type: mcp, ref: }`. See [Reusable MCP Servers](../overview/index.md#reusable-mcp-servers-mcps). ### Docker MCP (Recommended) @@ -80,7 +77,7 @@ Browse available tools at the [Docker MCP Catalog](https://hub.docker.com/search | `tools` | array | Optional: only expose these tools | | `instruction` | string | Custom instructions injected into the agent's context | | `config` | any | MCP server-specific configuration (passed during initialization) | -| `working_dir` | string | Working directory for the MCP gateway subprocess. Only applies when the catalog entry runs as a local process (not remote). Relative paths are resolved against the agent's working directory. Supports `${env.VAR}` (canonical), plus `~` and shell-style `$VAR`/`${VAR}` expansion ([details]({{ '/configuration/overview/#variable-expansion-in-config-fields' | relative_url }})). | +| `working_dir` | string | Working directory for the MCP gateway subprocess. Only applies when the catalog entry runs as a local process (not remote). Relative paths are resolved against the agent's working directory. Supports `${env.VAR}` (canonical), plus `~` and shell-style `$VAR`/`${VAR}` expansion ([details](../overview/index.md#variable-expansion-in-config-fields)). | ### Local MCP (stdio) @@ -102,7 +99,7 @@ toolsets: | `args` | array | Command arguments | | `tools` | array | Optional: only expose these tools | | `env` | object | Environment variables (key-value pairs) | -| `working_dir` | string | Working directory for the MCP server process. Relative paths are resolved against the agent's working directory. Defaults to the agent's working directory when omitted. Supports `${env.VAR}` (canonical), plus `~` and shell-style `$VAR`/`${VAR}` expansion ([details]({{ '/configuration/overview/#variable-expansion-in-config-fields' | relative_url }})). | +| `working_dir` | string | Working directory for the MCP server process. Relative paths are resolved against the agent's working directory. Defaults to the agent's working directory when omitted. Supports `${env.VAR}` (canonical), plus `~` and shell-style `$VAR`/`${VAR}` expansion ([details](../overview/index.md#variable-expansion-in-config-fields)). | | `instruction` | string | Custom instructions injected into the agent's context | | `version` | string | Package reference for [auto-installing](#auto-installing-tools) the command binary | @@ -208,11 +205,8 @@ export DOCKER_AGENT_AUTO_INSTALL=false Installed binaries are placed in `~/.cagent/tools/bin/` and cached so they are only downloaded once. -
-
Tip -
-

Auto-install supports both Go packages (via go install) and GitHub release binaries (via archive download). The aqua registry metadata determines which method is used.

-
+> [!TIP] +> Auto-install supports both Go packages (via `go install`) and GitHub release binaries (via archive download). The aqua registry metadata determines which method is used. ## Toolset Lifecycle @@ -276,11 +270,8 @@ toolsets: | `startup_timeout` | duration | Cap on the initial connect+initialize duration. Today this is informational; the eager-startup phase that enforces it ships in a follow-up. | | `call_timeout` | duration | Documented per-call timeout. Informational; the runtime currently uses the caller's context for cancellation. | -
-
required and startup_timeout are not yet enforced -
-

The schema validates these fields and the supervisor stores them, but no code path acts on them yet. They are documented now so config files written today keep working when the planned eager-startup phase lands. Picking the strict profile is forward-compatible — it will start enforcing required=true automatically.

-
+> [!NOTE] +> **`required` and `startup_timeout` are not yet enforced**: The schema validates these fields and the supervisor stores them, but no code path acts on them yet. They are documented now so config files written today keep working when the planned eager-startup phase lands. Picking the `strict` profile is forward-compatible — it will start enforcing `required=true` automatically. ### Inspecting and restarting toolsets at runtime @@ -289,7 +280,7 @@ The TUI exposes the supervisor through two slash commands: - `/tools` — the unified tools dialog. Its top section lists every toolset on the current agent with its lifecycle state (`Stopped`, `Starting`, `Ready`, `Degraded`, `Restarting`, `Failed`), restart count, and last error; its bottom section lists every tool the agent can call, grouped by category. Use this to answer both "what can the agent do?" and "is anything degraded?" with one command. - `/toolset-restart ` — force the supervisor to reconnect the named toolset. Useful after completing OAuth, when a remote MCP server has been redeployed, or when an LSP like `gopls` is stuck. -See the [TUI reference]({{ '/features/tui/' | relative_url }}) for the full list of slash commands. +See the [TUI reference](../../features/tui/index.md) for the full list of slash commands. See [`examples/lifecycle.yaml`](https://github.com/docker/docker-agent/blob/main/examples/lifecycle.yaml) for a complete lifecycle configuration example. @@ -313,11 +304,8 @@ toolsets: When a tool's output is not valid JSON, it is returned unchanged — TOON encoding is best-effort and never breaks tools that emit plain text. -
-
When to use TOON -
-

TOON typically yields 30-60% smaller payloads than equivalent JSON for MCP tools that return arrays of records (issue lists, search results, file listings, …). It works best when the schema is regular; one-off responses with deeply nested or heterogeneous shapes may benefit less.

-
+> [!NOTE] +> **When to use TOON**: TOON typically yields 30-60% smaller payloads than equivalent JSON for MCP tools that return arrays of records (issue lists, search results, file listings, …). It works best when the schema is regular; one-off responses with deeply nested or heterogeneous shapes may benefit less. ## Per-Toolset Model Routing @@ -366,11 +354,8 @@ toolsets: tools: ["shell"] ``` -
-
Tip -
-

Filtering tools improves agent performance — fewer tools means less confusion for the model about which tool to use.

-
+> [!TIP] +> Filtering tools improves agent performance — fewer tools means less confusion for the model about which tool to use. ## Tool Instructions @@ -504,8 +489,5 @@ agents: Authorization: "Bearer ${env.INTERNAL_TOKEN}" ``` -
-
Toolset Order Matters -
-

If multiple toolsets provide a tool with the same name, the first one wins. Order your toolsets intentionally.

-
+> [!WARNING] +> **Toolset Order Matters**: If multiple toolsets provide a tool with the same name, the first one wins. Order your toolsets intentionally. diff --git a/docs/css/style.css b/docs/css/style.css index 027439a344..bff03f807a 100644 --- a/docs/css/style.css +++ b/docs/css/style.css @@ -800,9 +800,9 @@ details.sidebar-section[open] > summary.sidebar-heading::after { /* ===== Callouts / Admonitions ===== * docs.docker.com-style: rounded panel with a filled, circular icon - * badge in the upper-left and a strong title. Authors keep using the - * existing Markdown: - *
+ * badge in the upper-left and a strong title. Authors write GitHub-style + * alerts (> [!TIP]); js/app.js upgrades the rendered blockquote to: + *
*
…
*

…

*
diff --git a/docs/features/a2a/index.md b/docs/features/a2a/index.md index 74e12cf38d..71998560c3 100644 --- a/docs/features/a2a/index.md +++ b/docs/features/a2a/index.md @@ -1,7 +1,7 @@ --- title: "A2A Protocol" description: "Expose docker-agent agents via Google's Agent-to-Agent (A2A) protocol for interoperability with other agent frameworks." -permalink: /features/a2a/ +keywords: docker agent, ai agents, features, a2a protocol --- # A2A Protocol @@ -12,12 +12,8 @@ _Expose docker-agent agents via Google's Agent-to-Agent (A2A) protocol for inter The `docker agent serve a2a` command starts an A2A server that exposes your agents using the [A2A protocol](https://a2a-protocol.org/latest/). This enables communication between Docker Agent and other agent frameworks that support A2A. -
-
Early support -
-

A2A support is functional but still evolving. Tool calls, artifacts, and memory features have limited A2A integration. See limitations below.

- -
+> [!WARNING] +> **Early support**: A2A support is functional but still evolving. Tool calls, artifacts, and memory features have limited A2A integration. See limitations below. ## Usage @@ -42,7 +38,7 @@ $ docker agent serve a2a agentcatalog/pirate | `--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. | | `--code-mode-tools` | `false` | Expose tools as a single "code" toolset that accepts a JavaScript snippet to run. | -| `--hook-pre-tool-use ` | (none) | Add a pre-tool-use hook (repeatable). See [Hooks]({{ '/configuration/hooks/' | relative_url }}). | +| `--hook-pre-tool-use ` | (none) | Add a pre-tool-use hook (repeatable). See [Hooks](../../configuration/hooks/index.md). | | `--hook-post-tool-use ` | (none) | Add a post-tool-use hook (repeatable). | | `--hook-session-start ` | (none) | Add a session-start hook (repeatable). | | `--hook-session-end ` | (none) | Add a session-end hook (repeatable). | @@ -56,12 +52,8 @@ $ docker agent serve a2a agentcatalog/pirate - **Full docker-agent features** — Supports all tools, models, and gateway features - **Multiple sources** — Load agents from files or the agent catalog -
-
See also -
-

For exposing agents via MCP instead, see MCP Mode. For stdio-based integration, see ACP. For the HTTP API, see API Server.

- -
+> [!TIP] +> **See also**: For exposing agents via MCP instead, see [MCP Mode](../mcp-mode/index.md). For stdio-based integration, see [ACP](../acp/index.md). For the HTTP API, see [API Server](../api-server/index.md). ## Current Limitations diff --git a/docs/features/acp/index.md b/docs/features/acp/index.md index fd80e5aa46..9331843f9f 100644 --- a/docs/features/acp/index.md +++ b/docs/features/acp/index.md @@ -1,7 +1,7 @@ --- title: "ACP (Agent Client Protocol)" description: "Expose docker-agent agents via the Agent Client Protocol for integration with ACP-compatible hosts like VS Code, IDEs, and other developer tools." -permalink: /features/acp/ +keywords: docker agent, ai agents, features, acp (agent client protocol) --- # ACP (Agent Client Protocol) @@ -14,12 +14,8 @@ The `docker agent serve acp` command starts an ACP server that communicates over ACP is built on the [ACP Go SDK](https://github.com/coder/acp-go-sdk) and provides a standardized way for client applications to interact with AI agents. -
-
ACP vs A2A vs MCP -
- **ACP** connects an agent to a *host application* (IDE, CLI tool) via stdio. **A2A** connects *agents to other agents* over HTTP. **MCP** exposes agents as *tools* for other MCP clients. Choose based on your integration target. - -
+> [!NOTE] +> **ACP vs A2A vs MCP**: **ACP** connects an agent to a _host application_ (IDE, CLI tool) via stdio. **A2A** connects _agents to other agents_ over HTTP. **MCP** exposes agents as _tools_ for other MCP clients. Choose based on your integration target. ## Usage @@ -74,7 +70,7 @@ docker agent serve acp | [flags] | `--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. | | `--code-mode-tools` | `false` | Expose tools as a single "code" toolset that accepts a JavaScript snippet to run. | -| `--hook-pre-tool-use ` | (none) | Add a pre-tool-use hook (repeatable). See [Hooks]({{ '/configuration/hooks/' | relative_url }}). | +| `--hook-pre-tool-use ` | (none) | Add a pre-tool-use hook (repeatable). See [Hooks](../../configuration/hooks/index.md). | | `--hook-post-tool-use ` | (none) | Add a post-tool-use hook (repeatable). | | `--hook-session-start ` | (none) | Add a session-start hook (repeatable). | | `--hook-session-end ` | (none) | Add a session-end hook (repeatable). | @@ -105,16 +101,8 @@ child.stdout.on("data", (data) => { }); ``` -
-
When to use ACP -
-

Use ACP when building **IDE integrations**, **editor plugins**, or any tool that wants to embed a docker-agent agent as a subprocess. For HTTP-based integrations, use the API Server instead.

- -
- -
-
See also -
-

For HTTP-based agent access, see the API Server. For agent-to-agent communication, see A2A Protocol. For exposing agents as MCP tools, see MCP Mode.

+> [!TIP] +> **When to use ACP**: Use ACP when building **IDE integrations**, **editor plugins**, or any tool that wants to embed a docker-agent agent as a subprocess. For HTTP-based integrations, use the [API Server](../api-server/index.md) instead. -
+> [!NOTE] +> **See also**: For HTTP-based agent access, see the [API Server](../api-server/index.md). For agent-to-agent communication, see [A2A Protocol](../a2a/index.md). For exposing agents as MCP tools, see [MCP Mode](../mcp-mode/index.md). diff --git a/docs/features/api-server/index.md b/docs/features/api-server/index.md index c57abf8381..70a8090246 100644 --- a/docs/features/api-server/index.md +++ b/docs/features/api-server/index.md @@ -1,7 +1,7 @@ --- title: "API Server" description: "Expose your agents via an HTTP API for programmatic access, web frontends, and integrations." -permalink: /features/api-server/ +keywords: docker agent, ai agents, features, api server --- # API Server @@ -104,7 +104,7 @@ curl -N -X POST http://localhost:8080/api/sessions/$SID/agent/team/reviewer \ | Method | Path | Description | | ------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `POST` | `/api/mcp-oauth/callback` | Deliver an OAuth deeplink callback to a pending unmanaged OAuth flow. Success path: `?state=&code=`; authorization-server error path: `?state=&error=&error_description=`. Returns 400 if `state` is missing or neither `code` nor `error` is provided; 404 if no flow is awaiting that `state`. See [Remote MCP OAuth]({{ '/features/remote-mcp/' | relative_url }}) for details. | +| `POST` | `/api/mcp-oauth/callback` | Deliver an OAuth deeplink callback to a pending unmanaged OAuth flow. Success path: `?state=&code=`; authorization-server error path: `?state=&error=&error_description=`. Returns 400 if `state` is missing or neither `code` nor `error` is provided; 404 if no flow is awaiting that `state`. See [Remote MCP OAuth](../remote-mcp/index.md) for details. | ## Streaming Responses @@ -184,21 +184,13 @@ docker agent serve api | [flags] | `--pull-interval` | `0` (disabled) | Auto-pull OCI reference every N minutes | | `--fake` | (none) | Replay AI responses from cassette file (testing) | | `--record` | (none) | Record AI API interactions to cassette file | -| `--mcp-oauth-redirect-uri` | (none) | Public HTTPS URL advertised as the OAuth `redirect_uri` for unmanaged MCP OAuth flows. When set, docker-agent drives PKCE and code exchange in-process and sends the full authorize URL to the client via elicitation. See [Remote MCP]({{ '/features/remote-mcp/' | relative_url }}) for details. | +| `--mcp-oauth-redirect-uri` | (none) | Public HTTPS URL advertised as the OAuth `redirect_uri` for unmanaged MCP OAuth flows. When set, docker-agent drives PKCE and code exchange in-process and sends the full authorize URL to the client via elicitation. See [Remote MCP](../remote-mcp/index.md) for details. | -
-
Live profiling (advanced) -
-

For production diagnostics, set the CAGENT_PPROF_ADDR environment variable (or the hidden --pprof-addr flag) to a TCP address such as 127.0.0.1:6060. docker-agent will start a Go pprof HTTP server at /debug/pprof/, which you can query with go tool pprof. Use a loopback address — a non-loopback binding logs a security warning. This flag is intentionally hidden from --help.

+> [!TIP] +> **Live profiling (advanced)**: For production diagnostics, set the `CAGENT_PPROF_ADDR` environment variable (or the hidden `--pprof-addr` flag) to a TCP address such as `127.0.0.1:6060`. docker-agent will start a Go pprof HTTP server at `/debug/pprof/`, which you can query with `go tool pprof`. Use a loopback address — a non-loopback binding logs a security warning. This flag is intentionally hidden from `--help`. -
- -
-
Multi-agent configs -
-

You can point docker agent serve api at a directory containing multiple agent YAML files. Each becomes a separate agent accessible via /api/agents. Combine with --pull-interval to auto-refresh agents from an OCI registry.

- -
+> [!TIP] +> **Multi-agent configs**: You can point `docker agent serve api` at a directory containing multiple agent YAML files. Each becomes a separate agent accessible via `/api/agents`. Combine with `--pull-interval` to auto-refresh agents from an OCI registry. ## Session Persistence @@ -246,11 +238,8 @@ $ curl -X POST http://127.0.0.1:8080/api/sessions/$SID/followup \ -d '{"messages":[{"content":"Now add tests"}]}' ``` -
-
Discovering a run -
-

Each run started with --listen writes a discovery record to <data-dir>/runs/<pid>.json containing its address and session id, so a supervising process can find a live run by session id, pid, or address.

-
+> [!NOTE] +> **Discovering a run**: Each run started with `--listen` writes a discovery record to `/runs/.json` containing its address and session id, so a supervising process can find a live run by session id, pid, or address. ## Session event stream and reconnection @@ -355,9 +344,5 @@ The response `status` is `queued_streaming` (a turn is running or starting), `queued_idle` (delivered to an idle headless session, runs on the next turn), or `duplicate`. -
-
See also -
-

For interactive use, see the Terminal UI. For agent-to-agent communication, see A2A Protocol and ACP. For MCP integration, see MCP Mode. For an OpenAI-compatible chat-completions API, see the Chat Server.

- -
+> [!NOTE] +> **See also**: For interactive use, see the [Terminal UI](../tui/index.md). For agent-to-agent communication, see [A2A Protocol](../a2a/index.md) and [ACP](../acp/index.md). For MCP integration, see [MCP Mode](../mcp-mode/index.md). For an OpenAI-compatible chat-completions API, see the [Chat Server](../chat-server/index.md). diff --git a/docs/features/chat-server/index.md b/docs/features/chat-server/index.md index 01a183d76a..881a1d677b 100644 --- a/docs/features/chat-server/index.md +++ b/docs/features/chat-server/index.md @@ -1,7 +1,7 @@ --- title: "Chat Server" description: "Expose your agents through an OpenAI-compatible Chat Completions API so any tool that already speaks OpenAI can drive a docker-agent agent." -permalink: /features/chat-server/ +keywords: docker agent, ai agents, features, chat server --- # Chat Server @@ -35,12 +35,8 @@ $ docker agent serve chat agentcatalog/pirate --listen 127.0.0.1:9090 $ docker agent serve chat agent.yaml --api-key-env CHAT_BEARER_TOKEN ``` -
-
When to use chat server vs. API server -
-

Use the chat server when you want to plug docker-agent into existing OpenAI-compatible tooling (chat UIs, IDE integrations, OpenAI SDK clients). Use the API server when you want full control over sessions, agent execution, tool-call confirmations, and streamed runtime events.

- -
+> [!TIP] +> **When to use chat server vs. API server**: Use the **chat server** when you want to plug docker-agent into existing OpenAI-compatible tooling (chat UIs, IDE integrations, OpenAI SDK clients). Use the [API server](../api-server/index.md) when you want full control over sessions, agent execution, tool-call confirmations, and streamed runtime events. ## Endpoints @@ -169,12 +165,8 @@ Clients must then send an `Authorization: Bearer ` header on every request to `/v1/*`. Both `/v1/models` and `/v1/chat/completions` are protected once a key is set. -
-
Public exposure -
-

The default listen address is 127.0.0.1:8083. If you bind to a non-loopback address, always set --api-key or --api-key-env — there is no other authentication layer.

- -
+> [!WARNING] +> **Public exposure**: The default listen address is `127.0.0.1:8083`. If you bind to a non-loopback address, always set `--api-key` or `--api-key-env` — there is no other authentication layer. ## CORS @@ -205,7 +197,7 @@ docker agent serve chat | [flags] | `--conversation-ttl ` | `30m` | Idle TTL after which a cached conversation is evicted. | | `--max-idle-runtimes ` | `4` | Maximum number of idle runtimes pooled per agent. `0` disables pooling. | -All [runtime configuration flags]({{ '/features/cli/#runtime-configuration-flags' | relative_url }}) +All [runtime configuration flags](../cli/index.md#runtime-configuration-flags) (`--working-dir`, `--env-from-file`, `--models-gateway`, `--hook-*`, …) are also accepted. @@ -230,9 +222,5 @@ in: 3. Each agent in your config appears as a selectable model. -
-
See also -
-

For the docker-agent–native HTTP API (sessions, tool-call confirmation, runtime events), see the API Server. For full CLI flag documentation, see the CLI Reference.

- -
+> [!NOTE] +> **See also**: For the docker-agent–native HTTP API (sessions, tool-call confirmation, runtime events), see the [API Server](../api-server/index.md). For full CLI flag documentation, see the [CLI Reference](../cli/index.md#docker-agent-serve-chat). diff --git a/docs/features/cli/index.md b/docs/features/cli/index.md index 3eb5386617..aaf87689d4 100644 --- a/docs/features/cli/index.md +++ b/docs/features/cli/index.md @@ -1,19 +1,15 @@ --- title: "CLI Reference" description: "Complete reference for all docker-agent command-line commands and flags." -permalink: /features/cli/ +keywords: docker agent, ai agents, features, cli reference --- # CLI Reference _Complete reference for all docker-agent command-line commands and flags._ -
-
No config needed -
-

Running docker agent run without a config file uses a built-in default agent. Perfect for quick experimentation.

- -
+> [!TIP] +> **No config needed**: Running `docker agent run` without a config file uses a built-in default agent. Perfect for quick experimentation. ## Commands @@ -37,7 +33,7 @@ $ docker agent run [config] [message...] [flags] | `--attach ` | Attach an image file to the initial message | | `--dry-run` | Initialize the agent without executing anything (useful for validating a config) | | `--remote ` | Use a remote runtime at the given address instead of running the agent locally | -| `--listen ` | Expose this run's control plane over HTTP so an external process can drive the running TUI (send follow-ups, stream events, read the title). Accepts `host:port` or `unix://`, `npipe://`, `fd://`. See the [API Server]({{ '/features/api-server/' | relative_url }}#listen). | +| `--listen ` | Expose this run's control plane over HTTP so an external process can drive the running TUI (send follow-ups, stream events, read the title). Accepts `host:port` or `unix://`, `npipe://`, `fd://`. See the [API Server](../api-server/index.md#listen). | | `--lean` | Use a simplified, non-alternate-screen TUI. Unlike the default full-screen TUI, this renders inline in the normal terminal buffer — useful in environments where an alternate screen is unwanted (e.g. inside tmux panes, CI with a tty, or log-friendly pipelines). Displays an ASCII art banner on startup. | | `--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`). | @@ -47,10 +43,10 @@ $ docker agent run [config] [message...] [flags] | `--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 | -| `--sandbox` | Run the agent inside a Docker sandbox (see [Sandbox]({{ '/configuration/sandbox/' | relative_url }})) | +| `--sandbox` | Run the agent inside a Docker sandbox (see [Sandbox](../../configuration/sandbox/index.md)) | | `--template ` | Template image for the sandbox (default: `docker/sandbox-templates:docker-agent`) | | `--sbx` | Prefer the `sbx` CLI backend when available (default `true`; set `--sbx=false` to force `docker sandbox`) | -| `--no-kit` | Disable the [auto-kit]({{ '/configuration/sandbox/' | relative_url }}#auto-kit): do not stage skills or prompt files into the sandbox | +| `--no-kit` | Disable the [auto-kit](../../configuration/sandbox/index.md#auto-kit): do not stage skills or prompt files into the sandbox | | `--agent-picker [refs]` | Show a full-screen interactive picker before launching, letting you browse and select an agent. Accepts an optional comma-separated list of agent references to show (defaults to `default,coder`). Arrow keys navigate; `?` toggles the YAML preview panel; Enter confirms. Not available in `--exec` or non-TTY modes. | | `-w, --worktree [name]` | Run the agent in a fresh git worktree of the working directory, isolating its changes from your checkout. Optionally name it (`--worktree=my-feature`); otherwise a name is generated. Requires the working directory to be inside a git repository. Every tool (the shell included) runs inside the worktree. Combine with `--working-dir` to branch from another repository, and with `--session` to resume into the same worktree later. Cannot be combined with `--remote` or `--sandbox`. When the session ends, a clean worktree is removed automatically; one with work prompts to keep or remove (never in `--exec`). | | `--worktree-base ` | Branch the `--worktree` from `` (a branch, tag, commit, or remote-tracking ref like `origin/main`) instead of the current `HEAD`. A remote-tracking ref is fetched first so the worktree starts from the latest remote state. Requires `--worktree`; cannot be combined with `--worktree-pr`, `--remote`, or `--sandbox`. | @@ -59,7 +55,7 @@ $ docker agent run [config] [message...] [flags] | `--env-from-file ` | Load environment variables from file (repeatable) | | `--code-mode-tools` | Provide a single tool to call other tools via JavaScript (forces code-mode tools globally) | | `--models-gateway ` | Route model traffic through a gateway. Also reads `DOCKER_AGENT_MODELS_GATEWAY` (legacy `CAGENT_MODELS_GATEWAY`) env var. | -| `--hook-pre-tool-use ` | Add a pre-tool-use hook command (repeatable). See [Hooks]({{ '/configuration/hooks/' | relative_url }}). | +| `--hook-pre-tool-use ` | Add a pre-tool-use hook command (repeatable). See [Hooks](../../configuration/hooks/index.md). | | `--hook-post-tool-use ` | Add a post-tool-use hook command (repeatable) | | `--hook-session-start ` | Add a session-start hook command (repeatable) | | `--hook-session-end ` | Add a session-end hook command (repeatable) | @@ -100,17 +96,11 @@ $ docker agent run --agent-picker $ docker agent run --agent-picker=agentcatalog/coder,agentcatalog/researcher ``` -
-
Lean, inline TUI -
-

Pass --lean to get a lightweight TUI that renders inline in your terminal (no alternate screen). It displays an ASCII art banner on startup and supports the same slash commands and streaming output as the full TUI, making it handy inside tmux, scripts, or any context where a full-screen takeover is unwanted.

-
+> [!TIP] +> **Lean, inline TUI**: Pass `--lean` to get a lightweight TUI that renders inline in your terminal (no alternate screen). It displays an ASCII art banner on startup and supports the same slash commands and streaming output as the full TUI, making it handy inside tmux, scripts, or any context where a full-screen takeover is unwanted. -
-
Isolate a run in a git worktree -
-

When the working directory is inside a git repository, --worktree creates a fresh git worktree and points the session at it, so the agent's edits land on a separate branch and never touch your checkout. Every tool — the shell included — runs inside the worktree. The worktree is stored under <data-dir>/worktrees/<name> on a branch named worktree-<name>.

-
+> [!TIP] +> **Isolate a run in a git worktree**: When the working directory is inside a git repository, `--worktree` creates a fresh [git worktree](https://git-scm.com/docs/git-worktree) and points the session at it, so the agent's edits land on a separate branch and never touch your checkout. Every tool — the shell included — runs inside the worktree. The worktree is stored under `/worktrees/` on a branch named `worktree-`. ```bash # Run in an isolated worktree with a generated name (e.g. "focused_turing") @@ -217,7 +207,7 @@ $ docker agent serve api || [flags] | `--pull-interval `| `0` | Periodically re-pull OCI/URL references and refresh the agent definition. `0` disables auto-pull. | | `--fake ` | (none) | Replay AI responses from a cassette file (for testing). Mutually exclusive with `--record`. | | `--record [path]` | (none) | Record AI API interactions to a cassette file. | -| `--mcp-oauth-redirect-uri ` | (none) | OAuth redirect URI for the unmanaged MCP OAuth flow in server mode. When set, the runtime drives PKCE and code exchange in-process and sends the full authorize URL to the client via elicitation. See [Remote MCP]({{ '/features/remote-mcp/' | relative_url }}) for details. | +| `--mcp-oauth-redirect-uri ` | (none) | OAuth redirect URI for the unmanaged MCP OAuth flow in server mode. When set, the runtime drives PKCE and code exchange in-process and sends the full authorize URL to the client via elicitation. See [Remote MCP](../remote-mcp/index.md) for details. | > **Diagnostics:** Set `CAGENT_PPROF_ADDR=127.0.0.1:6060` (or `--pprof-addr`, a hidden flag) to start a live Go pprof server at `/debug/pprof/`. Use a loopback address; a non-loopback binding logs a security warning. @@ -231,7 +221,7 @@ $ docker agent serve api ./agents/ # directory of agent $ docker agent serve api ociReference --pull-interval 10 # auto-refresh ``` -See [API Server]({{ '/features/api-server/' | relative_url }}) for the full HTTP API reference. +See [API Server](../api-server/index.md) for the full HTTP API reference. ### `docker agent serve mcp` @@ -260,7 +250,7 @@ $ docker agent serve mcp agent.yaml --working-dir /path/to/project $ docker agent serve mcp agentcatalog/coder ``` -See [MCP Mode]({{ '/features/mcp-mode/' | relative_url }}) for detailed setup. +See [MCP Mode](../mcp-mode/index.md) for detailed setup. ### `docker agent serve a2a` @@ -305,7 +295,7 @@ $ docker agent serve acp ./team.yaml $ docker agent serve acp agentcatalog/pirate ``` -See [ACP]({{ '/features/acp/' | relative_url }}) for details on the Agent Client Protocol. +See [ACP](../acp/index.md) for details on the Agent Client Protocol. ### `docker agent serve chat` @@ -341,7 +331,7 @@ $ curl http://127.0.0.1:8083/v1/chat/completions \ -d '{"model": "root", "messages": [{"role": "user", "content": "hello"}]}' ``` -See [Chat Server]({{ '/features/chat-server/' | relative_url }}) for the full feature reference. +See [Chat Server](../chat-server/index.md) for the full feature reference. ### `docker agent share push` / `docker agent share pull` @@ -362,7 +352,7 @@ $ docker agent share pull docker.io/username/my-agent:latest --force | ---------- | ---------- | ---------------------------------------------------------- | | `--force` | `pull` | Force pull even if the configuration already exists locally | -See [Agent Distribution]({{ '/concepts/distribution/' | relative_url }}) for full registry workflow details. +See [Agent Distribution](../../concepts/distribution/index.md) for full registry workflow details. ### `docker agent eval` @@ -395,7 +385,7 @@ $ docker agent eval agent.yaml --only "auth*" # only run matching ev $ docker agent eval agent.yaml --repeat 5 # repeat each eval 5 times ``` -See [Evaluation]({{ '/features/evaluation/' | relative_url }}) for details on creating eval sessions and interpreting results. +See [Evaluation](../evaluation/index.md) for details on creating eval sessions and interpreting results. ### `docker agent version` @@ -438,7 +428,7 @@ $ docker agent run yolo-coder - `--yolo` — Auto-approve all tool calls when running the alias - `--model <ref>` — Override the model for the alias - `--hide-tool-results` — Hide tool call results in the TUI when running the alias -- `--sandbox` — Always run the alias inside a [Docker sandbox]({{ '/configuration/sandbox/' | relative_url }}) +- `--sandbox` — Always run the alias inside a [Docker sandbox](../../configuration/sandbox/index.md) When listing aliases, options are shown in brackets: @@ -479,25 +469,21 @@ $ docker agent alias list --json JSON output is sorted by name and omits false/zero-valued fields. This is useful for scripting and automation. -
-
Override alias options -
-

Command-line flags override alias options. For example, docker agent run yolo-coder --yolo=false disables yolo mode even though the alias has it enabled.

- -
+> [!TIP] +> **Override alias options**: Command-line flags override alias options. For example, `docker agent run yolo-coder --yolo=false` disables yolo mode even though the alias has it enabled. -
-
Set a default agent -
-

Create a default alias to customize what docker agent starts with no arguments:

- 
$ docker agent alias add default /my/default/agent.yaml
-

Then simply run docker agent — it will launch that agent automatically.

- -
+> [!TIP] +> **Set a default agent**: Create a `default` alias to customize what `docker agent` starts with no arguments: +> +> ```bash +> $ docker agent alias add default /my/default/agent.yaml +> ``` +> +> Then simply run `docker agent` — it will launch that agent automatically. ### `docker agent sandbox` -Manage settings shared by every [`--sandbox`]({{ '/configuration/sandbox/' | relative_url }}) run — today, the persistent network allowlist that turns a `Blocked by network policy` 403 into a one-line, durable fix: +Manage settings shared by every [`--sandbox`](../../configuration/sandbox/index.md) run — today, the persistent network allowlist that turns a `Blocked by network policy` 403 into a one-line, durable fix: ```bash # Allow a host on every subsequent --sandbox run. @@ -548,7 +534,7 @@ These flags are accepted by every command that loads an agent (`run`, `run --exe | `--env-from-file ` | Load environment variables from file (repeatable). | | `--code-mode-tools` | Provide a single tool to call other tools via JavaScript (forces code-mode tools globally). | | `--models-gateway ` | Route model traffic through a gateway. Reads `DOCKER_AGENT_MODELS_GATEWAY` (legacy `CAGENT_MODELS_GATEWAY`) env var. | -| `--hook-pre-tool-use ` | Add a pre-tool-use hook command (repeatable). See [Hooks]({{ '/configuration/hooks/' | relative_url }}). | +| `--hook-pre-tool-use ` | Add a pre-tool-use hook command (repeatable). See [Hooks](../../configuration/hooks/index.md). | | `--hook-post-tool-use ` | Add a post-tool-use hook command (repeatable). | | `--hook-session-start ` | Add a session-start hook command (repeatable). | | `--hook-session-end ` | Add a session-end hook command (repeatable). | @@ -567,9 +553,5 @@ Commands that accept a config support multiple reference types: | Alias | `pirate` (after `docker agent alias add`) | | Default | (no argument) — uses built-in default agent | -
-
Debugging -
-

Having issues? See Troubleshooting for debug mode, log analysis, and common solutions.

- -
+> [!NOTE] +> **Debugging**: Having issues? See [Troubleshooting](../../community/troubleshooting/index.md) for debug mode, log analysis, and common solutions. diff --git a/docs/features/evaluation/index.md b/docs/features/evaluation/index.md index 31fbefb6f4..e476033962 100644 --- a/docs/features/evaluation/index.md +++ b/docs/features/evaluation/index.md @@ -1,7 +1,7 @@ --- title: "Evaluation" description: "Measure agent quality with automated evaluations — tool call accuracy, response relevance, output size, and more." -permalink: /features/evaluation/ +keywords: docker agent, ai agents, features, evaluation --- # Evaluation @@ -12,12 +12,8 @@ _Measure agent quality with automated evaluations — tool call accuracy, respon The `docker agent eval` command runs your agent against a set of recorded sessions and scores the results. Each eval session captures a user question, the expected tool calls, and criteria the response must satisfy. docker-agent replays the question, compares the agent's behavior to expectations, and produces a report. -
-
Docker required -
-

Evaluations run inside Docker containers for isolation. Each eval gets a clean environment with optional setup scripts. Docker Desktop (or Docker Engine) must be running.

- -
+> [!NOTE] +> **Docker required**: Evaluations run inside Docker containers for isolation. Each eval gets a clean environment with optional setup scripts. Docker Desktop (or Docker Engine) must be running. ## Quick Start @@ -146,12 +142,8 @@ The easiest way to create eval sessions is from real conversations: 3. Use the `/eval` slash command in the TUI to save the session as an eval file 4. Edit the generated JSON to add `evals` criteria (relevance, size, etc.) -
-
Tip -
-

Start with tool call scoring (automatic from recorded sessions), then add relevance criteria for the responses you care most about.

- -
+> [!TIP] +> Start with tool call scoring (automatic from recorded sessions), then add relevance criteria for the responses you care most about. ## CLI Flags @@ -189,12 +181,8 @@ After a run completes, docker-agent produces: - **Sessions JSON** — Exported session data for analysis - **Log file** — Debug-level log of the entire evaluation run -
-
Debugging Failed Evals -
-

Use --keep-containers to preserve containers after evaluation. You can then inspect them with docker exec to understand why an eval failed. The session database (.db file) contains the full conversation history for each eval.

- -
+> [!TIP] +> **Debugging Failed Evals**: Use `--keep-containers` to preserve containers after evaluation. You can then inspect them with `docker exec` to understand why an eval failed. The session database (`.db` file) contains the full conversation history for each eval. ```bash $ docker agent eval demo.yaml ./evals @@ -239,9 +227,5 @@ $ docker agent run agent.yaml $ docker agent eval agent.yaml ./evals ``` -
-
See also -
-

Use /eval in the TUI to create eval sessions from conversations. See the CLI Reference for all docker agent eval flags. Example eval configs are in examples/eval on GitHub.

- -
+> [!NOTE] +> **See also**: Use `/eval` in the [TUI](../tui/index.md) to create eval sessions from conversations. See the [CLI Reference](../cli/index.md) for all `docker agent eval` flags. Example eval configs are in [examples/eval](https://github.com/docker/docker-agent/tree/main/examples/eval) on GitHub. diff --git a/docs/features/harnesses/index.md b/docs/features/harnesses/index.md index 662d498692..31fd65d572 100644 --- a/docs/features/harnesses/index.md +++ b/docs/features/harnesses/index.md @@ -1,7 +1,7 @@ --- title: "Coding Harnesses" description: "Delegate coding tasks to external AI coding CLIs (Claude Code, Codex, opencode) as sub-agents." -permalink: /features/harnesses/ +keywords: docker agent, ai agents, features, coding harnesses --- # Coding Harnesses @@ -17,11 +17,8 @@ This pattern gives you the best of both worlds: - **External CLI strengths** — deep IDE integration, specialized coding workflows, CLI-native tool access - **Docker Agent strengths** — multi-agent coordination, hook-based auditing and policy enforcement, permission controls, OCI distribution, and the full agent config schema -
-
When to use harnesses -
-

Use a harness when you want a Claude Code / Codex / opencode session to act as a sub-agent inside a larger Docker Agent workflow — for example, an orchestrator that plans work and delegates coding tasks to specialized harness agents.

-
+> [!NOTE] +> **When to use harnesses**: Use a harness when you want a Claude Code / Codex / opencode session to act as a sub-agent inside a larger Docker Agent workflow — for example, an orchestrator that plans work and delegates coding tasks to specialized harness agents. ## Prerequisites @@ -102,11 +99,8 @@ Harness agents bypass the Docker Agent model pipeline entirely. As a result: - **`model:` routing is unavailable.** The harness CLI manages model selection; Docker Agent's `models:` configuration and routing rules do not apply to harness agents. - **Token usage tracking depends on the external CLI.** Docker Agent records usage when the CLI reports it (Claude Code and Codex both report usage data). If the CLI does not emit usage data, the session will show zero token usage. -
-
No Docker Agent toolsets inside a harness -
-

Do not configure toolsets: on a harness agent — they are silently ignored. If you need Docker Agent toolsets alongside external coding capabilities, use a standard sub-agent with transfer_task rather than a harness.

-
+> [!WARNING] +> **No Docker Agent toolsets inside a harness**: Do not configure `toolsets:` on a harness agent — they are silently ignored. If you need Docker Agent toolsets alongside external coding capabilities, use a standard sub-agent with `transfer_task` rather than a harness. ## Hook Behavior @@ -114,7 +108,7 @@ Hooks work normally on harness agents, including `before_llm_call` and `after_ll The `model_id` field in hook payloads is set to the harness label (e.g. `claude-code`) rather than a canonical `provider/model` string. This applies to `before_llm_call`, `after_llm_call`, and any other event that carries `model_id`. -See [Hooks]({{ '/configuration/hooks/' | relative_url }}) for the full hook reference. +See [Hooks](../../configuration/hooks/index.md) for the full hook reference. ## Recipe: Orchestrator + Harness Sub-Agents (Sequential) @@ -193,11 +187,11 @@ agents: The orchestrator calls `run_background_agent` for each task, monitors progress with `list_background_agents`, and collects results with `view_background_agent`. See the [full example on GitHub](https://github.com/docker/docker-agent/blob/main/examples/coding_harness_background_agents.yaml). -For the general background agents reference, see [Background Agents]({{ '/tools/background-agents/' | relative_url }}). +For the general background agents reference, see [Background Agents](../../tools/background-agents/index.md). ## See Also -- [Multi-Agent Systems]({{ '/concepts/multi-agent/' | relative_url }}) — orchestration patterns -- [Background Agents]({{ '/tools/background-agents/' | relative_url }}) — parallel task dispatch -- [Hooks]({{ '/configuration/hooks/' | relative_url }}) — auditing and policy enforcement -- [Agent Configuration]({{ '/configuration/agents/' | relative_url }}) — full agent schema reference +- [Multi-Agent Systems](../../concepts/multi-agent/index.md) — orchestration patterns +- [Background Agents](../../tools/background-agents/index.md) — parallel task dispatch +- [Hooks](../../configuration/hooks/index.md) — auditing and policy enforcement +- [Agent Configuration](../../configuration/agents/index.md) — full agent schema reference diff --git a/docs/features/mcp-mode/index.md b/docs/features/mcp-mode/index.md index e3f1dabd60..2e716d3b17 100644 --- a/docs/features/mcp-mode/index.md +++ b/docs/features/mcp-mode/index.md @@ -1,7 +1,7 @@ --- title: "MCP Mode" description: "Expose your docker-agent agents as MCP tools for use in Claude Desktop, Claude Code, and other MCP-compatible applications." -permalink: /features/mcp-mode/ +keywords: docker agent, ai agents, features, mcp mode --- # MCP Mode @@ -17,12 +17,8 @@ The `docker agent serve mcp` command makes your agents available to any applicat - Build reusable agent teams consumable from any MCP client - Integrate domain-specific agents into existing workflows -
-
What is MCP? -
-

The Model Context Protocol is an open standard for connecting AI tools. See also Remote MCP Servers for connecting to cloud services.

- -
+> [!NOTE] +> **What is MCP?** The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard for connecting AI tools. See also [Remote MCP Servers](../remote-mcp/index.md) for connecting to cloud services. ## Basic Usage @@ -59,7 +55,7 @@ $ docker agent serve mcp ./agent.yaml --http --listen 0.0.0.0:9090 | `--tool-name` | (none) | Override the MCP tool identifier clients call (defaults to agent name); only valid when exposing one agent. | | `--mcp-keepalive` | `0` | Interval between MCP keep-alive pings (e.g. `30s`); `0` disables keep-alive. | -Runtime configuration flags such as `--working-dir`, `--env-from-file`, `--models-gateway`, and hook flags are also available — see the [CLI reference]({{ '/features/cli/' | relative_url }}). +Runtime configuration flags such as `--working-dir`, `--env-from-file`, `--models-gateway`, and hook flags are also available — see the [CLI reference](../cli/index.md). ## Using with Claude Desktop diff --git a/docs/features/remote-mcp/index.md b/docs/features/remote-mcp/index.md index d9c337fb52..ee3af10c43 100644 --- a/docs/features/remote-mcp/index.md +++ b/docs/features/remote-mcp/index.md @@ -1,7 +1,7 @@ --- title: "Remote MCP Servers" description: "Connect docker-agent to cloud services via remote MCP servers with built-in OAuth authentication." -permalink: /features/remote-mcp/ +keywords: docker agent, ai agents, features, remote mcp servers --- # Remote MCP Servers @@ -20,19 +20,11 @@ toolsets: transport_type: "streamable" ``` -
-
OAuth flow -
-

When you connect to a remote MCP server that requires OAuth, docker-agent opens your browser automatically for authentication. Tokens are cached for subsequent sessions.

+> [!TIP] +> **OAuth flow**: When you connect to a remote MCP server that requires OAuth, docker-agent opens your browser automatically for authentication. Tokens are cached for subsequent sessions. -
- -
-
Cancelling the authorization dialog -
-

If you dismiss the OAuth authorization dialog, the request is cancelled cleanly — no repeated prompts appear. The agent will report that authorization was declined. To try again, simply re-enable the server or repeat the request that triggered the flow.

- -
+> [!TIP] +> **Cancelling the authorization dialog**: If you dismiss the OAuth authorization dialog, the request is cancelled cleanly — no repeated prompts appear. The agent will report that authorization was declined. To try again, simply re-enable the server or repeat the request that triggered the flow. ## Configuration @@ -48,36 +40,27 @@ toolsets: allow_private_ips: true ``` -For full configuration details, see the [Tool Config]({{ '/configuration/tools/' | relative_url }}) page. +For full configuration details, see the [Tool Config](../../configuration/tools/index.md) page. Set `allow_private_ips: true` on a remote MCP toolset only when the MCP server or its OAuth registration/token endpoints intentionally resolve to private, loopback, or link-local addresses. The default blocks those OAuth helper requests to reduce SSRF risk. -
-
Headers forwarded during OAuth discovery -
-

Configured headers are forwarded to OAuth protected-resource-metadata discovery requests directed at the MCP server's own host — not to third-party authorization servers. This allows services like Grafana Cloud that require a routing header (e.g. X-Grafana-URL) on the discovery request to scope the OAuth flow correctly. Headers are never sent to a different host than the one in remote.url.

-
- -
-
Automatic reconnection after idle timeouts -
-

Remote MCP connections (Streamable HTTP / SSE) automatically reconnect after the server closes an idle connection — no configuration needed. Services like Notion and Linear close idle connections periodically; docker-agent detects the clean close and reconnects with exponential backoff. To tune reconnect behaviour or disable reconnection entirely, use the lifecycle block.

-
- -
-
Automatic recovery from revoked or rotated OAuth tokens -
-

If a remote MCP server rejects the cached token with a 401 invalid_token error (for example, because the token was revoked or rotated server-side), docker-agent handles the failure automatically:

-
    -
  • Silent refresh: when a refresh token is available, docker-agent silently exchanges it for a new access token and replays the request — no user interaction required.
    • -
  • Re-authentication prompt: when the refresh token is absent or has also expired, the toolset transitions to a "needs re-auth" state and surfaces an OAuth prompt on your next message (exactly like the first-time flow).
    • -
-

Either way, the agent never burns 5 reconnect attempts on an auth failure — it fails fast and either refreshes silently or defers to interactive re-auth. If you want to trigger re-auth immediately without waiting for the next message, run /toolset-restart <name> from the TUI.

-
+> [!NOTE] +> **Headers forwarded during OAuth discovery**: Configured `headers` are forwarded to OAuth protected-resource-metadata discovery requests directed at the MCP server's own host — not to third-party authorization servers. This allows services like Grafana Cloud that require a routing header (e.g. `X-Grafana-URL`) on the discovery request to scope the OAuth flow correctly. Headers are never sent to a different host than the one in `remote.url`. + +> [!NOTE] +> **Automatic reconnection after idle timeouts**: Remote MCP connections (Streamable HTTP / SSE) automatically reconnect after the server closes an idle connection — no configuration needed. Services like Notion and Linear close idle connections periodically; docker-agent detects the clean close and reconnects with exponential backoff. To tune reconnect behaviour or disable reconnection entirely, use the [`lifecycle` block](../../configuration/tools/index.md#toolset-lifecycle). + +> [!NOTE] +> **Automatic recovery from revoked or rotated OAuth tokens**: If a remote MCP server rejects the cached token with a `401 invalid_token` error (for example, because the token was revoked or rotated server-side), docker-agent handles the failure automatically: +> +> - **Silent refresh:** when a refresh token is available, docker-agent silently exchanges it for a new access token and replays the request — no user interaction required. +> - **Re-authentication prompt:** when the refresh token is absent or has also expired, the toolset transitions to a "needs re-auth" state and surfaces an OAuth prompt on your next message (exactly like the first-time flow). +> +> Either way, the agent never burns 5 reconnect attempts on an auth failure — it fails fast and either refreshes silently or defers to interactive re-auth. If you want to trigger re-auth immediately without waiting for the next message, run `/toolset-restart ` from the TUI. ### OAuth for servers without Dynamic Client Registration -Most remote MCP servers that require OAuth support [Dynamic Client Registration (RFC 7591)]({{ 'https://datatracker.ietf.org/doc/html/rfc7591' }}) — no configuration is needed, docker-agent handles the flow for you. +Most remote MCP servers that require OAuth support [Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) — no configuration is needed, docker-agent handles the flow for you. For servers that do **not** support DCR, provide explicit OAuth credentials with the `oauth:` block: @@ -104,7 +87,7 @@ toolsets: | `scopes` | array[string] | ✗ | Scopes to request during the authorization step. Values are server-specific. | | `callbackRedirectURL` | string | ✗ | Custom OAuth redirect URI. Useful when the auth server requires HTTPS or a pre-registered URL. The literal placeholder `${callbackPort}` is replaced with the actual local callback port. See below. | -Secrets should be stored in a credential helper or environment variable rather than committed — see [Secrets]({{ '/guides/secrets/' | relative_url }}) for interpolation patterns. +Secrets should be stored in a credential helper or environment variable rather than committed — see [Secrets](../../guides/secrets/index.md) for interpolation patterns. ### Custom redirect URI (`callbackRedirectURL`) @@ -168,12 +151,8 @@ The client-driven `{access_token, ...}` reply shape is still accepted on the `-- A per-toolset `callbackRedirectURL` (in the YAML) overrides the runtime-wide `--mcp-oauth-redirect-uri` for that toolset. -
-
Security note -
-

The POST /api/mcp-oauth/callback route is open by default (no auth required) when --auth-token is unset. State values are 128-bit opaque tokens, so brute-force is infeasible, but a state value that leaks (e.g. via debug logs or a compromised host) could be exploited by an attacker to inject a code. Set --auth-token when docker agent serve api listens on a network-reachable interface. When set, --auth-token enforces Bearer-token authentication on all API routes including this callback endpoint.

- -
+> [!WARNING] +> **Security note**: The `POST /api/mcp-oauth/callback` route is open by default (no auth required) when `--auth-token` is unset. State values are 128-bit opaque tokens, so brute-force is infeasible, but a state value that leaks (e.g. via debug logs or a compromised host) could be exploited by an attacker to inject a code. Set `--auth-token` when `docker agent serve api` listens on a network-reachable interface. When set, `--auth-token` enforces Bearer-token authentication on all API routes including this callback endpoint. ## Project Management & Collaboration @@ -283,9 +262,5 @@ agents: instruction: Use Vercel for deployments. ``` -
-
Growing list -
-

This list is updated as more services add MCP support. If a service you use isn't listed, check their documentation — many providers are adding MCP endpoints regularly.

- -
+> [!NOTE] +> **Growing list**: This list is updated as more services add MCP support. If a service you use isn't listed, check their documentation — many providers are adding MCP endpoints regularly. diff --git a/docs/features/skills/index.md b/docs/features/skills/index.md index 9f3beb1c83..e8f6b1995b 100644 --- a/docs/features/skills/index.md +++ b/docs/features/skills/index.md @@ -1,7 +1,7 @@ --- title: "Skills" description: "Skills provide specialized instructions that agents can load on demand when a task matches a skill's description." -permalink: /features/skills/ +keywords: docker agent, ai agents, features, skills --- # Skills @@ -27,12 +27,8 @@ agents: - type: filesystem # required for reading skill files ``` -
-
Tip -
-

Skills are perfect for encoding team-specific workflows (PR review, deployment, coding standards) that apply across projects.

- -
+> [!TIP] +> Skills are perfect for encoding team-specific workflows (PR review, deployment, coding standards) that apply across projects. ## Filtering Skills @@ -111,14 +107,10 @@ Inline skills carry their body in the config itself, so they need no `SKILL.md` | `context` | No | Set to `fork` to run the skill as an isolated sub-agent | | `model` | No | Override the model used while running a fork-mode skill | | `allowed_tools` | No | For a fork-mode skill, restricts the sub-session to the parent tools whose names match an entry (glob or exact). See [Scoping a fork skill's tools](#scoping-a-fork-skills-tools). | -| `toolsets` | No | For a fork-mode skill, names of top-level [`toolsets`]({{ '/configuration/overview/' | relative_url }}#reusable-toolsets) to expose in the sub-session on top of the inherited tools. | - -
-
Inline vs. file-based skills -
-

Inline skills support the subset of the SKILL.md format that fits in YAML. They cannot bundle supporting files (no read_skill_file) or use !`command` expansion. For skills that need bundled resources or executable helpers, use a SKILL.md directory instead.

+| `toolsets` | No | For a fork-mode skill, names of top-level [`toolsets`](../../configuration/overview/index.md#reusable-toolsets-toolsets) to expose in the sub-session on top of the inherited tools. | -
+> [!NOTE] +> **Inline vs. file-based skills**: Inline skills support the subset of the SKILL.md format that fits in YAML. They cannot bundle supporting files (no `read_skill_file`) or use `!`command`` expansion. For skills that need bundled resources or executable helpers, use a `SKILL.md` directory instead. ## SKILL.md Format @@ -152,7 +144,7 @@ When asked to create a Dockerfile: | `context` | No | Set to `fork` to run the skill as an isolated sub-agent (see below) | | `model` | No | Override the model used while running the skill as a sub-agent (fork only) | | `allowed-tools` | No | For a fork-mode skill, restricts the sub-session to the parent tools whose names match an entry (YAML list or comma-separated string). See [Scoping a fork skill's tools](#scoping-a-fork-skills-tools). | -| `toolsets` | No | For a fork-mode skill, names of top-level [`toolsets`]({{ '/configuration/overview/' | relative_url }}#reusable-toolsets) to expose in the sub-session (YAML list or comma-separated string). | +| `toolsets` | No | For a fork-mode skill, names of top-level [`toolsets`](../../configuration/overview/index.md#reusable-toolsets-toolsets) to expose in the sub-session (YAML list or comma-separated string). | | `license` | No | License identifier (e.g. `Apache-2.0`) | | `compatibility` | No | Free-text compatibility notes | | `metadata` | No | Arbitrary key-value pairs (e.g. `author`, `version`) | @@ -185,12 +177,8 @@ When the agent encounters a task that matches a `context: fork` skill, it uses t - **Folds the result** — only the sub-agent's final answer is returned to the parent as the tool result - **Inherits the parent's model and tools** — the sub-agent can use all tools available to the parent agent (scope this with `allowed_tools` / `toolsets`, see [Scoping a fork skill's tools](#scoping-a-fork-skills-tools)) -
-
When to use context: fork -
-

Use context: fork for skills that involve many steps, heavy tool usage, or that should not clutter the main conversation — for example dependency bumping, large refactors, or code generation pipelines.

- -
+> [!TIP] +> **When to use context: fork**: Use `context: fork` for skills that involve many steps, heavy tool usage, or that should not clutter the main conversation — for example dependency bumping, large refactors, or code generation pipelines. ### Overriding the model for a fork skill @@ -245,7 +233,7 @@ patterns (e.g. `read_*`) and otherwise match exactly. This is the Claude-Code-compatible `allowed-tools` field, now enforced for fork skills rather than merely recorded. -`toolsets` references reusable [top-level toolsets]({{ '/configuration/overview/' | relative_url }}#reusable-toolsets) +`toolsets` references reusable [top-level toolsets](../../configuration/overview/index.md#reusable-toolsets-toolsets) by name. The referenced toolsets are exposed in the sub-session **in addition to** the inherited tools, and they bypass the `allowed_tools` filter (the skill explicitly asked for them). @@ -298,12 +286,8 @@ toolsets: --- ``` -
-
Fork only -
-

Both fields are rejected by config validation when set on a non-fork skill, and a toolsets entry that doesn't resolve to a top-level toolset is a load-time error.

- -
+> [!NOTE] +> **Fork only**: Both fields are rejected by config validation when set on a non-fork skill, and a `toolsets` entry that doesn't resolve to a top-level toolset is a load-time error. ## Search Paths @@ -350,7 +334,7 @@ When multiple skills share the same name: ## Skills in Sandbox Mode -When you run an agent with [`--sandbox`]({{ '/configuration/sandbox/' | relative_url }}), the sandbox VM has its own filesystem with no access to your host's skill directories. docker-agent handles this transparently via the [auto-kit]({{ '/configuration/sandbox/' | relative_url }}#auto-kit): every discovered local skill is staged into a per-agent kit on the host, run through best-effort secret redaction (see the [auto-kit]({{ '/configuration/sandbox/' | relative_url }}#secret-redaction) docs), and bind-mounted read-only into the sandbox so the agent sees the same skills inside the VM as on the host. No configuration is required — use `--no-kit` only if you explicitly want to run the sandbox without any host skills. +When you run an agent with [`--sandbox`](../../configuration/sandbox/index.md), the sandbox VM has its own filesystem with no access to your host's skill directories. docker-agent handles this transparently via the [auto-kit](../../configuration/sandbox/index.md#auto-kit): every discovered local skill is staged into a per-agent kit on the host, run through best-effort secret redaction (see the [auto-kit](../../configuration/sandbox/index.md#secret-redaction) docs), and bind-mounted read-only into the sandbox so the agent sees the same skills inside the VM as on the host. No configuration is required — use `--no-kit` only if you explicitly want to run the sandbox without any host skills. ## Creating a Skill @@ -378,10 +362,7 @@ EOF The skill will automatically be available to any agent with skills enabled (`skills: true`, or a list that targets its name — see [Filtering Skills](#filtering-skills)). -
-
See also -
-

Skills are enabled in the Agent Config with the skills property (boolean or list). For tool-based capabilities, see Tools.

-

Example configs: examples/skills_inline.yaml (inline skill definition), examples/skills_fork_toolsets.yaml (scoping a fork skill's tools), examples/skills_filter.yaml (filtering which skills load).

- -
+> [!NOTE] +> **See also**: Skills are enabled in the [Agent Config](../../configuration/agents/index.md) with the `skills` property (boolean or list). For tool-based capabilities, see [Tools](../../concepts/tools/index.md). +> +> Example configs: [`examples/skills_inline.yaml`](https://github.com/docker/docker-agent/blob/main/examples/skills_inline.yaml) (inline skill definition), [`examples/skills_fork_toolsets.yaml`](https://github.com/docker/docker-agent/blob/main/examples/skills_fork_toolsets.yaml) (scoping a fork skill's tools), [`examples/skills_filter.yaml`](https://github.com/docker/docker-agent/blob/main/examples/skills_filter.yaml) (filtering which skills load). diff --git a/docs/features/snapshots/index.md b/docs/features/snapshots/index.md index 4562260cdd..a0eabf352f 100644 --- a/docs/features/snapshots/index.md +++ b/docs/features/snapshots/index.md @@ -1,7 +1,7 @@ --- title: "Snapshots" description: "Shadow-git snapshots capture your workspace at turn boundaries so you can review what an agent changed and undo it without touching your real git history." -permalink: /features/snapshots/ +keywords: docker agent, ai agents, features, snapshots --- # Snapshots @@ -24,13 +24,8 @@ Snapshots only ever touch files on disk. They never write commits to your repository, never move your `HEAD`, and never appear in `git log` or `git status`. -
-
Git repositories only -
-

The snapshot machinery is a no-op outside a git worktree. It needs a git - repository to scope which files belong to your project and to mirror the - repository's ignore rules.

-
+> [!NOTE] +> **Git repositories only**: The snapshot machinery is a no-op outside a git worktree. It needs a git repository to scope which files belong to your project and to mirror the repository's ignore rules. ## Enabling Snapshots @@ -45,7 +40,7 @@ settings: Omit `snapshot` or set it to `false` to leave automatic snapshots off. -You can also wire the [`snapshot` built-in hook]({{ '/configuration/hooks/#available-built-ins' | relative_url }}) +You can also wire the [`snapshot` built-in hook](../../configuration/hooks/index.md#available-built-ins) into a single agent instead of enabling it globally: ```yaml @@ -67,7 +62,7 @@ for a complete configuration. ## Using Snapshots in the TUI -When snapshots are enabled, the [TUI]({{ '/features/tui/' | relative_url }}) +When snapshots are enabled, the [TUI](../tui/index.md) exposes two slash commands: - **`/undo`** restores files from the most recent snapshot (one step back). @@ -106,8 +101,8 @@ when snapshots are turned off. ## See Also -- [Hooks]({{ '/configuration/hooks/' | relative_url }}) — the `snapshot` +- [Hooks](../../configuration/hooks/index.md) — the `snapshot` built-in and the events it can run on. -- [Terminal UI]({{ '/features/tui/' | relative_url }}) — the `/undo` and +- [Terminal UI](../tui/index.md) — the `/undo` and `/snapshots` commands. - [`examples/snapshot_hooks.yaml`](https://github.com/docker/docker-agent/blob/main/examples/snapshot_hooks.yaml) — a complete snapshot hook configuration. diff --git a/docs/features/tui/index.md b/docs/features/tui/index.md index 3bff031853..b15a7dbacf 100644 --- a/docs/features/tui/index.md +++ b/docs/features/tui/index.md @@ -1,16 +1,14 @@ --- title: "Terminal UI (TUI)" description: "docker-agent's default interface is a rich, interactive terminal UI with file attachments, themes, session management, and more." -permalink: /features/tui/ +keywords: docker agent, ai agents, features, terminal ui (tui) --- # Terminal UI (TUI) _docker-agent's default interface is a rich, interactive terminal UI with file attachments, themes, session management, and more._ -
- docker-agent TUI in action showing an interactive agent session -
+![docker-agent TUI in action showing an interactive agent session](../../demo.gif) ## Launching the TUI @@ -168,7 +166,7 @@ When enabled, docker-agent records filesystem snapshots at turn boundaries. The Neither command removes messages from the session transcript — they only touch files on disk. Both commands (and the matching command-palette entries) are hidden when snapshots are turned off. Omit `snapshot` or set it to `false` to leave automatic snapshots off; agents can still configure snapshot hooks manually. -See [Snapshots]({{ '/features/snapshots/' | relative_url }}) for how the shadow-git machinery works and how to wire it per-agent. +See [Snapshots](../snapshots/index.md) for how the shadow-git machinery works and how to wire it per-agent. ## File Attachments @@ -195,12 +193,8 @@ Change the AI model during a session with `/model` or Ctrl+M -
Tip -
-

Use model switching to try a more capable model for complex tasks, or a cheaper one for simple queries — without modifying your YAML config.

- -
+> [!TIP] +> Use model switching to try a more capable model for complex tasks, or a cheaper one for simple queries — without modifying your YAML config. ## Editable Messages @@ -239,12 +233,8 @@ Customize session titles to make them more meaningful and easier to find. By def 2. Type your new title 3. Press Enter to save, or Escape to cancel -
-
Note -
-

Manually set titles are preserved and won’t be overwritten by auto-generation. Title changes are persisted immediately to the session.

- -
+> [!NOTE] +> Manually set titles are preserved and won’t be overwritten by auto-generation. Title changes are persisted immediately to the session. ## Keyboard Shortcuts @@ -388,19 +378,11 @@ settings: **At runtime:** Use the `/theme` command to open the theme picker and select from available themes. Your selection is saved globally in `~/.config/cagent/config.yaml` under `settings.theme` and persists across sessions. -
-
Hot Reload -
-

Custom themes auto-reload when you save changes to the file — no restart needed. This makes it easy to tweak colors in real-time.

- -
+> [!TIP] +> **Hot Reload**: Custom themes auto-reload when you save changes to the file — no restart needed. This makes it easy to tweak colors in real-time. -
-
Partial overrides -
-

All user themes are applied on top of the default theme. If you want to customize a built-in theme (e.g., dracula), copy its full YAML from the built-in themes on GitHub into ~/.cagent/themes/ and edit the copy. Otherwise, omitted values will use default colors, not the original theme's colors.

- -
+> [!WARNING] +> **Partial overrides**: All user themes are applied on top of the `default` theme. If you want to customize a built-in theme (e.g., `dracula`), copy its full YAML from the [built-in themes on GitHub](https://github.com/docker/docker-agent/tree/main/pkg/tui/styles/themes) into `~/.cagent/themes/` and edit the copy. Otherwise, omitted values will use `default` colors, not the original theme's colors. ## Tool Permissions @@ -412,12 +394,8 @@ When an agent calls a tool, docker-agent shows a confirmation dialog by default. **Granular permissions:** The permission system supports pattern-based matching. When you “Always allow” a specific tool command, only that exact pattern is auto-approved — other commands from the same tool still require confirmation. This lets you auto-approve safe, read-only operations while maintaining control over destructive ones. -
-
YOLO mode -
-

Use --yolo or the /yolo command to auto-approve all tool calls. You can also toggle this mid-session. For aliases, set --yolo when creating the alias: docker agent alias add fast agentcatalog/coder --yolo.

- -
+> [!TIP] +> **YOLO mode**: Use `--yolo` or the `/yolo` command to auto-approve all tool calls. You can also toggle this mid-session. For aliases, set `--yolo` when creating the alias: `docker agent alias add fast agentcatalog/coder --yolo`. ## Notifications diff --git a/docs/getting-started/installation/index.md b/docs/getting-started/installation/index.md index 9ee66d1d6d..70ef8aa4e1 100644 --- a/docs/getting-started/installation/index.md +++ b/docs/getting-started/installation/index.md @@ -1,7 +1,7 @@ --- title: "Installation" description: "Get docker-agent running on your system in minutes." -permalink: /getting-started/installation/ +keywords: docker agent, ai agents, getting started, installation --- # Installation @@ -21,12 +21,8 @@ Starting with [Docker Desktop 4.63](https://docs.docker.com/desktop/release-note $ docker agent version ``` -
-
Tip -
-

Docker Desktop bundles docker-agent and keeps it up to date. This is the easiest way to get started, especially if you want to use Docker MCP tools and Docker Model Runner.

- -
+> [!TIP] +> Docker Desktop bundles docker-agent and keeps it up to date. This is the easiest way to get started, especially if you want to use Docker MCP tools and Docker Model Runner. ## Homebrew (macOS / Linux) @@ -84,12 +80,8 @@ With self-updates enabled, docker-agent checks the latest GitHub release before Self-updates are fail-safe: if checking, downloading, verifying, installing, or restarting fails, docker-agent keeps running the current binary. Version/help/completion commands and Docker CLI plugin metadata handshakes do not trigger self-updates. -
-
Package-manager installs -
-

Docker Desktop and Homebrew already manage docker-agent updates. Prefer those update mechanisms when you installed docker-agent that way. Self-updates are mainly intended for standalone release binaries.

- -
+> [!NOTE] +> **Package-manager installs**: Docker Desktop and Homebrew already manage docker-agent updates. Prefer those update mechanisms when you installed docker-agent that way. Self-updates are mainly intended for standalone release binaries. ## Build from Source @@ -113,12 +105,8 @@ task build ./bin/docker-agent --help ``` -
-
Building on Windows -
-

On Windows, use task build-local instead of task build. This builds the binary inside a Docker container using Docker Buildx, which avoids issues with Windows-specific toolchain setup and CGo cross-compilation. The output goes to the ./dist directory.

- -
+> [!TIP] +> **Building on Windows**: On Windows, use `task build-local` instead of `task build`. This builds the binary inside a Docker container using Docker Buildx, which avoids issues with Windows-specific toolchain setup and CGo cross-compilation. The output goes to the `./dist` directory. ## Set Up API Keys @@ -133,14 +121,10 @@ export MISTRAL_API_KEY="..." # Mistral export OPENROUTER_API_KEY="..." # OpenRouter ``` -See [Configuration Overview]({{ '/configuration/overview/#environment-variables' | relative_url }}) for the full list of supported providers and environment variables. - -
-
Note -
-

You only need the key(s) for the provider(s) you configure in your agent YAML. If you use Docker Model Runner (DMR), no API key is needed — models run locally.

+See [Configuration Overview](../../configuration/overview/index.md#environment-variables) for the full list of supported providers and environment variables. -
+> [!NOTE] +> You only need the key(s) for the provider(s) you configure in your agent YAML. If you use Docker Model Runner (DMR), no API key is needed — models run locally. ## Verify Installation @@ -157,15 +141,5 @@ $ docker agent run agentcatalog/pirate ## What's Next? -
- -
⚡
-

Quick Start

-

Create and run your first agent in under 5 minutes.

- - -
🔧
-

Troubleshooting

-

Something not working? Debug mode, common issues, and solutions.

- -
+- **[Quick Start](../quickstart/index.md)** — Create and run your first agent in under 5 minutes. +- **[Troubleshooting](../../community/troubleshooting/index.md)** — Something not working? Debug mode, common issues, and solutions. diff --git a/docs/getting-started/introduction/index.md b/docs/getting-started/introduction/index.md index 4ef43beb8c..1d82f96548 100644 --- a/docs/getting-started/introduction/index.md +++ b/docs/getting-started/introduction/index.md @@ -1,7 +1,7 @@ --- title: "Introduction" description: "Docker Agent is a multi-agent runtime that lets you build, run, and share AI agents with a YAML or HCL config — no glue code required." -permalink: /getting-started/introduction/ +keywords: docker agent, ai agents, getting started, introduction --- # Introduction @@ -16,44 +16,12 @@ code to wire up LLMs, tools, and workflows, you **declare** your agents in YAML or HCL — their model, personality, tools, and how they collaborate — and Docker Agent handles the rest. -
-
-
🏗️
-

Multi-Agent Architecture

-

Build hierarchical teams of agents that specialize in different tasks and delegate work to each other.

- -
-
-
🔧
-

Rich Tool Ecosystem

-

Built-in tools for files, shell, memory, and todos. Extend with any MCP server from Docker's MCP catalog.

- -
-
-
🧠
-

Multi-Model Support

-

OpenAI, Anthropic, Google Gemini, AWS Bedrock, Docker Model Runner, and reusable provider definitions with shared defaults.

- -
-
-
📦
-

Package & Share

-

Push agents to OCI registries and pull them anywhere — just like Docker images.

- -
-
-
🖥️
-

Multiple Interfaces

-

Interactive TUI, headless CLI, HTTP API server, MCP mode, and A2A protocol support.

- -
-
-
🔒
-

Security-First Design

-

Tool confirmation prompts, containerized MCP tools via Docker, client isolation, and resource scoping.

- -
-
+- **Multi-Agent Architecture** — Build hierarchical teams of agents that specialize in different tasks and delegate work to each other. +- **Rich Tool Ecosystem** — Built-in tools for files, shell, memory, and todos. Extend with any MCP server from [Docker's MCP catalog](https://hub.docker.com/u/mcp). +- **Multi-Model Support** — OpenAI, Anthropic, Google Gemini, AWS Bedrock, Docker Model Runner, and reusable provider definitions with shared defaults. +- **Package & Share** — Push agents to OCI registries and pull them anywhere — just like Docker images. +- **Multiple Interfaces** — Interactive TUI, headless CLI, HTTP API server, MCP mode, and A2A protocol support. +- **Security-First Design** — Tool confirmation prompts, containerized MCP tools via Docker, client isolation, and resource scoping. ## Why Docker Agent? @@ -97,23 +65,10 @@ agents: $ docker agent run agent.yaml ``` -
-
Tip
-

Jump straight to the Quick Start if you want to build your first agent right away.

- -
+> [!TIP] +> Jump straight to the [Quick Start](../quickstart/index.md) if you want to build your first agent right away. ## What's next? -
- -
📥
-

Installation

-

Install Docker Agent on macOS, Linux, or Windows.

- - -
⚡
-

Quick Start

-

Build your first agent in under 5 minutes.

- -
+- **[Installation](../installation/index.md)** — Install Docker Agent on macOS, Linux, or Windows. +- **[Quick Start](../quickstart/index.md)** — Build your first agent in under 5 minutes. diff --git a/docs/getting-started/quickstart/index.md b/docs/getting-started/quickstart/index.md index c2a8f005aa..a09f0ab56e 100644 --- a/docs/getting-started/quickstart/index.md +++ b/docs/getting-started/quickstart/index.md @@ -1,7 +1,7 @@ --- title: "Quick Start" description: "Get up and running with Docker Agent in under 5 minutes. Pick whichever path suits you best." -permalink: /getting-started/quickstart/ +keywords: docker agent, ai agents, getting started, quick start --- # Quick Start @@ -82,12 +82,8 @@ This gives your agent: $ docker agent run agent.yaml ``` -
-
Prefer HCL? -
-

You can write the same config as agent.hcl using labeled blocks and heredocs. See HCL Configuration.

- -
+> [!TIP] +> **Prefer HCL?** You can write the same config as `agent.hcl` using labeled blocks and heredocs. See [HCL Configuration](../../configuration/hcl/index.md). ## Try It Out @@ -97,12 +93,8 @@ Once your agent is running, try asking it to: - _"Create a Python script that fetches weather data"_ - _"Explain what the code in main.go does"_ -
-
Tip -
-

Add --yolo to auto-approve all tool calls: `docker agent run agent.yaml --yolo`

- -
+> [!TIP] +> Add `--yolo` to auto-approve all tool calls: `docker agent run agent.yaml --yolo` ## Non-Interactive Mode @@ -136,34 +128,12 @@ agents: ref: docker:duckduckgo ``` -
-
Docker MCP Tools -
-

The ref: docker:duckduckgo syntax runs the DuckDuckGo MCP server in a Docker container. This is the recommended way to use MCP tools — secure, isolated, and easy to configure. Requires Docker Desktop.

- -
+> [!NOTE] +> **Docker MCP Tools**: The `ref: docker:duckduckgo` syntax runs the DuckDuckGo MCP server in a Docker container. This is the recommended way to use MCP tools — secure, isolated, and easy to configure. Requires Docker Desktop. ## What's Next? -
- -
🤖
-

Understand Agents

-

Learn how agents work and what you can configure.

- - -
👥
-

Multi-Agent Systems

-

Build teams of collaborating agents.

- - -
📚
-

Configuration Reference

-

Full reference for all YAML and HCL options.

- - -
🔧
-

Troubleshooting

-

Something not working? Debug tips and common fixes.

- -
+- **[Understand Agents](../../concepts/agents/index.md)** — Learn how agents work and what you can configure. +- **[Multi-Agent Systems](../../concepts/multi-agent/index.md)** — Build teams of collaborating agents. +- **[Configuration Reference](../../configuration/overview/index.md)** — Full reference for all YAML and HCL options. +- **[Troubleshooting](../../community/troubleshooting/index.md)** — Something not working? Debug tips and common fixes. diff --git a/docs/guides/go-sdk/index.md b/docs/guides/go-sdk/index.md index de86dd0130..57e5dbc845 100644 --- a/docs/guides/go-sdk/index.md +++ b/docs/guides/go-sdk/index.md @@ -1,7 +1,7 @@ --- title: "Go SDK" description: "Use docker-agent as a Go library to embed AI agents in your applications." -permalink: /guides/go-sdk/ +keywords: docker agent, ai agents, guides, go sdk --- # Go SDK @@ -12,11 +12,12 @@ _Use docker-agent as a Go library to embed AI agents in your applications._ docker-agent can be used as a Go library, allowing you to build AI agents directly into your Go applications. This gives you full programmatic control over agent creation, tool integration, and execution. -
-
Import Path -
-
import "github.com/docker/docker-agent/pkg/..."
-
+> [!NOTE] +> **Import Path**: +> +> ```go +> import "github.com/docker/docker-agent/pkg/..." +> ``` ## Core Packages @@ -149,10 +150,8 @@ go build -tags 'docker_agent_no_bedrock docker_agent_no_openai' ./... Requesting a model whose provider was compiled out fails at construction time with a clear `"not compiled into this build"` error. The `dmr` (Docker Model Runner) provider and the rule-based router are always compiled in. -
-
Anthropic + Google dependency
-

The Google provider's Vertex Model Garden support also imports the Anthropic SDK, so the Anthropic dependency is only fully removed when both docker_agent_no_anthropic and docker_agent_no_google are set.

-
+> [!WARNING] +> **Anthropic + Google dependency**: The Google provider's Vertex Model Garden support also imports the Anthropic SDK, so the Anthropic dependency is only fully removed when _both_ `docker_agent_no_anthropic` and `docker_agent_no_google` are set. ## RAG Toolset (opt-out) @@ -234,10 +233,8 @@ func main() { } ``` -
-
Call order matters
-

If keyringstore.Register() is called after the default token store has already been lazily initialised, docker-agent panics. The store is initialised when any remote MCP toolset is constructed — which happens inside teamloader.Load(). Always call keyringstore.Register() before calling teamloader.Load() on a config that includes remote MCP toolsets.

-
+> [!WARNING] +> **Call order matters**: If `keyringstore.Register()` is called after the default token store has already been lazily initialised, docker-agent panics. The store is initialised when any remote MCP toolset is constructed — which happens inside `teamloader.Load()`. Always call `keyringstore.Register()` before calling `teamloader.Load()` on a config that includes remote MCP toolsets. If you do not need persistent OAuth tokens (for example, in short-lived batch jobs or tests), omit the call and tokens will be kept in-memory for the process lifetime. @@ -523,12 +520,8 @@ The wrapper receives the already-instrumented transport (OpenTelemetry, SSE deco **Supported providers:** Anthropic, OpenAI, Gemini (GeminiAPI backend), Bedrock. Works in both direct and gateway/proxy mode. -
-
Vertex AI not supported -
-

Vertex AI uses an ADC-managed HTTP client that docker-agent cannot intercept. When a transport wrapper is set, docker-agent falls back to the GeminiAPI backend instead of Vertex AI — a debug message is logged.

- -
+> [!WARNING] +> **Vertex AI not supported**: Vertex AI uses an ADC-managed HTTP client that docker-agent cannot intercept. When a transport wrapper is set, docker-agent falls back to the GeminiAPI backend instead of Vertex AI — a debug message is logged. In **gateway mode** the wrapper is called on every LLM request because gateway clients are rebuilt each call for short-lived auth tokens. In **direct mode** it is called once at client construction. Rate-limit responses (HTTP 429) are classified as non-retryable by the runtime and cause the model chain to skip to the next fallback, so wrappers that track per-request outcomes will observe these as failures rather than retried calls. diff --git a/docs/guides/secrets/index.md b/docs/guides/secrets/index.md index fbb2264476..421457e9a6 100644 --- a/docs/guides/secrets/index.md +++ b/docs/guides/secrets/index.md @@ -1,7 +1,7 @@ --- title: "Managing Secrets" description: "How to securely provide API keys and credentials to docker-agent using environment variables, env files, Docker Compose secrets, macOS Keychain, pass, and 1Password references." -permalink: /guides/secrets/ +keywords: docker agent, ai agents, guides, managing secrets --- # Managing Secrets @@ -81,10 +81,8 @@ The file format supports: - Quoted values: `KEY="value with spaces"` - Blank lines are ignored -
-
Important
-

Add .env to your .gitignore to avoid committing secrets to version control.

-
+> [!WARNING] +> **Important**: Add `.env` to your `.gitignore` to avoid committing secrets to version control. ## Docker Compose Secrets @@ -232,10 +230,8 @@ docker agent run agent.yaml References follow the `op:////` format. Make sure the `op` CLI is installed and you are signed in (`op signin`) so that non-interactive reads succeed. -
-
Behaviour when resolution fails
-

If the value starts with op:// but the op CLI is not installed, or the reference cannot be read (not signed in, wrong path, locked vault), docker-agent logs a warning and uses an empty value — it never forwards the raw op:// reference to a model provider or tool. Resolved references (and deterministic failures) are cached for the lifetime of the run; transient failures such as a cancelled lookup are not cached, so a later attempt can retry.

-
+> [!WARNING] +> **Behaviour when resolution fails**: If the value starts with `op://` but the `op` CLI is not installed, or the reference cannot be read (not signed in, wrong path, locked vault), docker-agent logs a warning and uses an **empty value** — it never forwards the raw `op://` reference to a model provider or tool. Resolved references (and deterministic failures) are cached for the lifetime of the run; transient failures such as a cancelled lookup are not cached, so a later attempt can retry. ## Choosing a Method @@ -271,4 +267,4 @@ agents: - type: shell ``` -The ruleset covers GitHub PATs, AWS / GCP / Azure credentials, Stripe / Slack / GitLab / Hugging Face tokens, JWTs, PEM-encoded private keys, Docker Hub PATs, and many others. Each detected span is replaced with the literal `[REDACTED]`. See the [Redacting Secrets]({{ '/configuration/agents/#redacting-secrets' | relative_url }}) section in the agent configuration reference for the full picture and important caveats about false negatives. +The ruleset covers GitHub PATs, AWS / GCP / Azure credentials, Stripe / Slack / GitLab / Hugging Face tokens, JWTs, PEM-encoded private keys, Docker Hub PATs, and many others. Each detected span is replaced with the literal `[REDACTED]`. See the [Redacting Secrets](../../configuration/agents/index.md#redacting-secrets) section in the agent configuration reference for the full picture and important caveats about false negatives. diff --git a/docs/guides/thinking/index.md b/docs/guides/thinking/index.md index c95a896767..989aa682ec 100644 --- a/docs/guides/thinking/index.md +++ b/docs/guides/thinking/index.md @@ -1,7 +1,7 @@ --- title: "Thinking / Reasoning" description: "Control how much a model reasons before responding. Works across OpenAI, Anthropic, Google Gemini, AWS Bedrock, and Docker Model Runner." -permalink: /guides/thinking/ +keywords: docker agent, ai agents, guides, thinking / reasoning --- # Thinking / Reasoning @@ -14,11 +14,8 @@ Several modern models support an extended reasoning phase that happens before th docker-agent exposes this through a single `thinking_budget` field on any named model. The value format differs slightly by provider, but the semantics are the same: higher effort means more thorough reasoning. -
-
Think tool vs. thinking budget -
-

The think tool is a scratchpad for models that lack native reasoning. If your model supports thinking_budget, you do not need the think tool.

-
+> [!NOTE] +> **Think tool vs. thinking budget**: The [think tool](../../tools/think/index.md) is a scratchpad for models that lack native reasoning. If your model supports `thinking_budget`, you do not need the think tool. ## Quick Reference @@ -60,11 +57,8 @@ models: These effort levels (`minimal`–`xhigh`) are the **only** values accepted for OpenAI. Token counts, `max`, `adaptive`, and `adaptive/` are rejected with a configuration error at request time. The `xhigh` level is only supported by gpt-5.2 and later minor versions (e.g. gpt-5.2, gpt-5.4-mini); o-series and earlier gpt-5 releases top out at `high`. Older models (o1, o3-mini) only accept `low`/`medium`/`high` — sending an unsupported level returns an API error. -
-
Tokens and max_tokens -
-

OpenAI reasoning models always reason internally — even with thinking_budget: none there are hidden reasoning tokens that count against max_tokens. docker-agent automatically raises the output-token floor for its internal low-effort calls (e.g. title generation) so hidden reasoning cannot starve visible text output.

-
+> [!WARNING] +> **Tokens and max_tokens**: OpenAI reasoning models always reason internally — even with `thinking_budget: none` there are hidden reasoning tokens that count against `max_tokens`. docker-agent automatically raises the output-token floor for its internal low-effort calls (e.g. title generation) so hidden reasoning cannot starve visible text output. ## Anthropic @@ -118,11 +112,8 @@ models: `minimal` is treated as `low` (bare form only). `high` is the default when `adaptive` is used without an effort level. -
-
Effort strings require adaptive-capable models -
-

Every string effort value on Anthropic is sent as adaptive thinking (output_config.effort), which only newer Claude models (Opus 4.6+, Sonnet 4.6) accept. For older models like Sonnet 4.5, use an integer token budget instead. Conversely, models that only support adaptive thinking (Opus 4.6, 4.7, 4.8, Sonnet 4.6) automatically have token budgets coerced to adaptive (a warning is logged).

-
+> [!WARNING] +> **Effort strings require adaptive-capable models**: Every string effort value on Anthropic is sent as adaptive thinking (`output_config.effort`), which only newer Claude models (Opus 4.6+, Sonnet 4.6) accept. For older models like Sonnet 4.5, use an integer token budget instead. Conversely, models that _only_ support adaptive thinking (Opus 4.6, 4.7, 4.8, Sonnet 4.6) automatically have token budgets coerced to `adaptive` (a warning is logged). ### Disabling thinking @@ -145,11 +136,8 @@ models: interleaved_thinking: false ``` -
-
Temperature and top_p -
-

When extended thinking is enabled, Anthropic requires temperature=1.0. docker-agent automatically suppresses any temperature or top_p settings you have configured — they are silently ignored while thinking is active.

-
+> [!NOTE] +> **Temperature and top_p**: When extended thinking is enabled, Anthropic requires `temperature=1.0`. docker-agent automatically suppresses any `temperature` or `top_p` settings you have configured — they are silently ignored while thinking is active. ### Thinking display @@ -186,7 +174,7 @@ models: task_budget: 128000 # total token ceiling for the whole task ``` -See the [Anthropic provider page]({{ '/providers/anthropic/#task-budget' | relative_url }}) for details. +See the [Anthropic provider page](../../providers/anthropic/index.md#task-budget) for details. ## Google Gemini @@ -269,11 +257,8 @@ models: region: us-east-1 ``` -
-
Bedrock thinking requirements -
-

Bedrock Claude requires token-based thinking_budget values 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 token thinking budget is set on a Bedrock-hosted Claude model (adaptive thinking interleaves on its own).

-
+> [!WARNING] +> **Bedrock thinking requirements**: Bedrock Claude requires token-based `thinking_budget` values 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 token thinking budget is set on a Bedrock-hosted Claude model (adaptive thinking interleaves on its own). ## Docker Model Runner (local models) @@ -291,13 +276,13 @@ models: - **vLLM**: sent as `thinking_token_budget` on each request. - **MLX / SGLang**: no reasoning-budget knob; the value is silently ignored. -See the [Docker Model Runner provider page]({{ '/providers/dmr/' | relative_url }}) for details. +See the [Docker Model Runner provider page](../../providers/dmr/index.md) for details. ## xAI (Grok) and Mistral xAI and Mistral run through docker-agent's OpenAI-compatible client, but the `reasoning_effort` parameter is only sent for OpenAI reasoning model names (o-series, gpt-5). **Setting `thinking_budget` on Grok or Mistral models currently has no effect** — the value is accepted by config validation but never sent to the API. -Grok and Mistral reasoning models (e.g. `grok-3-mini`, `magistral`) manage reasoning on their own; for non-reasoning models, consider the [think tool]({{ '/tools/think/' | relative_url }}) instead. +Grok and Mistral reasoning models (e.g. `grok-3-mini`, `magistral`) manage reasoning on their own; for non-reasoning models, consider the [think tool](../../tools/think/index.md) instead. ## Disabling Thinking diff --git a/docs/guides/tips/index.md b/docs/guides/tips/index.md index 0bc50d3795..084402e6d2 100644 --- a/docs/guides/tips/index.md +++ b/docs/guides/tips/index.md @@ -1,7 +1,7 @@ --- title: "Tips & Best Practices" description: "Expert guidance for building effective, efficient, and secure agents." -permalink: /guides/tips/ +keywords: docker agent, ai agents, guides, tips & best practices --- # Tips & Best Practices @@ -178,7 +178,7 @@ toolsets: - type: think # Useful for models without native reasoning ``` -The agent uses it as a scratchpad for planning and decision-making. If your model already supports a [thinking budget]({{ '/configuration/models/#thinking-budget' | relative_url }}) (e.g., Claude with extended thinking, OpenAI o-series, Gemini with thinking enabled), you don't need this tool — the model can reason internally. +The agent uses it as a scratchpad for planning and decision-making. If your model already supports a [thinking budget](../../configuration/models/index.md#thinking-budget) (e.g., Claude with extended thinking, OpenAI o-series, Gemini with thinking enabled), you don't need this tool — the model can reason internally. ## Security Tips @@ -205,7 +205,7 @@ $ docker agent run agent.yaml --yolo ### Combine Permissions with Sandbox -For defense in depth, use both permissions and [sandbox mode]({{ '/configuration/sandbox/' | relative_url }}): +For defense in depth, use both permissions and [sandbox mode](../../configuration/sandbox/index.md): ```yaml agents: @@ -234,7 +234,7 @@ docker-agent run --sandbox agent.yaml ### Set Global Permission Guardrails -Use [global permissions]({{ '/configuration/permissions/' | relative_url }}#global-permissions) in your user config to enforce safety rules across every agent: +Use [global permissions](../../configuration/permissions/index.md#global-permissions) in your user config to enforce safety rules across every agent: ```yaml # ~/.config/cagent/config.yaml @@ -276,22 +276,21 @@ agents: Understand the difference between `sub_agents` and `handoffs`: -
-
-

sub_agents (transfer_task)

-

Delegates task to a child in a sub-session, waits for result, then continues. Hierarchical — the parent remains in control.

- 
sub_agents: [researcher, writer]
-
-
-

handoffs (peer-to-peer)

-

Hands off the entire conversation to another agent in the same session. The active agent switches and sees the full history. Agents can form cycles.

- 
handoffs:
-  - specialist
-  - summarizer
-
-
- -See Multi-Agent Systems for a detailed comparison. +- **`sub_agents` (transfer_task)** — delegates a task to a child in a sub-session, waits for the result, then continues. Hierarchical — the parent remains in control. + + ```yaml + sub_agents: [researcher, writer] + ``` + +- **`handoffs` (peer-to-peer)** — hands off the entire conversation to another agent in the same session. The active agent switches and sees the full history. Agents can form cycles. + + ```yaml + handoffs: + - specialist + - summarizer + ``` + +See [Multi-Agent Systems](../../concepts/multi-agent/index.md) for a detailed comparison. ### Give Sub-Agents Clear Descriptions diff --git a/docs/index.md b/docs/index.md index e1db6d9dfd..462abb4474 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,20 +2,20 @@ layout: default title: "Docker Agent" description: "Run AI agents like containers. Define them in YAML, share them through any OCI registry, and run them anywhere." -permalink: / +keywords: docker agent, ai agents ---

Docker Agent

Docker Agent is to AI agents what docker run is to containers.
Define an agent in a YAML file, run it with one command, share it through any OCI registry — the same workflow you already use for images.

- Quick Start → + Quick Start → View on GitHub
- Docker Agent TUI demo showing an interactive agent session + Docker Agent TUI demo showing an interactive agent session
@@ -104,6 +104,7 @@ while True: # …parse tool_use blocks, dispatch, append, loop… if resp.stop_reason == "end_turn": break ``` +
With Docker Agent
@@ -123,6 +124,7 @@ agents: ```bash $ docker agent run agent.yaml ``` +
@@ -213,7 +215,7 @@ What people build with Docker Agent today:

Ops & SRE

Triage incidents, search logs, run kubectl, build Dockerfiles. Pipe alerts in via --exec for headless runs.

- CLI reference → + CLI reference →
@@ -221,7 +223,7 @@ What people build with Docker Agent today:

Data & research

Persistent memory, web fetch, RAG over local docs, structured output for downstream pipelines.

- RAG guide → + RAG guide →
@@ -229,7 +231,7 @@ What people build with Docker Agent today:

Custom workflows

Multi-agent teams, hooks, model routing, A2A and MCP servers — wire agents into your existing stack.

- Multi-agent → + Multi-agent →
@@ -238,7 +240,7 @@ What people build with Docker Agent today: Docker Agent follows a simple loop:
- agent.yaml is run by 'docker agent run', which loops through Model, Tools and Sub-agents, then streams results to the TUI or API. + agent.yaml is run by 'docker agent run', which loops through Model, Tools and Sub-agents, then streams results to the TUI or API.
Your YAML config is the input; the runtime drives a Model ↔ Tools ↔ Sub-agents loop until the task is done; results stream back to the TUI or any API client.
@@ -333,11 +335,8 @@ $ cat error.log | docker agent run --exec agent.yaml "What's wrong in this log?" $ docker agent serve api agent.yaml --listen :8080 ``` -
-
Prefer HCL? -
-

You can also write agent configs in HCL using labeled blocks and heredocs. See HCL Configuration.

-
+> [!TIP] +> **Prefer HCL?** You can also write agent configs in HCL using labeled blocks and heredocs. See [HCL Configuration](configuration/hcl/index.md). ## Part of the Docker ecosystem @@ -365,42 +364,42 @@ Docker Agent reuses the tooling and conventions you already know: ## Explore the Docs
- +

Introduction

The full story: what Docker Agent is, why it exists, and how it works.

 - +

Quick Start

Get your first agent running in under 5 minutes.

 - +

Core Concepts

Agents, models, tools, and multi-agent orchestration explained.

 - +

Configuration

Full reference for every YAML and HCL option.

 - +

Model Providers

OpenAI, Anthropic, Gemini, Bedrock, Docker Model Runner, and more.

 - +
diff --git a/docs/js/app.js b/docs/js/app.js index 890f2d2532..16c616cf41 100644 --- a/docs/js/app.js +++ b/docs/js/app.js @@ -304,6 +304,38 @@ function restoreSidebarScroll() { }); } +// ---------- GitHub-style alerts ---------- +// Kramdown renders `> [!NOTE]` as a plain blockquote; upgrade it to the +// styled callout markup used across the site (Hugo on docs.docker.com +// styles the same syntax natively). +function upgradeAlerts() { + const kinds = { NOTE: 'info', TIP: 'tip', WARNING: 'warning', IMPORTANT: 'info', CAUTION: 'warning' }; + ($content || document).querySelectorAll('blockquote').forEach(bq => { + // Only a direct-child

counts — don't upgrade a prose blockquote + // that merely contains a nested alert. + const first = Array.from(bq.children).find(el => el.tagName === 'P'); + const m = first?.textContent.match(/^\[!(\w+)\]\s*/); + const kind = m && kinds[m[1]]; + if (!kind) return; + // Drop the [!KIND] marker from the leading text node (and a trailing + //
, if any) without reserializing the paragraph's HTML. + const lead = first.firstChild; + if (!lead || lead.nodeType !== Node.TEXT_NODE) return; + lead.textContent = lead.textContent.replace(/^\[!\w+\]\s*/, ''); + if (!lead.textContent) lead.remove(); + if (first.firstChild?.nodeName === 'BR') first.firstChild.remove(); + if (!first.textContent.trim()) first.remove(); + const div = document.createElement('div'); + div.className = `callout callout-${kind}`; + const title = document.createElement('div'); + title.className = 'callout-title'; + title.textContent = m[1].charAt(0) + m[1].slice(1).toLowerCase(); + div.appendChild(title); + while (bq.firstChild) div.appendChild(bq.firstChild); + bq.replaceWith(div); + }); +} + // ---------- Bind buttons (no inline handlers) ---------- function bindButtons() { document.getElementById('theme-toggle')?.addEventListener('click', toggleTheme); @@ -315,6 +347,7 @@ function bindButtons() { // ---------- Init ---------- initTheme(); restoreSidebarScroll(); +upgradeAlerts(); buildSearchIndex(); buildTOC(); addCopyButtons(); diff --git a/docs/providers/anthropic/index.md b/docs/providers/anthropic/index.md index 2f159b8e36..26b2d11399 100644 --- a/docs/providers/anthropic/index.md +++ b/docs/providers/anthropic/index.md @@ -1,7 +1,7 @@ --- title: "Anthropic" description: "Use Claude Sonnet 4, Claude Sonnet 4.5, and other Anthropic models with docker-agent." -permalink: /providers/anthropic/ +keywords: docker agent, ai agents, model providers, anthropic --- # Anthropic @@ -72,7 +72,7 @@ identity federation: failed to refresh identity token from source (federation_rule=fdrl_…): ...` message in the TUI. A complete walkthrough of all four sources lives in -[`examples/anthropic_wif.yaml`]({{ site.examples_url }}/anthropic_wif.yaml). +[`examples/anthropic_wif.yaml`](https://github.com/docker/docker-agent/blob/main/examples/anthropic_wif.yaml). ## Configuration @@ -132,7 +132,7 @@ models: thinking_budget: high # low | medium | high | xhigh | max (same as adaptive/) ``` -On models that reject token-based thinking (Opus 4.6, 4.7, 4.8, Sonnet 4.6), an integer budget is automatically coerced to `adaptive` with a logged warning. See the [Thinking / Reasoning guide]({{ '/guides/thinking/' | relative_url }}) for the full cross-provider reference. +On models that reject token-based thinking (Opus 4.6, 4.7, 4.8, Sonnet 4.6), an integer budget is automatically coerced to `adaptive` with a logged warning. See the [Thinking / Reasoning guide](../../guides/thinking/index.md) for the full cross-provider reference. ## Interleaved Thinking @@ -184,7 +184,7 @@ Object form (forward-compatible with future budget types): total: 128000 ``` -See the full schema on the [Model Configuration]({{ '/configuration/models/#task-budget' | relative_url }}) page. +See the full schema on the [Model Configuration](../../configuration/models/index.md#task-budget) page. ## Server-Side Fallbacks @@ -236,9 +236,5 @@ Valid values: Note: `thinking_display` applies to both `thinking_budget` with token counts and adaptive/effort-based budgets. Full thinking tokens are billed regardless of the `thinking_display` value. -

-
Note -
-

Anthropic thinking budget values below 1024 or greater than or equal to max_tokens are ignored (a warning is logged).

- -
+> [!NOTE] +> Anthropic thinking budget values below 1024 or greater than or equal to `max_tokens` are ignored (a warning is logged). diff --git a/docs/providers/baseten/index.md b/docs/providers/baseten/index.md index 3a4a63cdb1..23ee8ecdaf 100644 --- a/docs/providers/baseten/index.md +++ b/docs/providers/baseten/index.md @@ -1,7 +1,7 @@ --- title: "Baseten" description: "Use Baseten AI models with docker-agent." -permalink: /providers/baseten/ +keywords: docker agent, ai agents, model providers, baseten --- # Baseten diff --git a/docs/providers/bedrock/index.md b/docs/providers/bedrock/index.md index 59df9865c0..dc87629b39 100644 --- a/docs/providers/bedrock/index.md +++ b/docs/providers/bedrock/index.md @@ -1,7 +1,7 @@ --- title: "AWS Bedrock" description: "Access Claude, Nova, Llama, and more through AWS infrastructure with enterprise-grade security and compliance." -permalink: /providers/bedrock/ +keywords: docker agent, ai agents, model providers, aws bedrock --- # AWS Bedrock @@ -94,12 +94,8 @@ Use inference profile prefixes for optimal routing: | `eu.` | EU regions only (GDPR compliance) | | `apac.` | Asia Pacific regions only | -
-
Inference profiles -
-

Use global. prefix on model IDs for automatic cross-region routing. Use eu. prefix for GDPR compliance.

- -
+> [!TIP] +> **Inference profiles**: Use `global.` prefix on model IDs for automatic cross-region routing. Use `eu.` prefix for GDPR compliance. ## Thinking Budget (Claude on Bedrock) @@ -142,11 +138,8 @@ models: docker-agent recognizes these models (including Bedrock-style IDs) and transparently coerces a configured token budget or effort level to adaptive thinking, logging a warning — so `thinking_budget: 32768` on Opus 4.8 won't fail, but `adaptive` or `adaptive/` is the recommended configuration. On older models that still use token-based thinking (e.g. Sonnet 4.5), `adaptive` is forwarded as-is and rejected by Bedrock — use a token count or effort level there instead. -
-
Temperature and top_p -
-

Bedrock Claude suppresses temperature and top_p while extended thinking is active — Anthropic requires temperature=1.0 internally.

-
+> [!NOTE] +> **Temperature and top_p**: Bedrock Claude suppresses `temperature` and `top_p` while extended thinking is active — Anthropic requires `temperature=1.0` internally. ## Interleaved Thinking (Claude on Bedrock) @@ -165,7 +158,7 @@ models: 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. +See the [Thinking / Reasoning guide](../../guides/thinking/index.md) for a full cross-provider overview. ## Prompt Caching diff --git a/docs/providers/cerebras/index.md b/docs/providers/cerebras/index.md index 27e941dffe..af11a4525f 100644 --- a/docs/providers/cerebras/index.md +++ b/docs/providers/cerebras/index.md @@ -1,7 +1,7 @@ --- title: "Cerebras" description: "Use Cerebras models with docker-agent." -permalink: /providers/cerebras/ +keywords: docker agent, ai agents, model providers, cerebras --- # Cerebras diff --git a/docs/providers/cloudflare-ai-gateway/index.md b/docs/providers/cloudflare-ai-gateway/index.md index fcb1ad06e6..b5ab92730d 100644 --- a/docs/providers/cloudflare-ai-gateway/index.md +++ b/docs/providers/cloudflare-ai-gateway/index.md @@ -1,7 +1,7 @@ --- title: "Cloudflare AI Gateway" description: "Use Cloudflare AI Gateway models with docker-agent." -permalink: /providers/cloudflare-ai-gateway/ +keywords: docker agent, ai agents, model providers, cloudflare ai gateway --- # Cloudflare AI Gateway @@ -111,5 +111,5 @@ instead expects the token in Cloudflare's `cf-aig-authorization` header. The alias does not send that header, and custom `provider_opts.http_headers` values are not environment-expanded, so an authenticated gateway is **not supported out of the box** today. For that setup, use an unauthenticated gateway, or configure -a [custom provider]({{ '/providers/custom/' | relative_url }}) against the +a [custom provider](../custom/index.md) against the Cloudflare AI Gateway REST API. diff --git a/docs/providers/cloudflare-workers-ai/index.md b/docs/providers/cloudflare-workers-ai/index.md index 7d67cd746a..44c7193d17 100644 --- a/docs/providers/cloudflare-workers-ai/index.md +++ b/docs/providers/cloudflare-workers-ai/index.md @@ -1,7 +1,7 @@ --- title: "Cloudflare Workers AI" description: "Use Cloudflare Workers AI models with docker-agent." -permalink: /providers/cloudflare-workers-ai/ +keywords: docker agent, ai agents, model providers, cloudflare workers ai --- # Cloudflare Workers AI diff --git a/docs/providers/custom/index.md b/docs/providers/custom/index.md index 6b0fe8cd56..f0fc3cd270 100644 --- a/docs/providers/custom/index.md +++ b/docs/providers/custom/index.md @@ -1,7 +1,7 @@ --- title: "Provider Definitions" description: "Define reusable provider configurations with shared defaults for any provider type — OpenAI, Anthropic, Google, Bedrock, and more." -permalink: /providers/custom/ +keywords: docker agent, ai agents, model providers, provider definitions --- # Provider Definitions @@ -17,12 +17,8 @@ The `providers` section in your agent YAML lets you define named provider config - **Centralizing credentials** — Define token_key once for all models using a provider - **Any provider type** — Works with OpenAI, Anthropic, Google, Bedrock, and any OpenAI-compatible API -
-
Works with any provider -
-

The providers section supports all provider types: openai, anthropic, google, amazon-bedrock, dmr, and any built-in alias. When the provider field is not set, it defaults to openai for backward compatibility.

- -
+> [!NOTE] +> **Works with any provider**: The `providers` section supports all provider types: `openai`, `anthropic`, `google`, `amazon-bedrock`, `dmr`, and any built-in alias. When the `provider` field is not set, it defaults to `openai` for backward compatibility. ## Configuration @@ -100,7 +96,7 @@ agents: | `api_type` | string | API schema: `openai_chatcompletions` or `openai_responses`. Only for OpenAI-compatible providers. When omitted, the API type is selected automatically based on the model name: newer models (gpt-4.1, o-series, gpt-5, Codex) default to `openai_responses`; all others default to `openai_chatcompletions`. | `auto (model-dependent)` | | `base_url` | string | Base URL for the API endpoint. Required for OpenAI-compatible providers, optional for native providers. | — | | `token_key` | string | Environment variable name containing the API token. | — | -| `unload_api` | string | Optional path (or absolute URL) to the provider's model-unload endpoint. Used by the [`unload`]({{ '/configuration/hooks/#available-built-ins' | relative_url }}) built-in hook to release model resources between agent switches. Relative paths resolve against `base_url`'s scheme + host; absolute URLs are used verbatim. Today only Docker Model Runner ships a provider that calls this endpoint; cloud providers don't implement the underlying interface and the hook silently skips them. | — | +| `unload_api` | string | Optional path (or absolute URL) to the provider's model-unload endpoint. Used by the [`unload`](../../configuration/hooks/index.md#available-built-ins) built-in hook to release model resources between agent switches. Relative paths resolve against `base_url`'s scheme + host; absolute URLs are used verbatim. Today only Docker Model Runner ships a provider that calls this endpoint; cloud providers don't implement the underlying interface and the hook silently skips them. | — | | `temperature` | float | Default sampling temperature (0.0–2.0). | — | | `max_tokens` | int | Default maximum response tokens. | — | | `top_p` | float | Default nucleus sampling threshold (0.0–1.0). | — | @@ -174,11 +170,8 @@ agents: model: local_llm/llama-3.1-8b ``` -
-
Reasoning tokens from OpenAI-compatible providers -
-

Models that stream reasoning under delta.reasoning (e.g. Qwen3 served via OVHcloud AI Endpoints, OpenRouter, or a self-hosted vLLM / SGLang deployment) are fully supported. Docker Agent reads both the delta.reasoning_content and delta.reasoning fields from the stream, so thinking blocks are captured and shown in the TUI regardless of which field the server uses.

-
+> [!NOTE] +> **Reasoning tokens from OpenAI-compatible providers**: Models that stream reasoning under `delta.reasoning` (e.g. Qwen3 served via OVHcloud AI Endpoints, OpenRouter, or a self-hosted vLLM / SGLang deployment) are fully supported. Docker Agent reads both the `delta.reasoning_content` and `delta.reasoning` fields from the stream, so thinking blocks are captured and shown in the TUI regardless of which field the server uses. ### API Router (Requesty, LiteLLM) diff --git a/docs/providers/deepseek/index.md b/docs/providers/deepseek/index.md index 8aeb2251b5..ef7738e650 100644 --- a/docs/providers/deepseek/index.md +++ b/docs/providers/deepseek/index.md @@ -1,7 +1,7 @@ --- title: "DeepSeek" description: "Use DeepSeek models with docker-agent." -permalink: /providers/deepseek/ +keywords: docker agent, ai agents, model providers, deepseek --- # DeepSeek diff --git a/docs/providers/dmr/index.md b/docs/providers/dmr/index.md index 48afd99f46..95bbbf2055 100644 --- a/docs/providers/dmr/index.md +++ b/docs/providers/dmr/index.md @@ -1,7 +1,7 @@ --- title: "Docker Model Runner" description: "Run AI models locally with Docker — no API keys, no costs, full data privacy." -permalink: /providers/dmr/ +keywords: docker agent, ai agents, model providers, docker model runner --- # Docker Model Runner @@ -14,12 +14,8 @@ Docker Model Runner (DMR) lets you run open-source AI models directly on your ma docker-agent automatically discovers models you have already pulled from DMR. When no model is explicitly configured, auto-selection prefers a locally-installed model (choosing the model specified via the `model:` key in the agent YAML if it is already pulled locally, or otherwise the first available non-embedding model) rather than always defaulting to `ai/qwen3:latest` and triggering a pull prompt. -
-
No API key needed -
-

DMR runs models locally — your data never leaves your machine. Great for development, sensitive data, or offline use.

- -
+> [!TIP] +> **No API key needed**: DMR runs models locally — your data never leaves your machine. Great for development, sensitive data, or offline use. ## Prerequisites @@ -154,7 +150,7 @@ Accepted values: any Go duration string (`"30s"`, `"5m"`, `"1h"`, `"2h30m"`), `" ## Unloading models on agent switch -In multi-agent setups where two DMR models can't fit in GPU memory simultaneously, wire the [`unload`]({{ '/configuration/hooks/#available-built-ins' | relative_url }}) built-in hook into each agent's `on_agent_switch` chain. Every time the active agent transfers control, the runtime POSTs to the engine's `_unload` endpoint to free the previous model's resources before the next one is loaded: +In multi-agent setups where two DMR models can't fit in GPU memory simultaneously, wire the [`unload`](../../configuration/hooks/index.md#available-built-ins) built-in hook into each agent's `on_agent_switch` chain. Every time the active agent transfers control, the runtime POSTs to the engine's `_unload` endpoint to free the previous model's resources before the next one is loaded: ```yaml agents: @@ -189,13 +185,10 @@ models: model: ai/qwen3 ``` -Unload errors are logged and swallowed — a stuck or unreachable engine never blocks an agent transfer (each call is bounded to 10 s). Pair this with [`keep_alive`](#keeping-models-resident-in-memory-keep_alive) only when you want the model to *also* survive idle periods within a single agent's run; the hook controls **between-agent** unloads independently. - -
-
Single-tenant assumption
+Unload errors are logged and swallowed — a stuck or unreachable engine never blocks an agent transfer (each call is bounded to 10 s). Pair this with [`keep_alive`](#keeping-models-resident-in-memory-keep_alive) only when you want the model to _also_ survive idle periods within a single agent's run; the hook controls **between-agent** unloads independently. -The `_unload` endpoint is engine-level: it evicts the model from DMR's memory regardless of who is using it. If two concurrent sessions on the same runtime (e.g. an API server serving multiple users) hit the same agent, switching away in session A will yank the model out from under session B's in-flight request, which then has to wait for a reload. Wire `unload` only when the agents using these models are not run concurrently — typically a single TUI/CLI session. -
+> [!WARNING] +> **Single-tenant assumption**: The `_unload` endpoint is engine-level: it evicts the model from DMR's memory regardless of who is using it. If two concurrent sessions on the same runtime (e.g. an API server serving multiple users) hit the same agent, switching away in session A will yank the model out from under session B's in-flight request, which then has to wait for a reload. Wire `unload` only when the agents using these models are not run concurrently — typically a single TUI/CLI session. See [`examples/unload_on_switch.yaml`](https://github.com/docker/docker-agent/blob/main/examples/unload_on_switch.yaml) for the full example. diff --git a/docs/providers/fireworks/index.md b/docs/providers/fireworks/index.md index 111a126289..e0e204389b 100644 --- a/docs/providers/fireworks/index.md +++ b/docs/providers/fireworks/index.md @@ -1,7 +1,7 @@ --- title: "Fireworks AI" description: "Use Fireworks AI models with docker-agent." -permalink: /providers/fireworks/ +keywords: docker agent, ai agents, model providers, fireworks ai --- # Fireworks AI diff --git a/docs/providers/github-copilot/index.md b/docs/providers/github-copilot/index.md index 1908381a66..fa4b75df03 100644 --- a/docs/providers/github-copilot/index.md +++ b/docs/providers/github-copilot/index.md @@ -1,7 +1,7 @@ --- title: "GitHub Copilot" description: "Use GitHub Copilot's hosted models (GPT-4o, Claude, Gemini, and more) with docker-agent through your GitHub subscription." -permalink: /providers/github-copilot/ +keywords: docker agent, ai agents, model providers, github copilot --- # GitHub Copilot diff --git a/docs/providers/google/index.md b/docs/providers/google/index.md index 59741017fb..000de1822e 100644 --- a/docs/providers/google/index.md +++ b/docs/providers/google/index.md @@ -1,7 +1,7 @@ --- title: "Google Gemini" description: "Use Gemini 2.5 Flash, Gemini 3 Pro, and other Google models with docker-agent." -permalink: /providers/google/ +keywords: docker agent, ai agents, model providers, google gemini --- # Google Gemini @@ -64,12 +64,8 @@ models: Gemini supports two approaches depending on the model version: -
-
Different thinking formats -
-

Gemini 2.5 uses **token-based** budgets (integers). Gemini 3 uses **level-based** budgets (strings like low, high). Make sure you use the right format for your model version.

- -
+> [!WARNING] +> **Different thinking formats**: Gemini 2.5 uses **token-based** budgets (integers). Gemini 3 uses **level-based** budgets (strings like `low`, `high`). Make sure you use the right format for your model version. ### Gemini 2.5 (Token-based) @@ -170,9 +166,5 @@ models: | `location` | GCP region (e.g. `us-east5`, `us-central1`). Falls back to `GOOGLE_CLOUD_LOCATION` | | `publisher` | Model publisher (e.g. `anthropic`, `meta`, `mistral`). Must not be `google` | -
-
Gemini models on Vertex AI -
-

Setting publisher: google (or omitting publisher) uses the native Gemini SDK path. The Model Garden endpoint is only used for non-Google publishers.

- -
+> [!NOTE] +> **Gemini models on Vertex AI**: Setting `publisher: google` (or omitting `publisher`) uses the native Gemini SDK path. The Model Garden endpoint is only used for non-Google publishers. diff --git a/docs/providers/groq/index.md b/docs/providers/groq/index.md index 49ce6e83ff..951562786f 100644 --- a/docs/providers/groq/index.md +++ b/docs/providers/groq/index.md @@ -1,7 +1,7 @@ --- title: "Groq" description: "Use Groq fast-inference models with docker-agent." -permalink: /providers/groq/ +keywords: docker agent, ai agents, model providers, groq --- # Groq diff --git a/docs/providers/huggingface/index.md b/docs/providers/huggingface/index.md index 49f3302a77..f2e1910e5f 100644 --- a/docs/providers/huggingface/index.md +++ b/docs/providers/huggingface/index.md @@ -1,7 +1,7 @@ --- title: "Hugging Face" description: "Use Hugging Face Inference Providers with docker-agent." -permalink: /providers/huggingface/ +keywords: docker agent, ai agents, model providers, hugging face --- # Hugging Face diff --git a/docs/providers/local/index.md b/docs/providers/local/index.md index 4bdebf9008..27eac40e4e 100644 --- a/docs/providers/local/index.md +++ b/docs/providers/local/index.md @@ -1,7 +1,7 @@ --- title: "Local Models (Ollama, vLLM, LocalAI)" description: "Run docker-agent with locally hosted models for privacy, offline use, or cost savings." -permalink: /providers/local/ +keywords: docker agent, ai agents, model providers, local models (ollama, vllm, localai) --- # Local Models (Ollama, vLLM, LocalAI) @@ -16,12 +16,8 @@ docker-agent can connect to any OpenAI-compatible local model server. This guide - **vLLM** — High-performance inference server - **LocalAI** — OpenAI-compatible API for various backends -
-
Docker Model Runner -
-

For the easiest local model experience, consider Docker Model Runner which is built into Docker Desktop and requires no additional setup.

- -
+> [!TIP] +> **Docker Model Runner**: For the easiest local model experience, consider [Docker Model Runner](../dmr/index.md) which is built into Docker Desktop and requires no additional setup. ## Ollama @@ -169,16 +165,13 @@ agents: ## Performance Tips -
-
Local Model Considerations -
- -- **Memory:** Larger models need more RAM/VRAM. A 7B model typically needs 8-16GB RAM. -- **GPU:** GPU acceleration dramatically improves speed. Check your server's GPU support. -- **Context length:** Local models often have smaller context windows than cloud models. -- **Tool calling:** Not all local models support function/tool calling. Test your model's capabilities. - -
+> [!NOTE] +> **Local Model Considerations**: +> +> - **Memory:** Larger models need more RAM/VRAM. A 7B model typically needs 8-16GB RAM. +> - **GPU:** GPU acceleration dramatically improves speed. Check your server's GPU support. +> - **Context length:** Local models often have smaller context windows than cloud models. +> - **Tool calling:** Not all local models support function/tool calling. Test your model's capabilities. ## Example: Offline Development Agent diff --git a/docs/providers/minimax/index.md b/docs/providers/minimax/index.md index 720ec870ec..2a8128378b 100644 --- a/docs/providers/minimax/index.md +++ b/docs/providers/minimax/index.md @@ -1,7 +1,7 @@ --- title: "MiniMax" description: "Use MiniMax AI models with docker-agent." -permalink: /providers/minimax/ +keywords: docker agent, ai agents, model providers, minimax --- # MiniMax diff --git a/docs/providers/mistral/index.md b/docs/providers/mistral/index.md index fa4f74f1b5..a305fafe2f 100644 --- a/docs/providers/mistral/index.md +++ b/docs/providers/mistral/index.md @@ -1,7 +1,7 @@ --- title: "Mistral" description: "Use Mistral AI models with docker-agent." -permalink: /providers/mistral/ +keywords: docker agent, ai agents, model providers, mistral --- # Mistral @@ -76,7 +76,7 @@ When you run `docker agent run` without specifying a config, docker-agent automa docker-agent's `thinking_budget` field is **not applied** to Mistral models: the underlying OpenAI-compatible client only sends `reasoning_effort` for OpenAI reasoning model names (o-series, gpt-5). Setting `thinking_budget` on a Mistral model passes config validation but has no effect on the request. -Mistral reasoning models (e.g. `magistral`) reason on their own without configuration. For non-reasoning models, use the [think tool]({{ '/tools/think/' | relative_url }}) instead. +Mistral reasoning models (e.g. `magistral`) reason on their own without configuration. For non-reasoning models, use the [think tool](../../tools/think/index.md) instead. ## How It Works diff --git a/docs/providers/moonshot/index.md b/docs/providers/moonshot/index.md index ea121cce01..db1fb5c272 100644 --- a/docs/providers/moonshot/index.md +++ b/docs/providers/moonshot/index.md @@ -1,7 +1,7 @@ --- title: "Moonshot AI" description: "Use Moonshot AI (Kimi) models with docker-agent." -permalink: /providers/moonshot/ +keywords: docker agent, ai agents, model providers, moonshot ai --- # Moonshot AI diff --git a/docs/providers/nebius/index.md b/docs/providers/nebius/index.md index 83ea69398e..b7bb48290a 100644 --- a/docs/providers/nebius/index.md +++ b/docs/providers/nebius/index.md @@ -1,7 +1,7 @@ --- title: "Nebius" description: "Use Nebius AI models with docker-agent." -permalink: /providers/nebius/ +keywords: docker agent, ai agents, model providers, nebius --- # Nebius diff --git a/docs/providers/openai/index.md b/docs/providers/openai/index.md index 122f99fcb9..3922f353d3 100644 --- a/docs/providers/openai/index.md +++ b/docs/providers/openai/index.md @@ -1,7 +1,7 @@ --- title: "OpenAI" description: "Use GPT-4o, GPT-5, GPT-5-mini, and other OpenAI models with docker-agent." -permalink: /providers/openai/ +keywords: docker agent, ai agents, model providers, openai --- # OpenAI @@ -72,20 +72,13 @@ models: These are the **only** values OpenAI accepts — token counts, `max`, `adaptive`, and `adaptive/` are rejected with a configuration error at request time. Older models (o1, o3-mini) only accept `low`/`medium`/`high`. -
-
Hidden reasoning tokens -
-

OpenAI reasoning models always produce hidden reasoning tokens that count against max_tokens — even with thinking_budget: none. docker-agent automatically raises the output-token floor for its internal low-effort calls so reasoning cannot starve visible text output.

-
+> [!WARNING] +> **Hidden reasoning tokens**: OpenAI reasoning models always produce hidden reasoning tokens that count against `max_tokens` — even with `thinking_budget: none`. docker-agent automatically raises the output-token floor for its internal low-effort calls so reasoning cannot starve visible text output. -See the [Thinking / Reasoning guide]({{ '/guides/thinking/' | relative_url }}) for a cross-provider overview. +See the [Thinking / Reasoning guide](../../guides/thinking/index.md) for a cross-provider overview. -
-
Custom endpoints -
-

Use base_url for proxies and OpenAI-compatible services. See Custom Providers for full setup.

- -
+> [!TIP] +> **Custom endpoints**: Use `base_url` for proxies and OpenAI-compatible services. See [Custom Providers](../custom/index.md) for full setup. ## Custom Endpoint diff --git a/docs/providers/opencode-go/index.md b/docs/providers/opencode-go/index.md index 9e106fb871..6a6fc03834 100644 --- a/docs/providers/opencode-go/index.md +++ b/docs/providers/opencode-go/index.md @@ -1,7 +1,7 @@ --- title: "OpenCode Go" description: "Use OpenCode Go models with docker-agent." -permalink: /providers/opencode-go/ +keywords: docker agent, ai agents, model providers, opencode go --- # OpenCode Go @@ -87,7 +87,7 @@ These models use the `/v1/chat/completions` endpoint and work directly with the ### Anthropic-Compatible -These models use the `/v1/messages` endpoint and require a [custom provider definition]({{ '/providers/custom/' | relative_url }}): +These models use the `/v1/messages` endpoint and require a [custom provider definition](../custom/index.md): | Model | Description | | ----------------- | ------------------------ | diff --git a/docs/providers/opencode-zen/index.md b/docs/providers/opencode-zen/index.md index fc6c9aa683..fe78e22118 100644 --- a/docs/providers/opencode-zen/index.md +++ b/docs/providers/opencode-zen/index.md @@ -1,7 +1,7 @@ --- title: "OpenCode Zen" description: "Use OpenCode Zen models with docker-agent." -permalink: /providers/opencode-zen/ +keywords: docker agent, ai agents, model providers, opencode zen --- # OpenCode Zen @@ -121,7 +121,7 @@ These models use the `/v1/responses` endpoint and are auto-detected by docker-ag ### Anthropic-Compatible (Messages API) -These models use the `/v1/messages` endpoint and require a [custom provider definition]({{ '/providers/custom/' | relative_url }}): +These models use the `/v1/messages` endpoint and require a [custom provider definition](../custom/index.md): | Model | Description | | ----------------------- | ----------------------------- | @@ -163,7 +163,7 @@ agents: ### Google-Compatible -These models require a [custom provider definition]({{ '/providers/custom/' | relative_url }}) with a Google-compatible client: +These models require a [custom provider definition](../custom/index.md) with a Google-compatible client: | Model | Description | | ------------------- | ------------------------ | diff --git a/docs/providers/openrouter/index.md b/docs/providers/openrouter/index.md index 9067865b51..2bd5cb9056 100644 --- a/docs/providers/openrouter/index.md +++ b/docs/providers/openrouter/index.md @@ -1,7 +1,7 @@ --- title: "OpenRouter" description: "Use OpenRouter models with docker-agent." -permalink: /providers/openrouter/ +keywords: docker agent, ai agents, model providers, openrouter --- # OpenRouter diff --git a/docs/providers/overview/index.md b/docs/providers/overview/index.md index 49af7b68d4..89bd15034f 100644 --- a/docs/providers/overview/index.md +++ b/docs/providers/overview/index.md @@ -1,7 +1,7 @@ --- title: "Model Providers" description: "docker-agent supports multiple AI model providers. Choose the right one for your use case, or use multiple providers in the same configuration." -permalink: /providers/overview/ +keywords: docker agent, ai agents, model providers --- # Model Providers @@ -10,38 +10,12 @@ _docker-agent supports multiple AI model providers. Choose the right one for you ## Supported Providers -
- -
🟢
-

OpenAI

-

GPT-5, GPT-5-mini, GPT-4o. The most widely used AI models.

- - -
🟠
-

Anthropic

-

Claude Sonnet 4.5, Claude Opus 4.7. Excellent for coding and analysis.

- - -
🔵
-

Google Gemini

-

Gemini 2.5 Flash, Gemini 3 Pro. Fast and cost-effective.

- - -
🟡
-

AWS Bedrock

-

Access Claude, Nova, Llama, and more through AWS infrastructure.

- - -
🐳
-

Docker Model Runner

-

Run models locally with Docker. No API keys, no costs.

- - -
🔧
-

Provider Definitions

-

Define reusable provider configurations with shared defaults for any provider type.

- -
+- **[OpenAI](../openai/index.md)** — GPT-5, GPT-5-mini, GPT-4o. The most widely used AI models. +- **[Anthropic](../anthropic/index.md)** — Claude Sonnet 4.5, Claude Opus 4.7. Excellent for coding and analysis. +- **[Google Gemini](../google/index.md)** — Gemini 2.5 Flash, Gemini 3 Pro. Fast and cost-effective. +- **[AWS Bedrock](../bedrock/index.md)** — Access Claude, Nova, Llama, and more through AWS infrastructure. +- **[Docker Model Runner](../dmr/index.md)** — Run models locally with Docker. No API keys, no costs. +- **[Provider Definitions](../custom/index.md)** — Define reusable provider configurations with shared defaults for any provider type. ## Quick Comparison @@ -90,12 +64,8 @@ agents: model: mistral/mistral-large-latest ``` -
-
Multi-provider teams -
-

Use expensive models for complex reasoning and cheaper/local models for routine tasks. See the example below.

- -
+> [!TIP] +> **Multi-provider teams**: Use expensive models for complex reasoning and cheaper/local models for routine tasks. See the example below. ## Using Multiple Providers diff --git a/docs/providers/ovhcloud/index.md b/docs/providers/ovhcloud/index.md index 7ff5b62926..3285e39e85 100644 --- a/docs/providers/ovhcloud/index.md +++ b/docs/providers/ovhcloud/index.md @@ -1,7 +1,7 @@ --- title: "OVHcloud" description: "Use OVHcloud AI Endpoints models with docker-agent." -permalink: /providers/ovhcloud/ +keywords: docker agent, ai agents, model providers, ovhcloud --- # OVHcloud diff --git a/docs/providers/together/index.md b/docs/providers/together/index.md index d6789dd4c8..94a5e5bd1b 100644 --- a/docs/providers/together/index.md +++ b/docs/providers/together/index.md @@ -1,7 +1,7 @@ --- title: "Together AI" description: "Use Together AI models with docker-agent." -permalink: /providers/together/ +keywords: docker agent, ai agents, model providers, together ai --- # Together AI diff --git a/docs/providers/vercel/index.md b/docs/providers/vercel/index.md index 6f0eeace7f..9ea5a81028 100644 --- a/docs/providers/vercel/index.md +++ b/docs/providers/vercel/index.md @@ -1,7 +1,7 @@ --- title: "Vercel AI Gateway" description: "Use Vercel AI Gateway models with docker-agent." -permalink: /providers/vercel/ +keywords: docker agent, ai agents, model providers, vercel ai gateway --- # Vercel AI Gateway diff --git a/docs/providers/xai/index.md b/docs/providers/xai/index.md index f6f139a318..6720cbcb4a 100644 --- a/docs/providers/xai/index.md +++ b/docs/providers/xai/index.md @@ -1,7 +1,7 @@ --- title: "xAI (Grok)" description: "Use xAI's Grok models with docker-agent." -permalink: /providers/xai/ +keywords: docker agent, ai agents, model providers, xai (grok) --- # xAI (Grok) @@ -71,7 +71,7 @@ Check the [xAI documentation](https://docs.x.ai/docs) for the latest available m docker-agent's `thinking_budget` field is **not applied** to xAI models: the underlying OpenAI-compatible client only sends `reasoning_effort` for OpenAI reasoning model names (o-series, gpt-5). Setting `thinking_budget` on a Grok model passes config validation but has no effect on the request. -Grok reasoning models (e.g. `grok-3-mini`) reason on their own without configuration. For non-reasoning models, use the [think tool]({{ '/tools/think/' | relative_url }}) instead. +Grok reasoning models (e.g. `grok-3-mini`) reason on their own without configuration. For non-reasoning models, use the [think tool](../../tools/think/index.md) instead. ## How It Works diff --git a/docs/tools/a2a/index.md b/docs/tools/a2a/index.md index 7c362907f0..5a9c477a77 100644 --- a/docs/tools/a2a/index.md +++ b/docs/tools/a2a/index.md @@ -1,7 +1,7 @@ --- title: "A2A Tool" description: "Connect to remote agents via the Agent-to-Agent protocol." -permalink: /tools/a2a/ +keywords: docker agent, ai agents, tools, a2a tool --- # A2A Tool @@ -10,7 +10,7 @@ _Connect to remote agents via the Agent-to-Agent protocol._ ## Overview -The A2A tool connects to a remote agent exposed over the A2A (Agent-to-Agent) protocol. Unlike [`handoff`]({{ '/tools/handoff/' | relative_url }}), which only targets local agents declared in the same config, `a2a` reaches out to an agent running on the network. +The A2A tool connects to a remote agent exposed over the A2A (Agent-to-Agent) protocol. Unlike [`handoff`](../handoff/index.md), which only targets local agents declared in the same config, `a2a` reaches out to an agent running on the network. ## Configuration @@ -34,8 +34,5 @@ toolsets: | `name` | string | ✗ | Tool name registered for the remote agent. Defaults to a name derived from the server's agent card. | | `headers` | map\[string\]string | ✗ | Extra HTTP headers sent with every request (useful for `Authorization`, tenant selection, tracing, \u2026). | -
-
See also -
-

For full details on the A2A protocol and serving agents as A2A endpoints, see A2A Protocol.

-
+> [!TIP] +> **See also**: For full details on the A2A protocol and serving agents as A2A endpoints, see [A2A Protocol](../../features/a2a/index.md). diff --git a/docs/tools/api/index.md b/docs/tools/api/index.md index 1c7ffb9adb..faa14983ac 100644 --- a/docs/tools/api/index.md +++ b/docs/tools/api/index.md @@ -1,7 +1,7 @@ --- title: "API Tool" description: "Create custom tools that call HTTP APIs." -permalink: /tools/api/ +keywords: docker agent, ai agents, tools, api tool --- # API Tool @@ -12,15 +12,12 @@ _Create custom tools that call HTTP APIs._ The API tool type lets you define custom tools that make HTTP requests to external APIs. This is useful for integrating agents with REST APIs, webhooks, or any HTTP-based service without writing code. -
-
When to Use -
- -- Integrating with REST APIs that don't have an MCP server -- Simple HTTP operations (GET, POST) -- Quick prototyping before building a full MCP server - -
+> [!NOTE] +> **When to Use**: +> +> - Integrating with REST APIs that don't have an MCP server +> - Simple HTTP operations (GET, POST) +> - Quick prototyping before building a full MCP server ## Configuration @@ -238,20 +235,11 @@ toolsets: instruction: Check the local service health ``` -
-
SSRF -
-

Setting allow_private_ips: true re-exposes the SSRF surface for this tool. Only enable it when the configured endpoint is a trusted internal service — a prompt-injected agent cannot redirect the call elsewhere because the endpoint is fixed in config, but redirects from the configured host can still reach unexpected places.

-
- -
-
For Complex APIs -
-

For APIs that need authentication flows, pagination, or complex request/response handling, consider using an MCP server instead. The API tool is best for simple, stateless HTTP operations.

-
- -
-
Security -
-

API keys and tokens in headers are visible in debug logs. Use environment variables (${env.VAR}) rather than hardcoding secrets in configuration files.

-
+> [!WARNING] +> **SSRF**: Setting `allow_private_ips: true` re-exposes the SSRF surface for this tool. Only enable it when the configured `endpoint` is a trusted internal service — a prompt-injected agent cannot redirect the call elsewhere because the endpoint is fixed in config, but redirects from the configured host can still reach unexpected places. + +> [!TIP] +> **For Complex APIs**: For APIs that need authentication flows, pagination, or complex request/response handling, consider using an MCP server instead. The API tool is best for simple, stateless HTTP operations. + +> [!WARNING] +> **Security**: API keys and tokens in headers are visible in debug logs. Use environment variables (`${env.VAR}`) rather than hardcoding secrets in configuration files. diff --git a/docs/tools/background-agents/index.md b/docs/tools/background-agents/index.md index e4a1b5b865..bcc1f4eca8 100644 --- a/docs/tools/background-agents/index.md +++ b/docs/tools/background-agents/index.md @@ -1,7 +1,7 @@ --- title: "Background Agents Tool" description: "Dispatch work to sub-agents concurrently and collect results asynchronously." -permalink: /tools/background-agents/ +keywords: docker agent, ai agents, tools, background agents tool --- # Background Agents Tool @@ -10,7 +10,7 @@ _Dispatch work to sub-agents concurrently and collect results asynchronously._ ## Overview -The background agents tool lets an orchestrator dispatch work to sub-agents concurrently and collect results asynchronously. Unlike [transfer_task]({{ '/tools/transfer-task/' | relative_url }}) (which blocks until the sub-agent finishes), background agent tasks run in parallel — the orchestrator can start several tasks, do other work, and check on them later. +The background agents tool lets an orchestrator dispatch work to sub-agents concurrently and collect results asynchronously. Unlike [transfer_task](../transfer-task/index.md) (which blocks until the sub-agent finishes), background agent tasks run in parallel — the orchestrator can start several tasks, do other work, and check on them later. ## Available Tools @@ -70,15 +70,12 @@ agents: ref: docker:duckduckgo ``` -
-
When to Use -
-

Use background_agents when your orchestrator needs to fan out work to multiple specialists in parallel — for example, researching several topics simultaneously or running independent code analyses side by side.

-
+> [!TIP] +> **When to Use**: Use `background_agents` when your orchestrator needs to fan out work to multiple specialists in parallel — for example, researching several topics simultaneously or running independent code analyses side by side. ## Using Harness Sub-Agents -Background agents work equally well with [harness-backed sub-agents]({{ '/features/harnesses/' | relative_url }}) — sub-agents driven by external coding CLIs such as Claude Code or Codex. This lets you dispatch multiple independent coding tasks in parallel: +Background agents work equally well with [harness-backed sub-agents](../../features/harnesses/index.md) — sub-agents driven by external coding CLIs such as Claude Code or Codex. This lets you dispatch multiple independent coding tasks in parallel: ```yaml agents: @@ -108,10 +105,7 @@ agents: The orchestrator calls `run_background_agent` for each coding task, then uses `list_background_agents` and `view_background_agent` to collect results when they finish. -
-
Harness toolsets are ignored -
-

Harness agents use the external CLI's own tools — any toolsets: configured on the harness agent are silently ignored. See Coding Harnesses for details and caveats.

-
+> [!NOTE] +> **Harness toolsets are ignored**: Harness agents use the external CLI's own tools — any `toolsets:` configured on the harness agent are silently ignored. See [Coding Harnesses](../../features/harnesses/index.md) for details and caveats. See [`examples/coding_harness_background_agents.yaml`](https://github.com/docker/docker-agent/blob/main/examples/coding_harness_background_agents.yaml) for a complete configuration. diff --git a/docs/tools/fetch/index.md b/docs/tools/fetch/index.md index f6d033505a..b72ea65b09 100644 --- a/docs/tools/fetch/index.md +++ b/docs/tools/fetch/index.md @@ -1,7 +1,7 @@ --- title: "Fetch Tool" description: "Read content from HTTP/HTTPS URLs." -permalink: /tools/fetch/ +keywords: docker agent, ai agents, tools, fetch tool --- # Fetch Tool @@ -12,12 +12,8 @@ _Read content from HTTP/HTTPS URLs._ The fetch tool lets agents retrieve content from one or more HTTP/HTTPS URLs. It is **read-only** — only `GET` requests are supported. The tool respects `robots.txt`, limits response size (1 MB per URL), and can return content as plain text, Markdown (converted from HTML), or raw HTML. -
-
GET only -
-

The fetch tool does not support POST, PUT, DELETE or other methods, and does not expose request bodies or per-call custom headers (the toolset can still attach static credential headers to every request). To call REST endpoints with other verbs, use the API tool or an OpenAPI toolset.

- -
+> [!NOTE] +> **GET only**: The fetch tool does **not** support `POST`, `PUT`, `DELETE` or other methods, and does not expose request bodies or per-call custom headers (the toolset can still attach static [credential headers](#custom-headers) to every request). To call REST endpoints with other verbs, use the [API tool](../api/index.md) or an [OpenAPI toolset](../openapi/index.md). ## Configuration @@ -51,11 +47,8 @@ The lists are mutually exclusive: a single fetch toolset may set either `allowed When a list is configured, every redirect target is re-checked against the same list. A request to an allowed origin that redirects to a forbidden host is rejected before any data is read from the redirect. -
-
Limitations -
-

Matching is purely string-based on the URL host. It does not perform DNS resolution and does not normalise alternative IP encodings (decimal 2852039166, hex 0xa9.0xfe.0xa9.0xfe, octal, etc. IPv4-mapped IPv6 addresses ARE normalized to their IPv4 form). If you need to deny access to a specific IP, also list its alternative encodings, or block at the network layer.

-
+> [!WARNING] +> **Limitations**: Matching is purely string-based on the URL host. It does **not** perform DNS resolution and does **not** normalise alternative IP encodings (decimal `2852039166`, hex `0xa9.0xfe.0xa9.0xfe`, octal, etc. IPv4-mapped IPv6 addresses ARE normalized to their IPv4 form). If you need to deny access to a specific IP, also list its alternative encodings, or block at the network layer. ### Custom Timeout @@ -79,11 +72,8 @@ toolsets: X-Internal-Client: "docker-agent" ``` -
-
Pair credential headers with an allow-list -
-

When headers carries credentials (e.g. Authorization), set allowed_domains to the specific hosts that should receive them. Stdlib already strips a small allow-list (Authorization, Cookie, WWW-Authenticate) on cross-domain redirects, and the fetch tool additionally strips every operator-supplied header on cross-host redirects — but an allow-list is the strongest guarantee against accidental exfiltration.

-
+> [!WARNING] +> **Pair credential headers with an allow-list**: When `headers` carries credentials (e.g. `Authorization`), set `allowed_domains` to the specific hosts that should receive them. Stdlib already strips a small allow-list (`Authorization`, `Cookie`, `WWW-Authenticate`) on cross-domain redirects, and the fetch tool additionally strips every operator-supplied header on cross-host redirects — but an allow-list is the strongest guarantee against accidental exfiltration. ### Restrict to specific domains @@ -109,11 +99,8 @@ toolsets: - internal.example.com # internal corporate hostname ``` -
-
Already blocked by default -
-

You do not need to add loopback, RFC1918, link-local (incl. 169.254.169.254), multicast or the unspecified address to blocked_domains to be safe — the fetch tool already refuses connections to those ranges at dial time, after DNS resolution. The example above is only useful if you also want to reject those hosts before any network call (and to surface a clearer error message to the agent), or if you have set allow_private_ips: true and want to deny a specific subset.

-
+> [!NOTE] +> **Already blocked by default**: You do **not** need to add loopback, RFC1918, link-local (incl. `169.254.169.254`), multicast or the unspecified address to `blocked_domains` to be safe — the fetch tool already refuses connections to those ranges at dial time, after DNS resolution. The example above is only useful if you also want to reject those hosts _before_ any network call (and to surface a clearer error message to the agent), or if you have set `allow_private_ips: true` and want to deny a specific subset. ### SSRF protection and reaching localhost @@ -139,12 +126,10 @@ toolsets: - 10.0.0.0/8 # internal corporate range ``` -
-
Pair with an allow-list -
-

Setting allow_private_ips: true alone re-exposes the SSRF surface. We strongly recommend combining it with an allowed_domains entry that restricts the tool to the specific internal hosts or CIDRs the agent actually needs (e.g. localhost, 127.0.0.1, or your internal CIDR).

-

Note: allowed_domains is checked before DNS resolution (string-based on hostname), while the SSRF check happens after DNS resolution (on the resolved IP). This means allowed_domains and blocked_domains are evaluated independently of allow_private_ips and continue to apply. A public hostname in allowed_domains that resolves to a private IP will still be blocked unless allow_private_ips: true is set.

-
+> [!WARNING] +> **Pair with an allow-list**: Setting `allow_private_ips: true` alone re-exposes the SSRF surface. We strongly recommend combining it with an `allowed_domains` entry that restricts the tool to the specific internal hosts or CIDRs the agent actually needs (e.g. `localhost`, `127.0.0.1`, or your internal CIDR). +> +> **Note:** `allowed_domains` is checked _before_ DNS resolution (string-based on hostname), while the SSRF check happens _after_ DNS resolution (on the resolved IP). This means `allowed_domains` and `blocked_domains` are evaluated independently of `allow_private_ips` and continue to apply. A public hostname in `allowed_domains` that resolves to a private IP will still be blocked unless `allow_private_ips: true` is set. ## Tool Interface @@ -158,11 +143,8 @@ The toolset exposes a single tool, `fetch`, with the following parameters: Responses are capped at **1 MB** per URL. Hosts that disallow the agent's user-agent via `robots.txt` are skipped with a clear error. -
-
Fetch vs. API Tool -
-

Use fetch when the agent needs to read arbitrary public URLs at runtime. Use the API tool to expose specific, structured HTTP endpoints (including non-GET verbs) as named tools.

-
+> [!TIP] +> **Fetch vs. API Tool**: Use `fetch` when the agent needs to read arbitrary public URLs at runtime. Use the [API tool](../api/index.md) to expose specific, structured HTTP endpoints (including non-`GET` verbs) as named tools. ## Domain Filtering diff --git a/docs/tools/filesystem/index.md b/docs/tools/filesystem/index.md index 7a9d546761..01c14ba1a1 100644 --- a/docs/tools/filesystem/index.md +++ b/docs/tools/filesystem/index.md @@ -1,7 +1,7 @@ --- title: "Filesystem Tool" description: "Read, write, list, search, and navigate files and directories." -permalink: /tools/filesystem/ +keywords: docker agent, ai agents, tools, filesystem tool --- # Filesystem Tool @@ -108,8 +108,5 @@ Post-edit commands run with the same working directory as the agent. If a comman See [`examples/post_edit.yaml`](https://github.com/docker/docker-agent/blob/main/examples/post_edit.yaml) for a complete example. -
-
Tip -
-

The filesystem tool resolves paths relative to the working directory. Agents can also use absolute paths.

-
+> [!TIP] +> The filesystem tool resolves paths relative to the working directory. Agents can also use absolute paths. diff --git a/docs/tools/handoff/index.md b/docs/tools/handoff/index.md index 148de6abf0..4fdc3184df 100644 --- a/docs/tools/handoff/index.md +++ b/docs/tools/handoff/index.md @@ -1,7 +1,7 @@ --- title: "Handoff Tool" description: "Hand off the active conversation to another local agent defined in the same config." -permalink: /tools/handoff/ +keywords: docker agent, ai agents, tools, handoff tool --- # Handoff Tool @@ -10,16 +10,12 @@ _Hand off the active conversation to another local agent defined in the same con ## Overview -The `handoff` tool lets an agent transfer control of the **current conversation** to another agent in the **same config file**. Unlike [`transfer_task`]({{ '/tools/transfer-task/' | relative_url }}), which delegates a sub-task and collects the result, `handoff` rewires the session so the receiving agent continues the conversation directly with the user. +The `handoff` tool lets an agent transfer control of the **current conversation** to another agent in the **same config file**. Unlike [`transfer_task`](../transfer-task/index.md), which delegates a sub-task and collects the result, `handoff` rewires the session so the receiving agent continues the conversation directly with the user. This is the core mechanism for **handoffs routing** — a pattern where a router agent classifies the user's request and hands it off to a specialist, which then owns the rest of the session. -
-
Local only -
-

The handoff tool only targets agents declared in the same config file by their local name. It does not open network connections. To delegate to a remote agent over the network, use the A2A toolset instead.

- -
+> [!NOTE] +> **Local only**: The `handoff` tool only targets agents declared in the **same** config file by their local name. It does **not** open network connections. To delegate to a remote agent over the network, use the [A2A toolset](../a2a/index.md) instead. ## Configuration @@ -58,9 +54,5 @@ The `handoff` tool takes a single parameter: Only names listed in the current agent's `handoffs:` field are valid targets. -
-
See also -
-

For sub-task delegation (caller stays in control, waits for the result), see Transfer Task. For remote agent connections over the network, see the A2A toolset. For the broader pattern, see Handoffs Routing.

- -
+> [!TIP] +> **See also**: For sub-task delegation (caller stays in control, waits for the result), see [Transfer Task](../transfer-task/index.md). For remote agent connections over the network, see the [A2A toolset](../a2a/index.md). For the broader pattern, see [Handoffs Routing](../../concepts/multi-agent/index.md#handoffs-routing). diff --git a/docs/tools/lsp/index.md b/docs/tools/lsp/index.md index 147ff2a809..72bb51eecf 100644 --- a/docs/tools/lsp/index.md +++ b/docs/tools/lsp/index.md @@ -1,7 +1,7 @@ --- title: "LSP Tool" description: "Connect to Language Server Protocol servers for code intelligence." -permalink: /tools/lsp/ +keywords: docker agent, ai agents, tools, lsp tool --- # LSP Tool @@ -12,11 +12,8 @@ _Connect to Language Server Protocol servers for code intelligence._ The LSP tool connects your agent to any Language Server Protocol (LSP) server, providing comprehensive code intelligence capabilities like go-to-definition, find references, diagnostics, and more. -
-
What is LSP? -
-

The Language Server Protocol is a standard for providing language features like autocomplete, go-to-definition, and diagnostics. Most programming languages have LSP servers available.

-
+> [!NOTE] +> **What is LSP?** The [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) is a standard for providing language features like autocomplete, go-to-definition, and diagnostics. Most programming languages have LSP servers available. ## Available Tools @@ -66,7 +63,7 @@ agents: | `env` | object | ✗ | Environment variables for the LSP process | | `file_types` | array | ✗ | File extensions this LSP handles (e.g., `[".go", ".mod"]`) | | `working_dir` | string | ✗ | Working directory for the LSP server process. Relative paths are resolved against the agent's working directory. Defaults to the agent's working directory when omitted. | -| `version` | string | ✗ | Package reference for [auto-installing]({{ '/configuration/tools/#auto-installing-tools' | relative_url }}) the command binary | +| `version` | string | ✗ | Package reference for [auto-installing](../../configuration/tools/index.md#auto-installing-tools) the command binary | ## Common LSP Servers @@ -164,11 +161,8 @@ The LSP tool includes built-in instructions that guide the agent on how to use i 4. Check `lsp_diagnostics` after every code change 5. Apply `lsp_format` after edits are complete -
-
Best Practice -
-

Always include the filesystem tool alongside LSP. The agent needs filesystem access to read and write code files, while LSP provides intelligence about the code.

-
+> [!TIP] +> **Best Practice**: Always include the `filesystem` tool alongside LSP. The agent needs filesystem access to read and write code files, while LSP provides intelligence about the code. ## Capability Detection @@ -196,7 +190,7 @@ Available Capabilities: ## Auto-Restart and Lifecycle -LSP toolsets are managed by the same supervisor as MCP toolsets, so a crashed `gopls` (or any other language server) is reconnected automatically with exponential backoff. Use the [`lifecycle`]({{ '/configuration/tools/#toolset-lifecycle' | relative_url }}) block to tune the policy per toolset — for example, mark `gopls` as `strict` if your CI flow requires it to be available, or use `/toolset-restart gopls` from the TUI to force a reconnect when the server gets stuck. +LSP toolsets are managed by the same supervisor as MCP toolsets, so a crashed `gopls` (or any other language server) is reconnected automatically with exponential backoff. Use the [`lifecycle`](../../configuration/tools/index.md#toolset-lifecycle) block to tune the policy per toolset — for example, mark `gopls` as `strict` if your CI flow requires it to be available, or use `/toolset-restart gopls` from the TUI to force a reconnect when the server gets stuck. ```yaml toolsets: @@ -222,8 +216,5 @@ All LSP tools use **1-based** line and character positions: } ``` -
-
Auto-Installation -
-

docker-agent can automatically download and install LSP servers if they are not found in your PATH. Use the version property to specify a package, or let docker-agent auto-detect it from the command name. See Auto-Installing Tools for details.

-
+> [!TIP] +> **Auto-Installation**: docker-agent can automatically download and install LSP servers if they are not found in your PATH. Use the `version` property to specify a package, or let docker-agent auto-detect it from the command name. See [Auto-Installing Tools](../../configuration/tools/index.md#auto-installing-tools) for details. diff --git a/docs/tools/mcp-catalog/index.md b/docs/tools/mcp-catalog/index.md index 1e55d7686f..c810f8b5dd 100644 --- a/docs/tools/mcp-catalog/index.md +++ b/docs/tools/mcp-catalog/index.md @@ -1,7 +1,7 @@ --- title: "MCP Catalog Tool" description: "Let the agent discover and activate remote MCP servers from the Docker MCP Catalog on demand." -permalink: /tools/mcp-catalog/ +keywords: docker agent, ai agents, tools, mcp catalog tool --- # MCP Catalog Tool @@ -14,11 +14,8 @@ The `mcp_catalog` toolset gives an agent access to a curated subset of the [Dock Servers are **not** active by default. Instead, the toolset exposes a small set of meta-tools the agent uses to search, enable, and disable servers as a turn unfolds. Tools from un-enabled servers stay hidden, so the prompt is not flooded with hundreds of tool definitions the agent will never use. -
-
When to use it -
-

Use mcp_catalog when you want the agent to decide at runtime which third-party services it needs (Notion, Stripe, Brave Search, …) instead of pinning that decision in YAML up front. For a fixed set of servers, declare each one with type: mcp directly — the catalog adds an extra layer of meta-tools that pure type: mcp entries do not need.

-
+> [!NOTE] +> **When to use it**: Use `mcp_catalog` when you want the agent to _decide at runtime_ which third-party services it needs (Notion, Stripe, Brave Search, …) instead of pinning that decision in YAML up front. For a fixed set of servers, declare each one with [`type: mcp`](../../configuration/tools/index.md#mcp-tools) directly — the catalog adds an extra layer of meta-tools that pure `type: mcp` entries do not need. ## Configuration @@ -77,7 +74,7 @@ The catalog only includes servers docker-agent can authenticate itself, so there - **`oauth`** — `enable_remote_mcp_server` surfaces an authorization URL through the elicitation pipeline (the same one used by YAML-declared remote MCP toolsets) and blocks until the user either authorizes or cancels. Once the user authorizes, tokens are persisted in the OS keyring and re-used on subsequent runs. Use `reset_remote_mcp_server_auth` to wipe them. If the user dismisses the dialog, `enable` returns an error result naming the decline so the agent can ask whether to retry. - **`none`** — No authentication. The server is reachable as soon as it is enabled. -Servers that require a caller-provided API key are intentionally excluded from the catalog. To use one, declare it explicitly with [`type: mcp`]({{ '/configuration/tools/#mcp-tools' | relative_url }}) and supply the key via an environment variable. +Servers that require a caller-provided API key are intentionally excluded from the catalog. To use one, declare it explicitly with [`type: mcp`](../../configuration/tools/index.md#mcp-tools) and supply the key via an environment variable. ## Example @@ -101,14 +98,11 @@ A complete, runnable configuration lives in [`examples/mcp_catalog.yaml`](https: ## Notes and Limitations -- **Streamable-http only.** The catalog deliberately excludes servers that require a local subprocess or the MCP gateway — declare those with [`type: mcp`]({{ '/configuration/tools/#mcp-tools' | relative_url }}) instead. +- **Streamable-http only.** The catalog deliberately excludes servers that require a local subprocess or the MCP gateway — declare those with [`type: mcp`](../../configuration/tools/index.md#mcp-tools) instead. - **Catalog membership changes between releases.** The set of available servers is updated with each docker-agent release as integrations are added or removed. Servers present in one release may not appear in the next. - **Blocking enable.** DNS, TCP, MCP handshake and any OAuth flow happen synchronously inside `enable_remote_mcp_server` so the agent gets a deterministic result in the same turn. On startup, however, the runtime probes tools non-interactively (`mcp.WithoutInteractivePrompts`); OAuth-pending servers fail fast there and are silently deferred to the next interactive turn — including the sidebar-only tool-count pass, where a dialog would be impossible. - **No prompt discovery.** MCP prompt lookups (`/prompts`) walk YAML-declared `mcp` toolsets directly; prompts exposed by servers activated through the catalog are not surfaced. Tools — the primary interface — work fine. - **Frozen at build time.** The list of servers is embedded in the binary. New entries land with each docker-agent release. -
-
Pair with permissions -
-

Because the agent decides which third-party services to talk to, this toolset works best with explicit permissions on the surrounding tools (filesystem writes, shell commands) so a misrouted server cannot exfiltrate data unnoticed.

-
+> [!TIP] +> **Pair with permissions**: Because the agent decides which third-party services to talk to, this toolset works best with explicit [permissions](../../configuration/permissions/index.md) on the surrounding tools (filesystem writes, shell commands) so a misrouted server cannot exfiltrate data unnoticed. diff --git a/docs/tools/mcp/index.md b/docs/tools/mcp/index.md index e2abef0552..b61623dc2f 100644 --- a/docs/tools/mcp/index.md +++ b/docs/tools/mcp/index.md @@ -1,7 +1,7 @@ --- title: "MCP Tool" description: "Extend agents with external tools via the Model Context Protocol." -permalink: /tools/mcp/ +keywords: docker agent, ai agents, tools, mcp tool --- # MCP Tool @@ -18,11 +18,8 @@ The `mcp` toolset connects your agent to any MCP server — a process or remote | **Local stdio** | Subprocess over stdin/stdout | Custom or community MCP servers run from a binary or `npx`/`pip` package | | **Remote** | Streamable HTTP or SSE | Cloud services with hosted MCP endpoints (Linear, Notion, Atlassian, …) | -
-
What is MCP? -
-

The Model Context Protocol is an open standard for connecting AI tools. Docker Agent can both use MCP servers (this page) and expose agents as MCP servers — see MCP Mode.

-
+> [!NOTE] +> **What is MCP?** The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard for connecting AI tools. Docker Agent can both _use_ MCP servers (this page) and _expose_ agents as MCP servers — see [MCP Mode](../../features/mcp-mode/index.md). ## Docker MCP (Recommended) @@ -41,11 +38,11 @@ Browse available servers at the [Docker MCP Catalog](https://hub.docker.com/u/mc | Property | Type | Description | | ------------- | ------ | ---------------------------------------------------------------- | -| `ref` | string | Docker MCP reference (`docker:name`) or a name from the [reusable `mcps:`]({{ '/configuration/overview/#reusable-mcp-servers-mcps' | relative_url }}) block. | +| `ref` | string | Docker MCP reference (`docker:name`) or a name from the [reusable `mcps:`](../../configuration/overview/index.md#reusable-mcp-servers-mcps) block. | | `tools` | array | Optional whitelist — only expose these tools to the model. | | `instruction` | string | Custom instructions injected into the agent's context. | | `config` | any | MCP server-specific configuration passed during initialization. | -| `working_dir` | string | Working directory for the MCP gateway subprocess. Only applies when the catalog entry runs as a local process (not remote). Relative paths are resolved against the agent's working directory. Supports `${env.VAR}` (canonical), plus `~` and shell-style `$VAR`/`${VAR}` expansion ([details]({{ '/configuration/overview/#variable-expansion-in-config-fields' | relative_url }})). | +| `working_dir` | string | Working directory for the MCP gateway subprocess. Only applies when the catalog entry runs as a local process (not remote). Relative paths are resolved against the agent's working directory. Supports `${env.VAR}` (canonical), plus `~` and shell-style `$VAR`/`${VAR}` expansion ([details](../../configuration/overview/index.md#variable-expansion-in-config-fields)). | ## Local MCP (stdio) @@ -67,15 +64,12 @@ toolsets: | `args` | array | Command arguments. | | `tools` | array | Optional whitelist — only expose these tools. | | `env` | object | Environment variables (key-value pairs). | -| `working_dir` | string | Working directory for the MCP server process. Relative paths are resolved against the agent's working directory. Defaults to the agent's working directory when omitted. Supports `${env.VAR}` (canonical), plus `~` and shell-style `$VAR`/`${VAR}` expansion ([details]({{ '/configuration/overview/#variable-expansion-in-config-fields' | relative_url }})). | +| `working_dir` | string | Working directory for the MCP server process. Relative paths are resolved against the agent's working directory. Defaults to the agent's working directory when omitted. Supports `${env.VAR}` (canonical), plus `~` and shell-style `$VAR`/`${VAR}` expansion ([details](../../configuration/overview/index.md#variable-expansion-in-config-fields)). | | `instruction` | string | Custom instructions injected into the agent's context. | -| `version` | string | Package reference for [auto-installing]({{ '/configuration/tools/#auto-installing-tools' | relative_url }}) the command binary. | +| `version` | string | Package reference for [auto-installing](../../configuration/tools/index.md#auto-installing-tools) the command binary. | -
-
Auto-installation -
-

If the command is not in your PATH, docker-agent looks it up in the aqua registry and installs it for you. Use version: "false" to opt out, or set DOCKER_AGENT_AUTO_INSTALL=false globally. See Auto-Installing Tools.

-
+> [!TIP] +> **Auto-installation**: If the `command` is not in your `PATH`, docker-agent looks it up in the [aqua registry](https://github.com/aquaproj/aqua-registry) and installs it for you. Use `version: "false"` to opt out, or set `DOCKER_AGENT_AUTO_INSTALL=false` globally. See [Auto-Installing Tools](../../configuration/tools/index.md#auto-installing-tools). ## Remote MCP (Streamable HTTP / SSE) @@ -99,10 +93,10 @@ toolsets: | `remote.url` | string | Base URL of the MCP server. | | `remote.transport_type` | string | `streamable` or `sse`. | | `remote.headers` | object | HTTP headers (typically for static auth tokens). | -| `remote.oauth` | object | Explicit OAuth client credentials for servers that don't support DCR. See [Remote MCP Servers]({{ '/features/remote-mcp/' | relative_url }}#oauth-for-servers-without-dynamic-client-registration). | +| `remote.oauth` | object | Explicit OAuth client credentials for servers that don't support DCR. See [Remote MCP Servers](../../features/remote-mcp/index.md#oauth-for-servers-without-dynamic-client-registration). | | `allow_private_ips` | boolean | Permit remote MCP OAuth helper requests to dial non-public IP addresses. Use only for trusted internal servers. | -For a curated list of public remote MCP endpoints (Linear, GitHub, Vercel, Notion, …) and full OAuth configuration details, see [Remote MCP Servers]({{ '/features/remote-mcp/' | relative_url }}). +For a curated list of public remote MCP endpoints (Linear, GitHub, Vercel, Notion, …) and full OAuth configuration details, see [Remote MCP Servers](../../features/remote-mcp/index.md). ## Embedded Resources @@ -138,7 +132,7 @@ agents: ref: playwright ``` -See [Reusable MCP Servers]({{ '/configuration/overview/#reusable-mcp-servers-mcps' | relative_url }}) for the full reference. +See [Reusable MCP Servers](../../configuration/overview/index.md#reusable-mcp-servers-mcps) for the full reference. ## Common Options @@ -213,7 +207,7 @@ toolsets: model: openai/gpt-4o-mini ``` -See [Per-Toolset Model Routing]({{ '/configuration/tools/#per-toolset-model-routing' | relative_url }}). +See [Per-Toolset Model Routing](../../configuration/tools/index.md#per-toolset-model-routing). ### Lifecycle (auto-restart, profiles) @@ -232,7 +226,7 @@ toolsets: profile: strict # fail-fast: required, no retries ``` -See [Toolset Lifecycle]({{ '/configuration/tools/#toolset-lifecycle' | relative_url }}) for all profiles and tuning knobs, and [`/toolset-restart`]({{ '/features/tui/' | relative_url }}) to force a reconnect from the TUI. +See [Toolset Lifecycle](../../configuration/tools/index.md#toolset-lifecycle) for all profiles and tuning knobs, and [`/toolset-restart`](../../features/tui/index.md) to force a reconnect from the TUI. ## Combined Example @@ -273,16 +267,13 @@ agents: instruction: Use Linear for issue tracking. ``` -
-
Toolset order matters -
-

If multiple toolsets provide a tool with the same name, the first one wins: the duplicate from the later toolset is ignored and a warning identifies both toolsets. Order your toolsets intentionally. To keep both tools callable, give the MCP toolset a unique name: (its tools are then exposed as <name>_<tool>) or restrict the overlapping toolset with its tools: filter.

-
+> [!WARNING] +> **Toolset order matters**: If multiple toolsets provide a tool with the same name, the first one wins: the duplicate from the later toolset is ignored and a warning identifies both toolsets. Order your toolsets intentionally. To keep both tools callable, give the MCP toolset a unique `name:` (its tools are then exposed as `_`) or restrict the overlapping toolset with its `tools:` filter. ## See Also -- [Tool Configuration]({{ '/configuration/tools/' | relative_url }}) — full reference for every toolset type, plus shared options (lifecycle, TOON, model routing, …). -- [Reusable MCP Servers]({{ '/configuration/overview/#reusable-mcp-servers-mcps' | relative_url }}) — the top-level `mcps:` block. -- [Remote MCP Servers]({{ '/features/remote-mcp/' | relative_url }}) — catalog of public remote MCP endpoints + OAuth recipes. -- [MCP Mode]({{ '/features/mcp-mode/' | relative_url }}) — expose your own agents as MCP tools to Claude Desktop, Claude Code, etc. -- [Auto-Installing Tools]({{ '/configuration/tools/#auto-installing-tools' | relative_url }}) — automatic installation of MCP server binaries. +- [Tool Configuration](../../configuration/tools/index.md) — full reference for every toolset type, plus shared options (lifecycle, TOON, model routing, …). +- [Reusable MCP Servers](../../configuration/overview/index.md#reusable-mcp-servers-mcps) — the top-level `mcps:` block. +- [Remote MCP Servers](../../features/remote-mcp/index.md) — catalog of public remote MCP endpoints + OAuth recipes. +- [MCP Mode](../../features/mcp-mode/index.md) — expose your own agents as MCP tools to Claude Desktop, Claude Code, etc. +- [Auto-Installing Tools](../../configuration/tools/index.md#auto-installing-tools) — automatic installation of MCP server binaries. diff --git a/docs/tools/memory/index.md b/docs/tools/memory/index.md index b98f5efbda..9cc9f0aa9f 100644 --- a/docs/tools/memory/index.md +++ b/docs/tools/memory/index.md @@ -1,7 +1,7 @@ --- title: "Memory Tool" description: "Persistent key-value storage backed by SQLite for cross-session recall." -permalink: /tools/memory/ +keywords: docker agent, ai agents, tools, memory tool --- # Memory Tool @@ -54,8 +54,5 @@ Memories support an optional `category` field for organization and filtering. Co - `project` — Project-specific context - `decision` — Past decisions and their rationale -
-
Tip -
-

Memory is especially useful for long-running assistants that need to recall information across conversations — like coding preferences, project conventions, or context discovered during previous sessions.

-
+> [!TIP] +> Memory is especially useful for long-running assistants that need to recall information across conversations — like coding preferences, project conventions, or context discovered during previous sessions. diff --git a/docs/tools/model-picker/index.md b/docs/tools/model-picker/index.md index 5239dbee9a..03fc1d9908 100644 --- a/docs/tools/model-picker/index.md +++ b/docs/tools/model-picker/index.md @@ -1,7 +1,7 @@ --- title: "Model Picker Tool" description: "Let the agent pick between several models per turn." -permalink: /tools/model-picker/ +keywords: docker agent, ai agents, tools, model picker tool --- # Model Picker Tool @@ -50,12 +50,8 @@ agents: - openai/gpt-5 ``` -
-
Cost optimization -
-

The model picker tool is particularly useful for cost optimization: let the agent use a cheap model by default and only escalate to expensive models when necessary.

- -
+> [!TIP] +> **Cost optimization**: The model picker tool is particularly useful for cost optimization: let the agent use a cheap model by default and only escalate to expensive models when necessary. ## Tool Interface diff --git a/docs/tools/open-url/index.md b/docs/tools/open-url/index.md index b8e39d3a31..9e36c30a2f 100644 --- a/docs/tools/open-url/index.md +++ b/docs/tools/open-url/index.md @@ -1,7 +1,7 @@ --- title: "Open URL Tool" description: "Open a fixed URL in the user's default browser." -permalink: /tools/open-url/ +keywords: docker agent, ai agents, tools, open url tool --- # Open URL Tool @@ -16,15 +16,12 @@ never supplies the URL — it just calls the tool by name. Launching the browser is cross-platform: docker-agent uses `open` on macOS, `xdg-open` on Linux, and `rundll32` on Windows. -
-
When to Use -
- -- Letting an agent open a dashboard, documentation page, or deep link on demand -- Deep-linking into a desktop app via a custom URI scheme (e.g. `docker-desktop://`) -- Any "take me there" action where the destination is fixed and known up front - -
+> [!NOTE] +> **When to Use**: +> +> - Letting an agent open a dashboard, documentation page, or deep link on demand +> - Deep-linking into a desktop app via a custom URI scheme (e.g. `docker-desktop://`) +> - Any "take me there" action where the destination is fixed and known up front ## Configuration diff --git a/docs/tools/openapi/index.md b/docs/tools/openapi/index.md index f4abcd05d0..97132a690d 100644 --- a/docs/tools/openapi/index.md +++ b/docs/tools/openapi/index.md @@ -1,7 +1,7 @@ --- title: "OpenAPI Tool" description: "Automatically generate tools from an OpenAPI specification." -permalink: /tools/openapi/ +keywords: docker agent, ai agents, tools, openapi tool --- # OpenAPI Tool diff --git a/docs/tools/plan/index.md b/docs/tools/plan/index.md index 32d06feff2..c89d46bea9 100644 --- a/docs/tools/plan/index.md +++ b/docs/tools/plan/index.md @@ -1,7 +1,7 @@ --- title: "Plan Tool" description: "Shared persistent scratchpad for multi-agent collaboration." -permalink: /tools/plan/ +keywords: docker agent, ai agents, tools, plan tool --- # Plan Tool @@ -126,8 +126,5 @@ See [`examples/shared_plan.yaml`](https://github.com/docker/docker-agent/blob/ma - `list_plans` skips corrupt entries but reports them in a `warnings` field so an agent can detect and recover from a bad state (e.g., by calling `delete_plan`). - `delete_plan` can remove a corrupt plan to recover from a bad state. -
-
Plan vs. Todo vs. Tasks -
-

Use plan for shared, free-form documents that multiple agents collaborate on (design docs, requirements, work items). Use todo for lightweight in-session task lists. Use tasks for a structured, persistent task database with priorities and dependencies.

-
+> [!TIP] +> **Plan vs. Todo vs. Tasks**: Use **plan** for shared, free-form documents that multiple agents collaborate on (design docs, requirements, work items). Use [todo](../todo/index.md) for lightweight in-session task lists. Use [tasks](../tasks/index.md) for a structured, persistent task database with priorities and dependencies. diff --git a/docs/tools/rag/index.md b/docs/tools/rag/index.md index 35576f9d46..f70b7af045 100644 --- a/docs/tools/rag/index.md +++ b/docs/tools/rag/index.md @@ -1,7 +1,7 @@ --- title: "RAG Tool" description: "Give your agents access to document knowledge bases with background indexing, multiple retrieval strategies, and hybrid search." -permalink: /tools/rag/ +keywords: docker agent, ai agents, tools, rag tool --- # RAG Tool @@ -79,12 +79,8 @@ strategies: code_aware: true # AST-aware chunking ``` -
-
Trade-offs -
-

Semantic embeddings provide higher quality retrieval but slower indexing (LLM call per chunk) and additional API costs.

- -
+> [!NOTE] +> **Trade-offs**: Semantic embeddings provide higher quality retrieval but slower indexing (LLM call per chunk) and additional API costs. ### BM25 (Keyword Search) @@ -166,12 +162,8 @@ chunking: code_aware: true # Uses tree-sitter for AST-based chunking ``` -
-
Language Support -
-

Currently supports Go (.go) files. More languages will be added. Falls back to plain text chunking for unsupported file types.

- -
+> [!NOTE] +> **Language Support**: Currently supports Go (`.go`) files. More languages will be added. Falls back to plain text chunking for unsupported file types. ## Debugging RAG @@ -188,12 +180,8 @@ Look for log tags: `[RAG Manager]`, `[Chunked-Embeddings Strategy]`, `[BM25 Stra - **Indexing** — the entire indexing run is aborted after the first permanent failure (including 429). The error is surfaced in the logs so you know immediately if a model name or API key is wrong, rather than silently producing incomplete results. - **Reranking** — a permanent error (including 429) permanently disables the reranker for the lifetime of the manager. Subsequent queries fall back to un-reranked results. Only transient errors (5xx, timeouts) fall back and retry on the next query. -
-
Examples -
-

See the RAG examples in the GitHub repo for complete, runnable configurations.

- -
+> [!TIP] +> **Examples**: See the [RAG examples](https://github.com/docker/docker-agent/tree/main/examples/rag) in the GitHub repo for complete, runnable configurations. ## Configuration Reference diff --git a/docs/tools/script/index.md b/docs/tools/script/index.md index 07a77a731a..c57c849c7e 100644 --- a/docs/tools/script/index.md +++ b/docs/tools/script/index.md @@ -1,7 +1,7 @@ --- title: "Script Tool" description: "Define custom shell scripts as named tools with typed parameters." -permalink: /tools/script/ +keywords: docker agent, ai agents, tools, script tool --- # Script Tool @@ -10,7 +10,7 @@ _Define custom shell scripts as named tools with typed parameters._ ## Overview -The script tool lets you define custom shell scripts as named tools. Unlike the generic [shell tool]({{ '/tools/shell/' | relative_url }}) where the agent writes the command, script tools execute predefined commands — ideal for exposing safe, well-scoped operations with descriptive names. +The script tool lets you define custom shell scripts as named tools. Unlike the generic [shell tool](../shell/index.md) where the agent writes the command, script tools execute predefined commands — ideal for exposing safe, well-scoped operations with descriptive names. ## Configuration @@ -57,8 +57,5 @@ toolsets: | `shell..env` | object | Environment variables for this script | | `shell..working_dir` | string | Working directory for script execution | -
-
Script vs. Shell -
-

Use the shell tool when the agent needs to run arbitrary commands. Use the script tool when you want to expose specific, predefined operations with clear names and typed parameters — giving the agent less freedom but more safety.

-
+> [!TIP] +> **Script vs. Shell**: Use the [shell tool](../shell/index.md) when the agent needs to run arbitrary commands. Use the script tool when you want to expose specific, predefined operations with clear names and typed parameters — giving the agent less freedom but more safety. diff --git a/docs/tools/session_context/index.md b/docs/tools/session_context/index.md index cdb331d265..e45a4eab0a 100644 --- a/docs/tools/session_context/index.md +++ b/docs/tools/session_context/index.md @@ -1,7 +1,7 @@ --- title: "Session Context Tool" description: "Reference a previous session as context in the current one." -permalink: /tools/session_context/ +keywords: docker agent, ai agents, tools, session context tool --- # Session Context Tool @@ -51,7 +51,7 @@ toolsets: A long session could overflow the current context window, so `read_session` caps the rendered transcript. When a transcript is larger than the budget, the oldest messages are dropped (the most recent are usually the most useful for continuing work) and a note records how many were omitted: -``` +```text [12 earlier message(s) omitted to fit the context budget; showing the most recent 8] ``` diff --git a/docs/tools/session_plan/index.md b/docs/tools/session_plan/index.md index 64f9df6ed6..21cfbffd11 100644 --- a/docs/tools/session_plan/index.md +++ b/docs/tools/session_plan/index.md @@ -1,7 +1,7 @@ --- title: "Session Plan Tool" description: "Per-session plan tracker for the draft, review, execute workflow." -permalink: /tools/session_plan/ +keywords: docker agent, ai agents, tools, session plan tool --- # Session Plan Tool @@ -12,11 +12,11 @@ _Per-session plan tracker for the "draft, review, execute" workflow._ The `session_plan` toolset gives one agent a place to write a plan for the current session, signal that the plan is ready, and let the host route the next turn to an executing agent. -Different from the [`plan` toolset](/tools/plan/) — `plan` is for shared, named plans multiple agents collaborate on over many sessions. `session_plan` is for one ephemeral plan per session, scoped to that session by ID. +Different from the [`plan` toolset](../plan/index.md) — `plan` is for shared, named plans multiple agents collaborate on over many sessions. `session_plan` is for one ephemeral plan per session, scoped to that session by ID. Plans live as Markdown files under: -``` +```text ~/.cagent/session_plans/.md ``` @@ -120,8 +120,5 @@ See [`examples/session_plan.yaml`](https://github.com/docker/docker-agent/blob/m - `read_session_plan` and `exit_plan_mode` return a "no plan written yet" error when called before `write_session_plan`. - `write_session_plan` validates the session ID and refuses to write anything that could escape the plans directory; in practice the runtime generates UUIDs so this only triggers if an embedder supplies a hand-crafted ID. -
-
session_plan vs. plan vs. todo vs. tasks -
-

Use session_plan when one agent drafts an approach for the user to review before another agent executes it (ephemeral, one per session). Use plan for shared, named plans multiple agents collaborate on over many sessions. Use todo for lightweight in-session task lists. Use tasks for a structured, persistent task database with priorities and dependencies.

-
+> [!TIP] +> **session_plan vs. plan vs. todo vs. tasks**: Use **session_plan** when one agent drafts an approach for the user to review before another agent executes it (ephemeral, one per session). Use [plan](../plan/index.md) for shared, named plans multiple agents collaborate on over many sessions. Use [todo](../todo/index.md) for lightweight in-session task lists. Use [tasks](../tasks/index.md) for a structured, persistent task database with priorities and dependencies. diff --git a/docs/tools/shell/index.md b/docs/tools/shell/index.md index bf14c92d9f..6a4cf36f6f 100644 --- a/docs/tools/shell/index.md +++ b/docs/tools/shell/index.md @@ -1,7 +1,7 @@ --- title: "Shell Tool" description: "Execute arbitrary shell commands in the user's environment." -permalink: /tools/shell/ +keywords: docker agent, ai agents, tools, shell tool --- # Shell Tool @@ -49,7 +49,7 @@ toolsets: safer: true ``` -This auto-registers the [`safer_shell`](../../configuration/hooks/#built-in-hooks) builtin +This auto-registers the [`safer_shell`](../../configuration/hooks/index.md#built-in-hooks) builtin under `pre_tool_use` with `preempt_yolo: true` so the entry fires before `Decide()` / `--yolo`. Three behaviors: @@ -117,14 +117,8 @@ Background job output is captured up to 10 MB per job. All background jobs are a `view_background_job` and `stop_background_job` each take a single required `job_id` string returned by `run_background_job` or `list_background_jobs`. -
-
Safety -
-

The shell tool gives agents full access to the system shell. Always set max_iterations on agents that use the shell tool to prevent infinite loops. A value of 20–50 is typical for development agents. Use Sandbox Mode for additional isolation.

-
- -
-
Tool Confirmation -
-

By default, docker-agent asks for user confirmation before executing shell commands. Use --yolo to auto-approve all tool calls.

-
+> [!WARNING] +> **Safety**: The shell tool gives agents full access to the system shell. Always set `max_iterations` on agents that use the shell tool to prevent infinite loops. A value of 20–50 is typical for development agents. Use [Sandbox Mode](../../configuration/sandbox/index.md) for additional isolation. + +> [!NOTE] +> **Tool Confirmation**: By default, docker-agent asks for user confirmation before executing shell commands. Use `--yolo` to auto-approve all tool calls. diff --git a/docs/tools/tasks/index.md b/docs/tools/tasks/index.md index 6403c67289..9020c02c9d 100644 --- a/docs/tools/tasks/index.md +++ b/docs/tools/tasks/index.md @@ -1,7 +1,7 @@ --- title: "Tasks Tool" description: "Persistent task database with priorities and dependencies, shared across sessions." -permalink: /tools/tasks/ +keywords: docker agent, ai agents, tools, tasks tool --- # Tasks Tool @@ -10,7 +10,7 @@ _Persistent task database with priorities and dependencies, shared across sessio ## Overview -The tasks tool provides a persistent task database that survives across agent sessions. Unlike the [Todo tool]({{ '/tools/todo/' | relative_url }}), which maintains an in-memory task list for the current session only, the tasks tool stores tasks in a JSON file on disk so they can be accessed and updated across multiple sessions. Tasks support priorities and dependencies — a task is _blocked_ until every task it depends on is `done`. +The tasks tool provides a persistent task database that survives across agent sessions. Unlike the [Todo tool](../todo/index.md), which maintains an in-memory task list for the current session only, the tasks tool stores tasks in a JSON file on disk so they can be accessed and updated across multiple sessions. Tasks support priorities and dependencies — a task is _blocked_ until every task it depends on is `done`. ## Configuration @@ -52,9 +52,5 @@ agents: path: ./project-tasks.json ``` -
-
Tasks vs. Todo -
-

Use the tasks tool when you need persistence across sessions, priorities, or dependencies (e.g., long-running projects, recurring work). Use the todo tool for ephemeral, session-scoped task lists.

- -
+> [!TIP] +> **Tasks vs. Todo**: Use the **tasks** tool when you need persistence across sessions, priorities, or dependencies (e.g., long-running projects, recurring work). Use the [todo tool](../todo/index.md) for ephemeral, session-scoped task lists. diff --git a/docs/tools/think/index.md b/docs/tools/think/index.md index b616c72800..165ac47a2f 100644 --- a/docs/tools/think/index.md +++ b/docs/tools/think/index.md @@ -1,7 +1,7 @@ --- title: "Think Tool" description: "Step-by-step reasoning scratchpad for planning and decision-making." -permalink: /tools/think/ +keywords: docker agent, ai agents, tools, think tool --- # Think Tool @@ -23,8 +23,5 @@ toolsets: No configuration options. -
-
When to use -
-

Use the think tool with models that don't have native reasoning capabilities. If your model already supports a thinking budget, you likely don't need this tool.

-
+> [!TIP] +> **When to use**: Use the think tool with models that don't have native reasoning capabilities. If your model already supports a [thinking budget](../../configuration/models/index.md#thinking-budget), you likely don't need this tool. diff --git a/docs/tools/todo/index.md b/docs/tools/todo/index.md index a8872de949..b5a79b18af 100644 --- a/docs/tools/todo/index.md +++ b/docs/tools/todo/index.md @@ -1,7 +1,7 @@ --- title: "Todo Tool" description: "Task list management for complex multi-step workflows." -permalink: /tools/todo/ +keywords: docker agent, ai agents, tools, todo tool --- # Todo Tool diff --git a/docs/tools/transfer-task/index.md b/docs/tools/transfer-task/index.md index 96e99b9b7a..f5c1ba7d9b 100644 --- a/docs/tools/transfer-task/index.md +++ b/docs/tools/transfer-task/index.md @@ -1,7 +1,7 @@ --- title: "Transfer Task Tool" description: "Delegate tasks to sub-agents in multi-agent setups." -permalink: /tools/transfer-task/ +keywords: docker agent, ai agents, tools, transfer task tool --- # Transfer Task Tool @@ -55,10 +55,7 @@ The `transfer_task` tool takes three parameters: | `task` | string | ✓ | Clear, concise description of the task the sub-agent should achieve. | | `expected_output` | string | ✓ | Description of the result/format the caller expects back. | -The call blocks until the sub-agent returns its result, which becomes the tool's response. For non-blocking parallel delegation, use [`background_agents`]({{ '/tools/background-agents/' | relative_url }}) instead. +The call blocks until the sub-agent returns its result, which becomes the tool's response. For non-blocking parallel delegation, use [`background_agents`](../background-agents/index.md) instead. -
-
See also -
-

For parallel task delegation, see Background Agents. For multi-agent patterns, see Multi-Agent.

-
+> [!TIP] +> **See also**: For parallel task delegation, see [Background Agents](../background-agents/index.md). For multi-agent patterns, see [Multi-Agent](../../concepts/multi-agent/index.md). diff --git a/docs/tools/user-prompt/index.md b/docs/tools/user-prompt/index.md index c56eca9ec5..366732d883 100644 --- a/docs/tools/user-prompt/index.md +++ b/docs/tools/user-prompt/index.md @@ -1,7 +1,7 @@ --- title: "User Prompt Tool" description: "Ask the user questions and collect interactive input during agent execution." -permalink: /tools/user-prompt/ +keywords: docker agent, ai agents, tools, user prompt tool --- # User Prompt Tool @@ -12,16 +12,13 @@ _Ask the user questions and collect interactive input during agent execution._ The user prompt tool allows agents to ask questions and collect input from users during execution. This enables interactive workflows where the agent needs clarification, confirmation, or additional information before proceeding. -
-
When to Use -
- -- When the agent needs clarification before proceeding -- Collecting credentials or configuration values -- Presenting choices and getting user decisions -- Confirming destructive or important actions - -
+> [!NOTE] +> **When to Use**: +> +> - When the agent needs clarification before proceeding +> - Collecting credentials or configuration values +> - Presenting choices and getting user decisions +> - Confirming destructive or important actions ## Configuration @@ -169,11 +166,8 @@ How the prompt appears depends on the interface: - **CLI (exec mode)**: Prints the prompt and reads from stdin - **API/MCP**: Returns an elicitation request to the client -
-
Best Practice -
-

Provide clear, concise messages. Include context about why you're asking and what the information will be used for. Use schemas with descriptions to guide users on expected input format.

-
+> [!TIP] +> **Best Practice**: Provide clear, concise messages. Include context about why you're asking and what the information will be used for. Use schemas with descriptions to guide users on expected input format. ## Handling Responses @@ -183,8 +177,5 @@ The agent should handle all possible actions: - **decline**: Acknowledge and try an alternative approach or explain what's needed - **cancel**: Stop the current operation gracefully -
-
Context Requirement -
-

The user prompt tool requires an elicitation handler to be configured. It works in the TUI and CLI modes but may not be available in all contexts (e.g., some MCP client configurations).

-
+> [!WARNING] +> **Context Requirement**: The user prompt tool requires an elicitation handler to be configured. It works in the TUI and CLI modes but may not be available in all contexts (e.g., some MCP client configurations).