Getting Started with Docker cagent: Build AI Agent Teams Without Writing Code

If you've been following Docker's AI tooling evolution, you've probably noticed a pattern — Docker keeps making complex things simpler to run, share, and deploy. cagent is their latest move in that direction, but this time squarely in the AI agent space.

What is Docker cagent?

cagent (currently experimental) is an open source tool from Docker Engineering that lets you build and run teams of specialized AI agents — defined entirely in YAML, with no code required. Instead of relying on a single generalist model to handle everything, cagent lets you split complex work across multiple focused agents, each with its own role, instructions, and even its own LLM model.

Think of it as container orchestration, but for AI agents. You define who does what, and cagent handles the coordination.

The GitHub repository describes it simply: "Define agents in YAML, run them from your terminal using any LLM provider."

Why Agent Teams Instead of One Agent?

Here's the problem with single-agent setups — when you throw a complex task at one model, it constantly context-switches between investigation, planning, writing, and execution. That leads to mediocre results across the board.

cagent's answer is specialization. A root agent receives your task and delegates subtasks to sub-agents, each of which stays focused on its specialty. The root agent manages coordination; sub-agents go deep on execution. Agents don't share context with each other, which keeps them clean and focused.

A Real Example: Bug Debugger Agent Team

Here's a two-agent debugging team straight from the official docs:

agents: root: model: openai/gpt-4o-mini description: Bug investigator instruction: | Analyze error messages, stack traces, and code to find bug root causes. Explain what's wrong and why it's happening. Delegate fix implementation to the fixer agent. sub_agents: [fixer] toolsets: - type: filesystem - type: mcp ref: docker:duckduckgo fixer: model: anthropic/claude-sonnet-4-5 description: Fix implementer instruction: | Write fixes for bugs diagnosed by the investigator. Make minimal, targeted changes and add tests to prevent regression. toolsets: - type: filesystem - type: shell

Notice a few things here. The root agent uses OpenAI to investigate, while the fixer uses Claude for implementation — you can mix LLM providers freely within a single agent team. Each agent also has access to different tools: filesystem access, shell execution, and even web search via Docker's MCP Gateway.

Installation

cagent ships with Docker Desktop 4.49 and later — so if you're already updated, you already have it.

For Docker Engine users, you have three options:

# macOS / Linux brew install cagent # Windows winget install Docker.Cagent

Or grab pre-built binaries directly from the GitHub releases page.

Running Your First Agent Team

1. Export your API key for whichever LLM provider you want to use:

export ANTHROPIC_API_KEY=<your_key> # For Claude export OPENAI_API_KEY=<your_key> # For OpenAI export GOOGLE_API_KEY=<your_key> # For Gemini

2. Save your agent config as debugger.yaml

3. Run it:

cagent run debugger.yaml

You'll get an interactive prompt where you describe a bug or paste an error. The investigator agent analyzes it, then hands off to the fixer for implementation.

Sharing Agent Teams via Docker Hub

This is where cagent gets genuinely clever. Agent configurations are packaged as OCI artifacts — the same format as container images — so you can push and pull them via Docker Hub or any OCI-compatible registry:

cagent push ./debugger.yaml myusername/debugger cagent pull myusername/debugger

This means the same distribution model you already use for containers now works for AI agent teams. Version them, share them with your team, publish them publicly. The mental model is immediately familiar if you already know Docker.

Key Concepts to Remember

Root agent — the entry point that receives your input and delegates work downward via sub_agents.

Sub-agents — specialized agents focused on specific tasks; can themselves have sub-agents for deeper hierarchies.

Toolsets — built-in capabilities like filesystem access, shell execution, and memory, plus external tools via MCP servers.

MCP integration — cagent connects natively to Docker's MCP Gateway, giving agents access to a growing catalog of external tools like web search, databases, and APIs.

Who Should Pay Attention to This?

If you're already in the Docker ecosystem and starting to explore agentic AI workflows, cagent is worth experimenting with today. It removes the need to write orchestration code from scratch, keeps your agent configs version-controllable and shareable, and supports multi-provider setups out of the box.

Given that it's currently experimental, the API will evolve — but the core concept of YAML-defined, Docker-distributed agent teams is solid, and the MCP integration gives it a strong foundation.

The official docs are at docs.docker.com/ai/cagent and the source is open at github.com/docker/cagent.

This article is based on Docker's official documentation as of February 2026.