# Docker Agent: Build and Run AI Agents from a YAML File
Building an AI agent from scratch usually involves a lot of setup before the agent can do anything useful. You need an LLM client, a tool execution loop, response parsing, error handling, and orchestration code to keep multiple agents working together.
Docker Agent is designed to remove most of that boilerplate. Docker sums up the idea neatly: "Docker Agent is to AI agents what `docker run` is to containers." Instead of wiring the runtime together yourself, **you define the agent in YAML and let Docker handle the execution layer**.
That means Docker Agent takes care of things like model access, tool calling, and multi-agent orchestration, giving you a much shorter path from an agent definition to something you can actually run.
The project is **open source under Apache 2.0** and comes pre-installed with Docker Desktop 4.49 and later. It supports **OpenAI, Anthropic, Google, xAI, AWS Bedrock, and Mistral**, as well as Docker Model Runner for local inference.
The current release is **v1.149.0**.
## The `agent.yaml` configuration
Everything about an agent, its model, persona, tools, and sub-agents, is declared in a YAML file. No Python, no framework.
```yaml
[label agent.yaml]
agents:
root:
model: openrouter/anthropic/claude-haiku-4-5
description: A helpful assistant
instruction: |
You are a helpful assistant for developers.
Keep your answers short and clear.
toolsets:
- type: filesystem
- type: shell
```
The key fields:
**`model`** points to the LLM powering the agent. The format is `provider/model-id`. You can use `openai/gpt-6-astra`, `anthropic/claude-opus-5-5`, `google/gemini-3-8-flash`, or `dmr/ai/qwen3` for a local model via Docker Model Runner. Switching models is a one-line change.
**`instruction`** is the system prompt. This is where you define the agent's persona, goals, and constraints.
**`toolsets`** are built-in capability bundles. `filesystem` grants read/write file access. `shell` grants terminal command execution. The tool-calling loop, where the LLM decides to call a tool, gets the result, and reasons about the next step, runs automatically. You don't write it.
HCL is also supported as an alternative to YAML if your team prefers it.
## The agent loop Docker Agent handles for you
The standard pattern for building AI agents is the ReAct (Reason, Act) loop: the model reasons about the task, decides to use a tool, calls it, gets the result, reasons again, and repeats until done. Implementing this manually involves parsing LLM responses to detect tool calls, executing tools securely, formatting results to send back, and handling failures at each step.
Docker Agent runs this loop automatically. When you execute `docker agent run`, it manages the back-and-forth between the model and its tools. Docker's own documentation shows this replacing dozens of lines of Python with an 8-line YAML file.
## The three design principles
**Configuration as code.** Because agents live in YAML files, they can be version-controlled like any other code. Changes to prompts, models, or tool grants can go through pull requests. A/B testing two models is a one-line edit and a re-run.
**Seamless distribution.** Agents can be pushed to any OCI-compliant registry with `docker agent share push ./agent.yaml myorg/my-agent:v1` and pulled and run anywhere with `docker agent run myorg/my-agent:v1`. The exact model, instructions, and tools travel with the configuration.
**Agents as services.** The `docker agent serve` command exposes an agent in three modes: as an HTTP API, as an MCP server for connecting external tools, or as an A2A (Agent-to-Agent) server. The A2A mode is what enables multi-agent systems.
## Installation and your first agent
Docker Agent is pre-installed in Docker Desktop 4.49+. Verify:
```command
docker agent version
```
For Linux or older desktop versions, install the plugin:
```command
curl -fsSL https://get.docker.com/docker-agent | sh
```
Create `agent.yaml` with a minimal configuration:
```yaml
[label agent.yaml]
agents:
root:
model: anthropic/claude-haiku-5-5
description: A developer assistant
instruction: |
You are a helpful developer assistant.
Keep your answers short and clear.
toolsets:
- type: filesystem
- type: shell
```
Run it:
```command
docker agent run agent.yaml
```
This opens an interactive TUI. Ask it to list the current directory or read a file and it will use the filesystem tool to do so. To pass a prompt directly without the TUI:
```command
docker agent run --exec agent.yaml "List all TypeScript files in this directory"
```
## Practical example: multi-agent incident response
The real value of Docker Agent is multi-agent workflows. A debugging example with two specialized agents illustrates the security model.
**The `log_analyst` agent** has read-only access to `/logs`. It can read application logs and nothing else.
**The `on_call` agent** has no filesystem access at all. Its only tool is the ability to delegate to `log_analyst` over the A2A protocol.
```yaml
[label team.yaml]
agents:
log_analyst:
model: anthropic/claude-haiku-5-5
instruction: |
You are a log analysis specialist.
Read log files to identify root causes of incidents.
Report findings clearly with timestamps and evidence.
toolsets:
- type: filesystem
read_only: true
paths:
- /logs
on_call:
model: anthropic/claude-opus-5-5
instruction: |
You are an on-call engineer assistant.
Delegate log analysis to the log_analyst agent.
Present findings as a structured incident summary.
toolsets:
- type: a2a
url: http://127.0.0.1:8080
```
Start the `log_analyst` as an A2A service in one terminal:
```command
docker agent serve a2a team.yaml --agent log_analyst --listen 127.0.0.1:8080
```
Query through `on_call` in a second terminal:
```command
docker agent run --exec team.yaml --agent on_call \
"Why has checkout been throwing 500s since around 2 p.m.?"
```
What happens: the `on_call` agent receives the question and delegates to `log_analyst` via A2A. The `log_analyst` reads the relevant logs, finds that a deployment at 13:58 changed a payment timeout from 5000ms to 2000ms, and returns a structured finding. The `on_call` agent formats this into an incident summary with cause, impact, and a suggested next step.
The security design is deliberate: the agent that can access sensitive log data is isolated and read-only. The agent the engineer interacts with has no direct data access. A compromised `on_call` agent can only ask `log_analyst` for information, not access files directly.
## Multi-model Battleship
To demonstrate multi-agent coordination with a concrete, observable output, the source article runs a Battleship game with three agents: GPT-6 Luna as one player (A2A on port 8080), Claude Haiku 5.5 as the other (A2A on port 8081), and Kimi K3 as a neutral referee managing game state and calling each player for their moves.
Each turn, the referee sends the current board state to the active player via A2A and receives a coordinate and a line of trash talk in return. The game ran to completion without human intervention. Claude Haiku won in 34 shots at 50% accuracy. The example is illustrative rather than a meaningful benchmark, but it demonstrates that multi-agent coordination via A2A works across different model providers without any custom integration code.
## What to know before using it
A2A support is functional but still evolving. Tool calls are handled internally and not exposed as separate A2A events. A2A artifact support and memory features have limited integration. Multi-agent scenarios with sub-agents need further work. Check the [Docker Agent documentation](https://docs.docker.com/ai/docker-agent/) for the current state of each feature before building production workflows on it.
The agent catalog at [hub.docker.com/catalogs/agents](https://hub.docker.com/catalogs/agents) has pre-built agents for common tasks that can be run directly or used as references for building your own.