Docker Agent
AI Agent Builder and Runtime by Docker Engineering
Last verified:
What is Docker Agent?
Docker Agent is an open-source framework for building teams of specialized AI agents that collaborate to solve complex problems. Instead of prompting one generalist model, you define agents with specific roles and instructions that work together as a team. You run these agent teams from your terminal using any LLM provider, with Docker Agent managing the coordination between agents.
Key features include multi-agent architecture with hierarchical task delegation and conversation handoffs, a rich tool ecosystem with built-in tools (filesystem, shell, think, todo, memory) plus any MCP server support, and AI provider agnosticism supporting OpenAI, Anthropic, Gemini, AWS Bedrock, Mistral, xAI, and Docker Model Runner for local models. The framework uses declarative YAML configuration files that are versionable and shareable as OCI artifacts to any registry. Advanced capabilities include built-in reasoning tools (think, todo, memory), pluggable RAG with BM25, embeddings, hybrid search and reranking, and the ability to push/pull agent teams like container images.
Docker Agent is designed for developers, DevOps engineers, and AI practitioners who want to build custom AI agent teams without coding. It's included in Docker Desktop 4.63 and later as a CLI plugin, and is available for Docker Engine users via Homebrew, Winget, pre-built binaries from GitHub releases, or building from source. The tool is particularly useful for debugging workflows, coding assistance, research tasks, and any scenario where specialized agents working together outperforms a single generalist agent.
Docker Agent pricing
Pricing model: Freemium
Docker Agent is completely free and open-source under the Apache-2.0 license. It is included pre-installed in Docker Desktop 4.63 and later at no additional cost. For Docker Engine users, it's available via free package managers (Homebrew: brew install docker-agent, Winget: winget install Docker.Agent) or free pre-built binaries from GitHub releases. The only costs are from the LLM provider API calls you make (OpenAI, Anthropic, Gemini, etc.) or you can use Docker Model Runner for completely free local models. There are no paid tiers, subscriptions, or enterprise plans for Docker Agent itself.
Docker Agent pros
- Open-source framework with Apache-2.0 license
- Multi-agent architecture with specialized roles
- Hierarchical task delegation via sub_agents
- Conversation handoffs between peer agents
- Works with any LLM provider (OpenAI, Anthropic, Gemini, AWS Bedrock, Mistral, xAI)
- Supports Docker Model Runner for local models
- Declarative YAML configuration files
- Pre-installed in Docker Desktop 4.63+
- Built-in tools: filesystem, shell, think, todo, memory
- Rich MCP server ecosystem (local, remote, Docker Gateway)
- Push and share agents as OCI artifacts to any registry
- RAG support with BM25, embeddings, hybrid search, reranking
- Code-aware chunking with AST-based parsing for source code
- Alloy models support multiple models in rotation
- Interactive TUI with editable session titles and custom themes
- Response caching to skip model calls for repeated questions
- OpenAI-compatible HTTP server via docker agent serve chat
- No code required to create and run agents
- 10+ builtin hook events including lifecycle and observability events
- Skill model overrides for fork skills
Docker Agent cons
- Requires setting up API keys for LLM providers
- Agents don't share knowledge (each has own context)
- Anonymous usage telemetry collected by default
- only supports OpenAI and Gemini for structured output
- Anthropic thinking budget must be less than max_tokens
- Gemini thinking budget cannot be disabled (minimum 128 tokens)
- Steep learning curve for multi-agent orchestration
- YAML configuration can become complex for large agent teams
- MCP server setup requires additional configuration
- Not included in Docker Desktop versions before 4.49
- Requires Docker CLI plugin installation for Engine users
- Sub-agents increase token consumption and costs
- Limited to Go-based implementation (98.9% Go code)
- Web search requires explicit MCP server configuration
- Debugging multi-agent workflows can be challenging
Frequently asked questions about Docker Agent
What is Docker Agent and how does it differ from Docker's built-in AI assistant?
Docker Agent is an open-source framework for building and running custom agent teams with specialized AI agents that collaborate. It's different from Gordon (docker ai), which is Docker's built-in AI assistant. Docker Agent lets you define your own agents with specific roles in YAML configuration, while Gordon is a pre-built assistant
How do I install Docker Agent?
Docker Agent is included in Docker Desktop 4.63 and later as a pre-installed CLI plugin. For Docker Engine users: use Homebrew (brew install docker-agent), Winget (winget install Docker.Agent), download pre-built binaries from GitHub releases, or build from source. The binary should be copied to ~/.docker/cli-plugins to use 'docker agent' command, or run as standalone 'docker-agent'
What LLM providers does Docker Agent support?
Docker Agent is AI provider agnostic and supports OpenAI, Anthropic, Claude, Gemini, AWS Bedrock, Mistral, xAI, and Docker Model Runner for local models. You set API keys for your provider (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, etc.) or use Docker Model Runner for local models without API keys
How do multi-agent teams work in Docker Agent?
You interact with the root agent, which can delegate work to sub-agents you define. Each agent uses its own model and parameters, has its own context (agents don't share knowledge), and can access built-in tools or MCP servers. The root agent delegates tasks via the transfer_task tool to sub_agents listed in the configuration. Sub-agents can have their own sub-agents for deeper hierarchies
What's the difference between sub_agents and handoffs?
Use sub_agents for hierarchical task delegation where the parent assigns specific tasks and maintains control, receiving results back. Use handoffs for conversation transfer where a new agent takes over completely until someone hands back. Sub_agents work well for structured workflows combining specialist results; handoffs work well when specialists own different parts of an ongoing conversation as peers
What built-in tools are available in Docker Agent?
Built-in tools include filesystem (file operations), shell (command execution), think (reasoning), todo (task management), and memory (persistent storage). All toolsets support common properties like tools whitelist, deferred loading, output compression, environment variables, and usage guidance instructions
How do I share and distribute agent teams?
Agent configurations are packaged as OCI artifacts. You can push and pull them like container images using 'docker agent share push ./debugger.yaml myusername/debugger' and 'docker agent share pull myusername/debugger'. Use Docker Hub or any OCI-compatible registry. Pushing creates the repository if it doesn't exist yet
What is RAG support in Docker Agent?
RAG (Retrieval-Augmented Generation) provides document knowledge bases with pluggable retrieval strategies: chunked-embeddings for semantic search, semantic-embeddings for LLM-enhanced search, BM25 for keyword search, and hybrid retrieval with fusion (RRF, weighted, max). Supports reranking, code-aware chunking with AST-based parsing, and custom vector databases
How do I configure models and their parameters?
Configure models in the 'models' section of your YAML file with provider (openai, anthropic, google, dmr), model name, temperature, max_tokens, top_p, frequency_penalty, presence_penalty, base_url for custom endpoints, parallel_tool_calls, thinking_budget for reasoning depth, and provider_opts for provider-specific options. You can also use alloy models by separating names with commas
What's new in the latest version v1.53.0?
Version v1.53.0 adds 'docker agent serve chat' command exposing agents through an OpenAI-compatible HTTP server, configurable response cache for skipping model calls on repeated questions, skill model override capability for fork skills via model field in SKILL.md frontmatter, g/G keybindings for scrolling messages view, 10 new builtin hook events including lifecycle and observability events, and type: model hook handler for LLM-as-judge functionality