Skip to content

Cagent docs #23786

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Cagent docs #23786

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bd35d68
Cagent docs
rumpl Nov 28, 2025
8c03e9d
Add one guide, not great but...
rumpl Nov 28, 2025
8c6513f
vale: add toolsets, reranking to vocabulary
dvdksn Dec 1, 2025
78f5efd
cagent: big rewrite
dvdksn Dec 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions _vale/config/vocabularies/Docker/accept.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -290,4 +290,6 @@ Zsh
[Vv]irtiofs
[Vv]irtualize
[Ww]alkthrough
[Tt]oolsets?
[Rr]erank(ing|ed)?

290 changes: 101 additions & 189 deletions content/manuals/ai/cagent/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,236 +5,148 @@ weight: 60
params:
sidebar:
group: Open source
badge:
color: violet
text: Experimental
keywords: [ai, agent, cagent]
---

{{< summary-bar feature_name="cagent" >}}

[cagent](https://github.com/docker/cagent) lets you build, orchestrate, and share
AI agents. You can use it to define AI agents that work as a team.
[cagent](https://github.com/docker/cagent) is an open source tool for building
teams of specialized AI agents. Instead of prompting one generalist model, you
define agents with specific roles and instructions that collaborate to solve
problems. Run these agent teams from your terminal using any LLM provider.

cagent relies on the concept of a _root agent_ that acts as a team lead and
delegates tasks to the sub-agents you define.
Each agent:
- uses the model of your choice, with the parameters of your choice.
- has access to the [built-in tools](#built-in-tools) and MCP servers
configured in the [Docker MCP gateway](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md).
- works in its own context. They do not share knowledge.
## Why agent teams

The root agent is your main contact point. Each agent has its own context,
they don't share knowledge.
One agent handling complex work means constant context-switching. Split the
work across focused agents instead - each handles what it's best at. cagent
manages the coordination.

## Key features
Here's a two-agent team that debugs problems:

- ️Multi-tenant architecture with client isolation and session management.
- Rich tool ecosystem via Model Context Protocol (MCP) integration.
- Hierarchical agent system with intelligent task delegation.
- Multiple interfaces including CLI, TUI, API server, and MCP server.
- Agent distribution via Docker registry integration.
- Security-first design with proper client scoping and resource isolation.
- Event-driven streaming for real-time interactions.
- Multi-model support (OpenAI, Anthropic, Gemini, DMR, Docker AI Gateway).

## Get started with cagent

1. The easiest way to get cagent is to [install Docker Desktop version 4.49 or later](/manuals/desktop/release-notes.md) for your operating system.

> [!NOTE]
> You can also build cagent from the source. For more information, see the [cagent GitHub repository](https://github.com/docker/cagent?tab=readme-ov-file#build-from-source).

1. Set the following environment variables:

```bash
export OPENAI_API_KEY=<your_api_key_here> # For OpenAI models
export ANTHROPIC_API_KEY=<your_api_key_here> # For Anthropic models
export GOOGLE_API_KEY=<your_api_key_here> # For Gemini models
```

1. Create an agent by saving this sample as `assistant.yaml`:

```yaml {title="assistant.yaml"}
agents:
root:
model: openai/gpt-5-mini
description: A helpful AI assistant
instruction: |
You are a knowledgeable assistant that helps users with various tasks.
Be helpful, accurate, and concise in your responses.
```

1. Start your prompt with your agent:

```bash
cagent run assistant.yaml
```

## Create an agentic team

You can use AI prompting to generate a team of agents with the `cagent new`
command:

```console
$ cagent new

For any feedback, visit: https://docker.qualtrics.com/jfe/form/SV_cNsCIg92nQemlfw

Welcome to cagent! (Ctrl+C to exit)

What should your agent/agent team do? (describe its purpose):

> I need a cross-functional feature team. The team owns a specific product
feature end-to-end. Include the key responsibilities of each of the roles
involved (engineers, designer, product manager, QA). Keep the description
short, clear, and focused on how this team delivers value to users and the business.
```

Alternatively, you can write your configuration file manually. For example:

```yaml {title="agentic-team.yaml"}
```yaml
agents:
root:
model: claude
description: "Main coordinator agent that delegates tasks and manages workflow"
model: openai/gpt-5-mini # Change to the model that you want to use
description: Bug investigator
instruction: |
You are the root coordinator agent. Your job is to:
1. Understand user requests and break them down into manageable tasks.
2. Delegate appropriate tasks to your helper agent.
3. Coordinate responses and ensure tasks are completed properly.
4. Provide final responses to the user.
When you receive a request, analyze what needs to be done and decide whether to:
- Handle it yourself if it's simple.
- Delegate to the helper agent if it requires specific assistance.
- Break complex requests into multiple sub-tasks.
sub_agents: ["helper"]
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

helper:
model: claude
description: "Assistant agent that helps with various tasks as directed by the root agent"
fixer:
model: anthropic/claude-sonnet-4-5 # Change to the model that you want to use
description: Fix implementer
instruction: |
You are a helpful assistant agent. Your role is to:
1. Complete specific tasks assigned by the root agent.
2. Provide detailed and accurate responses.
3. Ask for clarification if tasks are unclear.
4. Report back to the root agent with your results.

Focus on being thorough and helpful in whatever task you're given.

models:
claude:
provider: anthropic
model: claude-sonnet-4-0
max_tokens: 64000
```

[See the reference documentation](https://github.com/docker/cagent?tab=readme-ov-file#-configuration-reference).

## Built-in tools

cagent includes a set of built-in tools that enhance your agents' capabilities.
You don't need to configure any external MCP tools to use them.

```yaml
agents:
root:
# ... other config
Write fixes for bugs diagnosed by the investigator.
Make minimal, targeted changes and add tests to prevent regression.
toolsets:
- type: todo
- type: transfer_task
- type: filesystem
- type: shell
```

### Think tool
The root agent investigates and explains the problem. When it understands the
issue, it hands off to `fixer` for implementation. Each agent stays focused on
its specialty.

The think tool allows agents to reason through problems step by step:
## Installation

```yaml
agents:
root:
# ... other config
toolsets:
- type: think
```
cagent is included in Docker Desktop 4.49 and later.

### Todo tool
For Docker Engine users or custom installations:

The todo tool helps agents manage task lists:
- **Homebrew**: `brew install cagent`
- **Pre-built binaries**: [GitHub releases](https://github.com/docker/cagent/releases)
- **From source**: See the [cagent repository](https://github.com/docker/cagent?tab=readme-ov-file#build-from-source)

```yaml
agents:
root:
# ... other config
toolsets:
- type: todo
```
## Get started

### Memory tool
Try the bug analyzer team:

The memory tool provides persistent storage:
1. Set your API key for the model provider you want to use:

```yaml
agents:
root:
# ... other config
toolsets:
- type: memory
path: "./agent_memory.db"
```

### Task transfer tool
```console
$ export ANTHROPIC_API_KEY=<your_key> # For Claude models
$ export OPENAI_API_KEY=<your_key> # For OpenAI models
$ export GOOGLE_API_KEY=<your_key> # For Gemini models
```

The task transfer tool is an internal tool that allows an agent to delegate a task
to sub-agents. To prevent an agent from delegating work, make sure it doesn't have
sub-agents defined in its configuration.
2. Save the [example configuration](#why-agent-teams) as `debugger.yaml`.

### Using tools via the Docker MCP Gateway
3. Run your agent team:

If you use the [Docker MCP gateway](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md),
you can configure your agent to interact with the
gateway and use the MCP servers configured in it. See [docker mcp
gateway run](/reference/cli/docker/mcp/gateway/gateway_run.md).
```console
$ cagent run debugger.yaml
```

For example, to enable an agent to use Duckduckgo via the MCP Gateway:
You'll see a prompt where you can describe bugs or paste error messages. The
investigator analyzes the problem, then hands off to the fixer for
implementation.

```yaml
toolsets:
- type: mcp
command: docker
args: ["mcp", "gateway", "run", "--servers=duckduckgo"]
```
## How it works

## CLI interactive commands
You interact with the _root agent_, which can delegate work to sub-agents you
define. Each agent:

You can use the following CLI commands, during
CLI sessions with your agents:
- Uses its own model and parameters
- Has its own context (agents don't share knowledge)
- Can access built-in tools like todo lists, memory, and task delegation
- Can use external tools via [MCP servers](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md)

| Command | Description |
|----------|------------------------------------------|
| /exit | Exit the program |
| /reset | Clear conversation history |
| /eval | Save current conversation for evaluation |
| /compact | Compact the current session |
The root agent delegates tasks to agents listed under `sub_agents`. Sub-agents
can have their own sub-agents for deeper hierarchies.

## Share your agents
## Configuration options

Agent configurations can be packaged and shared via Docker Hub.
Before you start, make sure you have a [Docker repository](/manuals/docker-hub/repos/create.md).
Agent configurations are YAML files. A basic structure looks like this:

To push an agent:
```yaml
agents:
root:
model: claude-sonnet-4-0
description: Brief role summary
instruction: |
Detailed instructions for this agent...
sub_agents: [helper]

```bash
cagent push ./<agent-file>.yaml <namespace>/<reponame>
helper:
model: gpt-5-mini
description: Specialist agent role
instruction: |
Instructions for the helper agent...
```

To pull an agent to the current directory:
You can also configure model settings (like context limits), tools (including
MCP servers), and more. See the [configuration reference](https://github.com/docker/cagent?tab=readme-ov-file#-configuration-reference)
for complete details.

## Share agent teams

```bash
cagent pull <namespace>/<reponame>
Agent configurations are packaged as OCI artifacts. Push and pull them like
container images:

```console
$ cagent push ./debugger.yaml myusername/debugger
$ cagent pull myusername/debugger
```

The agent's configuration file is named `<namespace>_<reponame>.yaml`. Run
it with the `cagent run <filename>` command.
Use Docker Hub or any OCI-compatible registry. Pushing creates the repository
if it doesn't exist yet.

## Related pages
## What's next

- For more information about cagent, see the
[GitHub repository](https://github.com/docker/cagent).
- [Docker MCP Gateway](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md)
- Follow the [tutorial](./tutorial.md) to build your first coding agent
- Learn [best practices](./best-practices.md) for building effective agents
- Integrate cagent with your [editor](./integrations/acp.md) or use agents as
[tools in MCP clients](./integrations/mcp.md)
- Browse example agent configurations in the [cagent repository](https://github.com/docker/cagent/tree/main/examples)
- Use `cagent new` to generate agent teams with AI <!-- TODO: link to some page where we explain this, probably a CLI reference? -->
- Connect agents to external tools via the [Docker MCP Gateway](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md)
- Read the full [configuration reference](https://github.com/docker/cagent?tab=readme-ov-file#-configuration-reference) <!-- TODO: move to this site/repo -->
Loading
Loading