Imagine asking an AI assistant to review a large codebase.
It needs to inspect the project structure, identify potential bugs, examine security vulnerabilities, and explain its findings. You could build a custom application using Python or Node.js, connect an LLM API, implement tool calling, manage conversations, and write the orchestration logic.
Now imagine splitting that work between specialist AI agents, with one coordinating the entire process.
This is exactly the kind of problem Docker Agent is designed to solve.
Docker has introduced an open-source agent runtime that lets developers define, run, coordinate, and share AI agents using YAML or HCL configuration files.
You can connect different LLM providers, give agents access to tools, integrate MCP servers, and create teams of agents without building the orchestration infrastructure yourself.
Let’s understand how it works and build a practical multi-agent code review system.
1. What is Docker Agent?
Docker Agent is an open-source framework and runtime developed by Docker for building and running AI agents.
Its primary idea is straightforward: describe your agent in a configuration file, specify its model, instructions, tools, and other agents it can delegate work to, then run it through the Docker Agent CLI.
For example:
agents:
root:
model: openai/gpt-5-mini
description: A helpful AI assistant
instruction: |
You are a knowledgeable assistant.
Help users with technical questions.Run it:
docker agent run agent.yamlDocker Agent takes care of the agent execution loop, model communication, tool execution, and delegation between agents.
You can use multiple LLM providers, including OpenAI, Anthropic, Google Gemini, AWS Bedrock, and local models through Docker Model Runner.
One important distinction: Docker Agent is an agent runtime, not a new LLM or a container image that automatically runs your entire agent inside a container. It can package and distribute agent configurations using OCI registries, while Docker-based isolation is available through separate sandbox functionality.
Also, Docker Agent is different from Docker Gordon (docker ai), Docker's built-in AI assistant.
2. How does Docker Agent work?
Think of Docker Agent as the execution layer between an LLM and the tools it needs.
The process looks like this:
Here is what happens internally:
You define agents, models, instructions, and tools in YAML or HCL.
You launch an agent using the CLI.
The LLM decides whether to respond directly, call a tool, or delegate a task.
Docker Agent executes the requested operation and returns its result to the agent.
The agent continues processing until it can provide a response.
The runtime streams results back through its terminal interface or supported APIs.
Understanding the main building blocks
You can configure these components independently and reuse them across different agents.
3. Built-in tools and MCP integration
An LLM on its own cannot inspect your local files, run terminal commands, or communicate with external services.
It needs tools.
Docker Agent comes with several built-in toolsets.
You enable a toolset by adding it to an agent’s configuration.
For example:
toolsets:
- type: filesystem
- type: shell
- type: thinkConnecting external tools through MCP
Docker Agent also supports the Model Context Protocol (MCP).
This means you can connect external MCP servers without implementing individual integrations yourself.
For example, adding DuckDuckGo search:
toolsets:
- type: mcp
ref: docker:duckduckgoDocker MCP runs the MCP server in a container through the MCP Gateway. Docker Agent also supports local MCP servers using standard input/output and remote MCP servers using supported HTTP transports.
This gives developers access to an ecosystem of external tools.
4. Build a multi-agent code review system
Let’s build something practical.
We will create a code review team that examines a software repository.
Our team has three agents:
Root agent: Coordinates the review and prepares the final report.
Bug hunter: Identifies correctness problems and edge cases.
Security reviewer: Looks for security vulnerabilities.
The root agent delegates work to the specialists and combines their findings.
Step 1: Install Docker Agent
Docker Agent is included in Docker Desktop 4.63 and later.
For macOS or Linux users who prefer a standalone installation:
brew install docker-agentVerify the installation:
docker-agent versionDocker Desktop users can use:
docker agent versionOlder Docker Desktop releases between 4.49 and 4.62 referred to this functionality as cagent.
Step 2: Configure your LLM provider
For this example, we will use OpenAI models.
Set your API key:
export OPENAI_API_KEY="your-api-key"Docker Agent reads provider credentials from environment variables. Keep API keys out of your YAML configuration files.
Step 3: Create the agent configuration
Create a file called review-team.yaml in your project directory.
agents:
root:
model: openai/gpt-5-mini
description: Coordinates the code review process.
instruction: |
You are a senior software engineering reviewer.
Inspect the repository and coordinate a thorough
code review.
Delegate correctness analysis to bug_hunter.
Delegate security analysis to security_reviewer.
Collect both reports and consolidate their findings.
Remove duplicate findings.
Every finding must contain:
- Severity
- File path and line numbers
- Evidence
- Potential impact
- Recommended fix
Do not modify any files.
Do not report speculative problems as confirmed bugs.
sub_agents:
- bug_hunter
- security_reviewer
toolsets:
- type: filesystem
- type: think
bug_hunter:
model: openai/gpt-5
description: Identifies correctness bugs and edge cases.
instruction: |
You are an experienced software engineer.
Inspect the repository for:
- Logic errors
- Incorrect error handling
- Edge cases
- Async and concurrency problems
- Potential performance issues
Report only findings supported by code evidence.
toolsets:
- type: filesystem
security_reviewer:
model: openai/gpt-5
description: Reviews application security.
instruction: |
You are an application security reviewer.
Examine the repository for:
- Authentication and authorization weaknesses
- Injection vulnerabilities
- Insecure data handling
- Exposed secrets
- Input validation problems
- Unsafe dependency usage
Prioritize exploitable issues.
Provide evidence and recommended fixes.
toolsets:
- type: filesystem
# Restrict this example to read-only operations.
permissions:
allow:
- "read_file"
- "read_multiple_files"
- "list_directory"
- "directory_tree"
- "search_files_content"
deny:
- "write_file"
- "edit_file"
- "shell"The root agent has two sub-agents. Docker Agent automatically provides the transfer_task capability when an agent has sub_agents configured.
Each specialist has its own model, instructions, and tools. The root agent receives the specialists’ results and prepares the final response.
We have also added permissions to block file modifications and shell execution. This makes the example suitable for a read-only code review.
💡 Enjoying this article?
Every week day, I publish practical, production-ready deep dives covering Web development, System Design, Open source projects, Tech industry trends and AI Engineering and tools.
Step 4: Run your agent
docker agent run review-team.yamldocker-agent run review-team.yamlGive it a task:
Review this repository for correctness and security issues.
Inspect the source code and identify high-impact problems.
Provide the severity, file path, line numbers,
evidence, and recommended fixes.
Do not modify any files.You can also run the agent without the interactive terminal:
docker agent run --exec review-team.yaml \
"Review this repository for correctness and security issues."The --exec option is useful when integrating agents into scripts and automated workflows.
5. What makes multi-agent orchestration interesting?
Docker Agent supports two particularly useful patterns.
Delegation
An agent can delegate a task to a specialist using sub_agents.
For example:
Root Agent
|
+---- Bug Hunter
|
+---- Security Reviewer
|
+---- Test EngineerThe parent agent sends a task to a child agent, waits for its result, and continues processing.
Each sub-agent runs in its own sub-session and receives a task description. Agents do not automatically share their entire context. The parent must provide enough information for the specialist to complete its work.
Handoffs
Handoffs are useful when the entire conversation needs to move between agents.
Consider a documentation workflow:
Researcher
|
v
Technical Writer
|
v
ReviewerEach agent becomes the active agent and continues working with the conversation history.
Use delegation when a coordinator needs specialist results. Use handoffs when the conversation should move through a defined workflow.
Docker Agent also supports background agents for running independent tasks concurrently.
One feature worth paying attention to is agent distribution.
Docker Agent supports packaging agent configurations as OCI artifacts.
That means you can push an agent configuration to an OCI-compatible registry and share it with other developers.
Instead of asking everyone to manually recreate the same configuration, your team can pull and run the shared agent:
docker agent run myorg/code-reviewer:latestThis is useful when an engineering team wants a consistent code review agent across multiple repositories.
You can maintain the configuration centrally and distribute it through familiar registry workflows.
7. Where can developers use Docker Agent?
The architecture works well beyond code review.
You can also expose agents through HTTP APIs, MCP servers, or the Agent-to-Agent (A2A) protocol.
For example, exposing an agent through an HTTP API:
docker agent serve api review-team.yaml \
--listen 127.0.0.1:8080This lets an application or CI/CD workflow communicate with your agent programmatically.
8. Limitations and things developers should consider
Docker Agent simplifies agent orchestration, but some engineering decisions remain yours.
Model costs and latency: Every agent invocation can involve additional model requests. Delegation may improve task specialization while increasing execution time and API costs.
Context management: Sub-agents receive their own task contexts. Poor delegation instructions can lead to incomplete results or duplicated work.
Tool permissions: Filesystem and shell access can have consequences. Keep tool permissions narrow and review third-party agent configurations before executing them.
Security isolation: Permission rules help control tool execution, but Docker documents them as client-side controls rather than a security boundary for untrusted agents. For stronger isolation, Docker Agent supports sandbox mode, which runs the agent inside a disposable sandbox VM. The working directory is still mounted into that environment, so consider what files you expose.
When configuration is insufficient: YAML is convenient for defining agents, but applications with complex business logic or highly dynamic orchestration may still need custom application code.
These trade-offs matter when moving from a local experiment to an agent used by an engineering team.
Conclusion
Docker Agent gives developers a practical way to define and run AI agents without implementing the entire orchestration layer themselves.
Its YAML-based configuration, model flexibility, built-in tools, MCP integration, multi-agent delegation, and OCI distribution make it worth exploring.
For developers building AI-powered applications, I would start with a small coding assistant or code review agent. Add a specialist only when the task genuinely benefits from a separate role.
That approach makes it easier to understand where delegation helps, how much additional model usage it introduces, and which tools an agent actually needs.
References and further reading
Thank You for Reading!
I hope you found it helpful and informative. If you have any questions or feedback, feel free to leave a comment below. Your support and engagement mean a lot to me.
