centersl/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-03-27 06:18:55 +07:00
Code Issues Packages Projects Releases Wiki Activity

cagent (#23336)

Browse Source 
Add cagent docs to open-source section.

---------

Co-authored-by: Usha Mandya <47779042+usha-mandya@users.noreply.github.com>
This commit is contained in:
Arthur
2025-09-04 16:46:45 +02:00
committed by GitHub
parent 4b3efa0ca1
commit c3df922b83
8 changed files with 456 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
_vale/config/vocabularies/Docker/accept.txt
View File

@@ -1,6 +1,5 @@
(?i)[A-Z]{2,}'?s
[Dd]ev
Adreno
Aleksandrov
Amazon
@@ -18,6 +17,7 @@ Bugsnag
BuildKit
buildkitd
BusyBox
cagent
CD
CentOS
Ceph
@@ -65,6 +65,7 @@ dockerignore
Dockerize
Dockerized
Dockerizing
Duckduckgo
Entra
EPERM
ESXi
@@ -130,11 +131,11 @@ MySQL
nameserver
namespaced?
namespacing
Neovim
netfilter
netlabel
netlink
Netplan
Neovim
NFSv\d
Nginx
npm
@@ -219,6 +220,7 @@ Zsh
[Aa]nonymized?
[Aa]utobuild
[Aa]llowlist
[Aa]gentic
[Aa]utobuilds?
[Aa]utotests?
[Bb]uildx
@@ -266,6 +268,7 @@ Zsh
[Ss]yscalls?
[Ss]ysfs
[Tt]eardown
[Tt]odo
[Tt]oolchains?
[Uu]narchived?
[Uu]ngated

14
assets/icons/cagent.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 9.0 KiB

5
content/manuals/_index.md
View File

@@ -36,7 +36,10 @@ params:
description: Manage and secure your AI tools with a single gateway.
icon: /icons/toolkit.svg
link: /ai/mcp-gateway/
- title: Cagent
description: The open-source multi-agent solution to assist you in your tasks.
icon: /icons/cagent.svg
link: /ai/cagent
ai:
- title: Ask Gordon
description: Streamline your workflow and get the most out of the Docker ecosystem with your personal AI assistant.

260
content/manuals/ai/cagent/_index.md Normal file
View File

@@ -0,0 +1,260 @@
---
title: cagent
description: cagent lets you build, orchestrate, and share AI agents that work together as a team.
weight: 60
params:
sidebar:
group: Open source
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 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-gateway/_index.md).
- works in its own context. They do not share knowledge.
The root agent is your main contact point. Each agent has its own context,
they don't share knowledge.
## Key features
- ️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. Download the [latest release](https://github.com/docker/cagent/releases)
for your operating system.
> [!NOTE]
> You might need to give the binary executable permissions.
> On macOS and Linux, run:
```console
chmod +x /path/to/downloads/cagent-linux-<arm/amd>64
```
> [!NOTE]
> You can also build cagent from the source. See the [repository](https://github.com/docker/cagent?tab=readme-ov-file#build-from-source).
1. Optional: Rename the binary as needed and update your PATH to include
cagent's executable.
1. Set the following environment variables:
```bash
# If using the Docker AI Gateway, set this environment variable or use
# the `--models-gateway <url_to_docker_ai_gateway>` CLI flag
export CAGENT_MODELS_GATEWAY=<url_to_docker_ai_gateway>
# Alternatively, set keys for remote inference services.
# These are not needed if you are using Docker AI Gateway.
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"}
agents:
root:
model: claude
description: "Main coordinator agent that delegates tasks and manages workflow"
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"]
helper:
model: claude
description: "Assistant agent that helps with various tasks as directed by the root agent"
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
toolsets:
- type: todo
- type: transfer_task
```
### Think tool
The think tool allows agents to reason through problems step by step:
```yaml
agents:
root:
# ... other config
toolsets:
- type: think
```
### Todo tool
The todo tool helps agents manage task lists:
```yaml
agents:
root:
# ... other config
toolsets:
- type: todo
```
### Memory tool
The memory tool provides persistent storage:
```yaml
agents:
root:
# ... other config
toolsets:
- type: memory
path: "./agent_memory.db"
```
### Task transfer tool
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.
### Using tools via the Docker MCP Gateway
If you use the [Docker MCP gateway](/manuals/ai/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).
For example, to enable an agent to use Duckduckgo via the MCP Gateway:
```yaml
toolsets:
- type: mcp
command: docker
args: ["mcp", "gateway", "run", "--servers=duckduckgo"]
```
## CLI interactive commands
You can use the following CLI commands, during
CLI sessions with your agents:
| Command | Description |
|----------|------------------------------------------|
| /exit | Exit the program |
| /reset | Clear conversation history |
| /eval | Save current conversation for evaluation |
| /compact | Compact the current session |
## Share your agents
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).
To push an agent:
```bash
cagent push ./<agent-file>.yaml <namespace>/<reponame>
```
To pull an agent to the current directory:
```bash
cagent pull <namespace>/<reponame>
```
The agent's configuration file is named `<namespace>_<reponame>.yaml`. Run
it with the `cagent run <filename>` command.
## Related pages
- For more information about cagent, see the
[GitHub repository](https://github.com/docker/cagent).
- [Docker MCP Gateway](/manuals/ai/mcp-gateway/_index.md)

166
content/manuals/ai/cagent/examples.md Normal file
View File

@@ -0,0 +1,166 @@
---
title: cagent examples
description: Get inspiration from agent examples
keywords: [ai, agent, cagent]
weight: 10
---
Get inspiration from the following agent examples.
## Agentic development team
```yaml {title="dev-team.yaml"}
agents:
root:
model: claude
description: Technical lead coordinating development
instruction: |
You are a technical lead managing a development team.
Coordinate tasks between developers and ensure quality.
sub_agents: [developer, reviewer, tester]
developer:
model: claude
description: Expert software developer
instruction: |
You are an expert developer. Write clean, efficient code
and follow best practices.
toolsets:
- type: filesystem
- type: shell
- type: think
reviewer:
model: gpt4
description: Code review specialist
instruction: |
You are a code review expert. Focus on code quality,
security, and maintainability.
toolsets:
- type: filesystem
tester:
model: gpt4
description: Quality assurance engineer
instruction: |
You are a QA engineer. Write tests and ensure
software quality.
toolsets:
- type: shell
- type: todo
models:
gpt4:
provider: openai
model: gpt-4o
claude:
provider: anthropic
model: claude-sonnet-4-0
max_tokens: 64000
```
## Research assistant
```yaml {title="research-assistant.yaml"}
agents:
root:
model: claude
description: Research assistant with web access
instruction: |
You are a research assistant. Help users find information,
analyze data, and provide insights.
toolsets:
- type: mcp
command: mcp-web-search
args: ["--provider", "duckduckgo"]
- type: todo
- type: memory
path: "./research_memory.db"
models:
claude:
provider: anthropic
model: claude-sonnet-4-0
max_tokens: 64000
```
## Technical blog writer
```yaml {title="tech-blog-writer.yaml"}
#!/usr/bin/env cagent run
version: "1"
agents:
root:
model: anthropic
description: Writes technical blog posts
instruction: |
You are the leader of a team of AI agents for a technical blog writing workflow.
Here are the members in your team:
<team_members>
- web_search_agent: Searches the web
- writer: Writes a 750-word technical blog post based on the chosen prompt
</team_members>
<WORKFLOW>
1. Call the `web_search_agent` agent to search the web to get
important information about the task that is asked
2. Call the `writer` agent to write a 750-word technical blog
post based on the research done by the web_search_agent
</WORKFLOW>
- Use the transfer_to_agent tool to call the right agent at the right
time to complete the workflow.
- DO NOT transfer to multiple members at once
- ONLY CALL ONE AGENT AT A TIME
- When using the `transfer_to_agent` tool, make exactly one call
and wait for the result before making another. Do not batch or
parallelize tool calls.
sub_agents:
- web_search_agent
- writer
toolsets:
- type: think
web_search_agent:
model: anthropic
add_date: true
description: Search the web for information
instruction: |
Search the web for information
Always include sources
toolsets:
- type: mcp
command: uvx
args: ["duckduckgo-mcp-server"]
writer:
model: anthropic
description: Writes a 750-word technical blog post based on the chosen prompt.
instruction: |
You are an agent that receives a single technical writing prompt
and generates a detailed, informative, and well-structured technical blog post.
- Ensure the content is technically accurate and includes relevant
code examples, diagrams, or technical explanations where appropriate.
- Structure the blog post with clear sections, including an introduction,
main content, and conclusion.
- Use technical terminology appropriately and explain complex concepts clearly.
- Include practical examples and real-world applications where relevant.
- Make sure the content is engaging for a technical audience while
maintaining professional standards.
Constraints:
- DO NOT use lists
models:
anthropic:
provider: anthropic
model: claude-3-5-sonnet-latest
```
See more examples in the [repository](https://github.com/docker/cagent/tree/main/examples).

1
content/manuals/ai/mcp-gateway/_index.md
View File

@@ -2,6 +2,7 @@
title: MCP Gateway
description: "Docker's MCP Gateway provides secure, centralized, and scalable orchestration of AI tools through containerized MCP servers—empowering developers, operators, and security teams."
keywords: MCP Gateway
weight: 50
params:
sidebar:
group: Open source

7
content/manuals/testcontainers.md
View File

@@ -1,5 +1,6 @@
---
title: Testcontainers
weight: 40
description: Learn how to use Testcontainers to run containers programmatically in your preferred programming language.
keywords: docker APIs, docker, testcontainers documentation, testcontainers, testcontainers oss, testcontainers oss documentation,
docker compose, docker-compose, java, golang, go
@@ -12,7 +13,7 @@ intro:
icon: feature_search
link: https://testcontainers.com/getting-started/#what-is-testcontainers
- title: The Testcontainers workflow
description: Understand the Testcontainers workflow
description: Understand the Testcontainers workflow
icon: explore
link: https://testcontainers.com/getting-started/#testcontainers-workflow
quickstart:
@@ -44,8 +45,8 @@ The rest are community-driven and maintained by independent contributors.
### Prerequisites
Testcontainers requires a Docker-API compatible container runtime.
During development, Testcontainers is actively tested against recent versions of Docker on Linux, as well as against Docker Desktop on Mac and Windows.
Testcontainers requires a Docker-API compatible container runtime.
During development, Testcontainers is actively tested against recent versions of Docker on Linux, as well as against Docker Desktop on Mac and Windows.
These Docker environments are automatically detected and used by Testcontainers without any additional configuration being necessary.
It is possible to configure Testcontainers to work for other Docker setups, such as a remote Docker host or Docker alternatives.

2
data/summary.yaml
View File

@@ -63,6 +63,8 @@ Buildx no default:
requires: Docker Buildx [0.10.4](/manuals/build/release-notes.md#0104) and later
Cache backend API:
availability: Experimental
cagent:
availability: Experimental
Company:
subscription: [Business]
for: Administrators