docker-agent Examples

May 7, 2026 · View on GitHub

This directory is a curated catalog of working agent configurations. Each example demonstrates one or more features of docker-agent and is meant to be read as documentation as well as run as-is.

Running an example

Most files have a shebang line and are directly executable, but the canonical way to run any of them is:

$ docker agent run examples/<name>.yaml

Add -c <command> to invoke one of the agent's commands, --exec to skip the TUI, or -a <agent> to run a specific agent from a multi-agent file. A handful of examples (e.g. tic-tac-toe.yaml, elicitation/, eval/) ship a small README of their own with extra setup instructions — read those before running.

Most agents need API keys for at least one provider (OpenAI, Anthropic, Google, Mistral, Nebius, Groq, GitHub Models, Bedrock, …). Set the matching environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, …) before running, or wire the agent to a key your gateway/proxy already holds.

The rest of this document groups examples by what feature they showcase. If you are looking for inspiration to build a real agent, jump to Real-world agents.

Getting started — minimal agents

The smallest possible configurations. Read these first to learn the YAML shape: an agents.root block with at least a model, a description, and an instruction.

File	What it shows
`basic_agent.yaml`	The bare minimum: model + instruction, no tools.
`echo-agent.yaml`	Same shape with an explicit `models:` block and zero temperature.
`pirate.yaml` / `pirate.hcl`	Persona-only agent in YAML and the equivalent HCL form.
`haiku.yaml`	Writes haikus.
`42.yaml`	Douglas-Adams-style witty assistant.
`contradict.yaml`	Contrarian.
`silvia.yaml`	Sylvia-Plath-inspired poet.
`mistral.yaml`	Tiny agent pinned to a Mistral model.
`pokemon.yaml`	French-speaking Pokémon expert with two trainer sub-agents.
`alloy.yaml`	Learning assistant.
`dmr.yaml`	Pirate served by a local Docker Model Runner endpoint.
`welcome_message.yaml`	Adds a `welcome_message` shown by the TUI.
`instructions_from_file.hcl` + `instructions_from_file.md`	Loads the system instruction from an external file via `${file(...)}`.
`gopher.yaml` / `gopher.hcl`	Same agent in YAML and HCL.

Built-in toolsets

Examples that wire up one of the toolsets shipped with docker-agent (filesystem, shell, todo, think, memory, fetch, script, user_prompt, api, openapi, rag, model_picker, …).

Filesystem & shell

File	What it shows
`shell.yaml`	Plain `shell` toolset.
`filesystem.yaml`	Plain `filesystem` toolset.
`filesystem_allow_deny.yaml`	Restricting the filesystem tool with allow/deny path lists.
`script_shell.yaml`	Defining custom shell commands as named tools via `type: script`.
`pythonista.yaml`	Python tutor with filesystem + shell.
`diag.yaml`	Log analysis using filesystem + shell + `think`.
`typo.yaml`	Restricts a `filesystem` toolset to a subset of tools and exposes them as a `fix` command.
`toolset-working-dir.yaml`	Setting a `working_dir` for MCP/LSP toolsets.
`post_edit.yaml`	Auto-runs `gofmt -w` on every `.go` file the agent edits via `filesystem.post_edit`.
`sandbox_agent.yaml`	Same shell-based agent run with `--sandbox` to confine commands to a Docker container.
`deferred.yaml`	Wraps the agent in a deferred-execution container (`runtime: deferred`).

Memory, todo, think, cache

File	What it shows
`mem.yaml`	Persistent memory via the `memory` toolset (SQLite-backed).
`todo.yaml`	Task manager built on the `todo` toolset.
`shared-todo.yaml`	Multiple agents sharing the same todo list.
`cached_responses.yaml`	Caching final answers in JSON so repeated questions don't hit the model.

Web & API access

File	What it shows
`fetch_docker.yaml`	Uses the built-in `fetch` toolset to summarize a web page.
`fetch_headers.yaml`	Adding custom HTTP headers (e.g. `Authorization`) to `fetch`.
`fetch_domain_filtering.yaml`	Restricting `fetch` to an allow-list of domains.
`api-tool.yaml`	Defines a single REST endpoint as a typed tool via `type: api`.
`openapi-petstore.yaml`	Generates one tool per endpoint from a public OpenAPI spec.
`bio.yaml`	Biographer driven by DuckDuckGo + fetch.
`search.yaml`	Web research powered by Brave + fetch.
`librarian.yaml`	Documentation researcher using context7 + DuckDuckGo + fetch.

RAG (Retrieval-Augmented Generation)

File	What it shows
`rag.yaml`	End-to-end example with a chunked-embeddings index over local docs.
`rag/bm25.yaml`	Lexical BM25 strategy.
`rag/semantic_embeddings.yaml`	Pure semantic-embeddings strategy.
`rag/hybrid.yaml`	Hybrid BM25 + embeddings retrieval.
`rag/reranking.yaml`	Hybrid retrieval with a re-ranking model on top.
`rag/custom_provider.yaml`	Pointing the embeddings model at a custom OpenAI-compatible provider.

MCP — Model Context Protocol

docker-agent speaks MCP natively. These examples cover everything from referencing a single Docker MCP server to wiring up the full MCP Toolkit and remote MCP endpoints.

Local & catalog MCP servers

File	What it shows
`apify.yaml`	Single MCP server (`docker:apify`).
`airbnb.yaml`	Airbnb search via the openbnb MCP server.
`moby.yaml`	Project expert backed by `gitmcp.io/moby/moby`.
`couchbase_agent.yaml`	Database commands through the Couchbase MCP server.
`github.yaml`	GitHub assistance via `docker:github-official`.
`github_issue_manager.yaml`	Same MCP, scoped to issue-management tools.
`github-toon.yaml`	GitHub MCP with the TOON compact tool format.
`mcp_generator.yaml`	Researches and emits new MCP server configurations.
`k8s_debugger.yaml`	Kubernetes triage with the Inspektor-Gadget + kubernetes MCP servers.
`mcp-toolkit.yaml`	Discovering and enabling servers from the Docker MCP Toolkit.
`mcp-definitions.yaml`	Top-level `mcps:` block: define a server once, reference it from many agents.
`podcastgenerator_githubmodel.yaml`	Multi-agent podcast pipeline using GitHub Models + DuckDuckGo + filesystem MCPs.
`dhi/dhi.yaml`	Migrates Dockerfiles to Docker Hardened Images.

Remote MCP & transports

File	What it shows
`notion-expert.yaml`	Remote MCP server with OAuth Dynamic Client Registration.
`remote_mcp_oauth.yaml`	Remote MCP server with explicit OAuth credentials (Slack/GitHub-style).
`remote_mcp_oauth_callback_redirect.yaml`	OAuth flow with a public redirect URL bouncing back to localhost.
`websocket_transport.yaml`	OpenAI Responses API streaming over WebSocket instead of SSE.
`ha.yaml`	Home Assistant via remote MCP (streamable HTTP).
`elicitation/`	Demo MCP server that asks the user for structured input mid-call (forms, confirmations, enums).

Multi-agent setups

Coordinator + sub-agents (in-process)

File	What it shows
`blog.yaml`	Technical blog pipeline (researcher → writer → reviewer).
`writer.yaml`	Story writing supervisor with specialized sub-agents.
`finance.yaml`	Financial research orchestrating analysts.
`background_agents.yaml`	Parallel research delegated to background sub-agents.
`dev-team.yaml`	Product-manager-led team (designer + engineer) with shared memory.
`multi-code.yaml`	Tech-lead routing tasks to a frontend and a Go expert.
`coder.yaml`	Coding agent with planner, implementer, and librarian sub-agents.
`pr-reviewer-bedrock.yaml`	PR review toolkit pinned to Bedrock models.
`professional/professional_writing_agent.yaml`	English editor + French translator team.
`handoff.yaml`	Strict handoff (`type: handoff`) between specialists.

Catalog sub-agents

File	What it shows
`sub-agents-from-catalog.yaml`	Mixes locally-defined sub-agents with ones pulled from an OCI catalog (e.g. `agentcatalog/pirate`).

Inter-agent protocols (A2A & MCP)

File	What it shows
`tic-tac-toe.yaml`	Game-master + two players communicating over A2A.
`tic-tac-toe-mcp.yaml`	Same demo, players exposed as MCP servers instead.

Models, providers & routing

File	What it shows
`custom_provider.yaml`	Talking to any OpenAI-compatible endpoint via a custom provider.
`compose-secrets.yaml`	Reading API keys from Docker Compose / Swarm secrets.
`env_placeholders.yaml`	`${ENV_VAR}` substitution inside the YAML.
`nebius.yaml`	Nebius cloud provider.
`grok.yaml`	xAI Grok model.
`github-copilot.yaml`	GitHub Copilot models via OAuth device-flow.
`fallback_models.yaml`	Automatic fallback to a secondary model when the primary fails.
`model_picker.yaml`	Lets the agent itself swap to a stronger model mid-conversation.
`per_tool_model_routing.yaml`	Use a cheap/fast model to interpret tool results, the primary model for reasoning.
`rule_based_routing.yaml`	Cheap router model dispatches the user message to fast or capable models.
`structured-output.yaml`	Forces the model to return JSON matching a schema.
`google_search_grounding.yaml`	Enables Google Search grounding on Gemini models.
`sampling-opts.yaml`	Provider-specific sampling parameters (`top_k`, `repetition_penalty`, …).
`thinking_budget.yaml`	Reasoning/thinking budgets across OpenAI, Anthropic and Google.
`task_budget.yaml`	Anthropic `task_budget`: cap total tokens spent across a multi-step agentic task.

Permissions, redaction & sandboxing

File	What it shows
`permissions.yaml`	Top-level `permissions` block with `allow`/`deny` patterns for tool calls.
`llm_judge.yaml`	Layered defense: deterministic permissions + an LLM-as-judge `pre_tool_use` hook + user prompts.
`redact_secrets.yaml`	Single-flag (`redact_secrets: true`) scrubbing of detected secrets in args, chat content, and tool output.
`redact_secrets_hooks.yaml`	The same scrubbing wired manually as three hooks.
`sandbox_agent.yaml`	Running tools inside a Docker sandbox via `docker agent run --sandbox`.
`filesystem_allow_deny.yaml`	Path-level allow/deny for the filesystem toolset.

Hooks & toolset lifecycle

File	What it shows
`hooks.yaml`	Comprehensive tour of every hook event (`pre_tool_use`, `post_tool_use`, `before_llm_call`, `after_llm_call`, `transform`, `notification`, `session_*`, …).
`unload_on_switch.yaml`	`on_agent_switch` builtin (`command: unload`) that unloads the previous agent's models (DMR `_unload`) so two heavy local models can share a single GPU.
`lifecycle.yaml`	Per-toolset lifecycle policies (`strict`, `resilient`, `best-effort`) and restart/back-off tuning.
`post_edit.yaml`	Filesystem `post_edit` actions running after every file edit.

Code-mode, skills & runtime knobs

File	What it shows
`code_mode.yaml`	`code_mode_tools: true` lets the model script multi-step tool calls in code instead of one-shot calls.
`skills_filter.yaml`	Restricts which discovered skills the agent is allowed to expose.
`toolset_instructions.yaml`	Augmenting a toolset's default instructions with `{ORIGINAL_INSTRUCTIONS}`.

Real-world agents

Larger, opinionated agents you can use as starting points for your own projects.

File	What it does
`code.yaml`	Code analysis + modification + validation loop.
`coder.yaml`	Coding agent with planner and librarian sub-agents.
`multi-code.yaml`	Tech-lead routing between web and Go specialists.
`gopher.yaml` / `gopher.hcl`	Go-specialist coding agent.
`go_packages.yaml`	Expert in the Go module ecosystem.
`modernize-go-tests.yaml`	Mass-modernizes Go test suites to recent Go idioms.
`pr-reviewer-bedrock.yaml`	PR reviewer pinned to Bedrock.
`review.yaml`	Dockerfile review specialist.
`doc_generator.yaml`	Generates documentation from a codebase.
`image_text_extractor.yaml`	OCR-ish extractor for text in images.
`dhi/dhi.yaml`	Migrates Dockerfiles to Docker Hardened Images.
`k8s_debugger.yaml`	Kubernetes incident triage.

Evaluation

File	What it shows
`eval/`	Saved sessions plus the agent under test, runnable with `docker agent eval demo.yaml ./evals`.

Embedding docker-agent in Go programs

Code samples that import the docker-agent Go packages directly.

Path	What it shows
`golibrary/simple/`	Single agent, single message.
`golibrary/multi/`	Two agents with a `transfer_task` hand-off.
`golibrary/tool/`	Registering a custom Go-defined tool.
`golibrary/builtintool/`	Wiring up a built-in toolset (`shell`) from Go.
`golibrary/stream/`	Consuming the runtime's streaming events (`RunStream`).
`chat/`	Tiny OpenAI-SDK client that talks to `docker agent serve chat` — proves any OpenAI-compatible client works against a docker-agent.

Conventions

YAML is the recommended format. HCL is also supported (*.hcl); the pirate.{yaml,hcl}, gopher.{yaml,hcl} and instructions_from_file.hcl pairs show equivalent agents in both formats.
Every example references the JSON schema at agent-schema.json — point your editor at it for autocomplete and validation.
Examples target the latest schema version. Older config versions live under pkg/config/v0, v1, … and are intentionally frozen; new features only land on the latest version.