Build a Multi-Agent System in 5 Minutes with cagent

Models are advancing quickly. GPT-5, Claude Sonnet, Gemini. Each release gives us more capabilities. But most real work isn’t solved by a single model.

Developers are realizing they need a system of agents: different types of agents working together to accomplish more complex tasks. For example, a researcher to find information, a writer to summarize, a planner to coordinate, and a reviewer to check accuracy.

The challenge is that today, building a multi-agent system is harder than it should be. Context doesn’t flow cleanly between agents. Tools require custom integration. Sharing with a teammate means sending instructions and hoping they can re-create your setup.

That’s the problem cagent solves.

In this blog, we’ll walk you through the basics, how to create a multi-agent AI system in minutes, and how cagent makes this possible. 

What’s a multi-agent system?

A multi-agent system is a coordinated group of AI agents that collaborate to complete complex tasks. Using cagent, you can build and run these systems declaratively, no complex wiring or reconfiguration needed.

Meet cagent: The best (and open source) way to build multi-agent systems

Figure 1: cagent workflow for multi-agent orchestration. 

cagent is an open-source tool for building agents and a part of Docker’s growing ecosystem of AI tools. 

Instead of writing glue code to wire up models, tools, and workflows, describe an agent (or a team of agents) in a single YAML file:

• Which model the agent uses (OpenAI, Anthropic, Gemini, or a local one)
• What its role or instructions are
• Which tools it can use (like GitHub, search, or the filesystem)
• And, if needed, which sub-agents it delegates to

This turns agents into portable, reproducible artifacts you can run anywhere and share with anyone. 

Multi-agent challenges that cagent is solving

Create, run, and share multi-agent AI systems more easily with cagent.

• Orchestrate agents (and sub-agents) more easily – Define roles and delegation (sub-agents). cagent manages calls and context.
• Let agents use tools with guardrails – Grant capabilities with MCP: search, GitHub, files, databases. Each agent gets only the tools you list and is auditable.
• Use (and swap) models – OpenAI, Anthropic, Gemini, or local models through Docker Model Runner. Swap providers without rewriting your system.
• Treat agents like artifacts – Package, version, and share agents like containers.

How to build a multi-agent system with Docker cagent

Here’s what that looks like in practice.

Step 1: Define your multi-agent system

version: "2"

agents:
 root:
 model: anthropic/claude-sonnet-4-0
 instruction: |
 Break down a user request.
 Ask the researcher to gather facts, then pass them to the writer.
 sub_agents: ["researcher", "writer"]

 researcher:
 model: openai/gpt-5-mini
 description: Agent to research and gather information.
 instruction: Collect sources and return bullet points with links.
 toolsets:
 - type: mcp
 ref: docker:duckduckgo

 writer:
 model: dmr/ai/qwen3
 description: Agent to summarize notes.

 instruction: Write a concise, clear summary from the researcher’s notes.

Step 2: Run the YAML file

cagent run team.yaml

The coordinator delegates, the researcher gathers, and the writer drafts. You now have a functioning team of agents.

Step 3: Share it on Docker Hub

cagent push ./team.yaml org/research-writer

Now, anyone on your team can run the exact same setup with:

cagent run docker.io/org/research-writer

That’s a full multi-agent workflow, built and shared in under 5 minutes.

First principles: Why cagent works

These principles keep cagent an easy-to-use and customizable multi-agent runtime to orchestrate AI agents.

• Declarative > imperative. Multi-agent systems are mostly wiring: roles, tools, and topology. YAML keeps that wiring declarative, making it easy to define, read, and review.
• Agents as artifacts. Agents become portable artifacts you can pull, pin, and trust.
• Small surface area. A thin runtime that does one job well: coordinate agents.

What developers are building with cagent

Developers are already exploring different multi-agent use cases with cagent. Here are some examples:

1. PR and issue triaging

• Collector reads PRs/issues, labels, failing checks
• Writer drafts comments or changelogs
• Coordinator enforces rules, routes edge cases

2. Research summarizing

• Researcher finds and cites sources
• Writer produces a clean summary
• Reviewer checks for hallucinations and tone

3. Knowledge routing

• Router classifies requests
• KB agent queries internal docs
• Redactor strips PII before escalation

Each one starts the same way: a YAML file and an idea. And they can be pushed to a registry and run by anyone.

Get started

cagent gives you the fastest path forward to build multi-agent systems. It’s open-source, easy to use, and built for the way developers already work. Define your agents, run them locally, and share them, all in a few lines of YAML.

YAML in, agents out.

Run the following to get started:

brew install cagent
cagent new
cagent run agent.yaml

Learn more

• Get the technical details from our cagent documentation. 
• We’d love to hear what you think. Join us in the Docker Community Slack. 
• Dive into more topics about AI and Docker. 
• Subscribe to the Docker Navigator Newsletter.