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.

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:

docker agent version

For Linux or older desktop versions, install the plugin:

curl -fsSL https://get.docker.com/docker-agent | sh

Create agent.yaml with a minimal configuration:

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:

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:

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.

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:

docker agent serve a2a team.yaml --agent log_analyst --listen 127.0.0.1:8080

Query through on_call in a second terminal:

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 for the current state of each feature before building production workflows on it.

The agent catalog at 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.

Got an article suggestion? Let us know

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.