|
| 1 | +--- |
| 2 | +title: cagent |
| 3 | +description: cagent lets you build, orchestrate, and share AI agents that work together as a team. |
| 4 | +weight: 60 |
| 5 | +params: |
| 6 | + sidebar: |
| 7 | + group: Open source |
| 8 | +keywords: [ai, agent, cagent] |
| 9 | +--- |
| 10 | + |
| 11 | +`cagent` is lets you build, orchestrate, and share AI agents. Use it to build AI |
| 12 | +agents that can work as a team. Build a root agent that can delegate |
| 13 | +tasks to sub-agents. Each agent can use the model of your choice, with the |
| 14 | +parameters of your choice. |
| 15 | + |
| 16 | +## Key features |
| 17 | + |
| 18 | +- ️Multi-tenant architecture with client isolation and session management. |
| 19 | +- Rich tool ecosystem via Model Context Protocol (MCP) integration. |
| 20 | +- Hierarchical agent system with intelligent task delegation. |
| 21 | +- Multiple interfaces including CLI, TUI, API server, and MCP server. |
| 22 | +- Agent distribution via Docker registry integration. |
| 23 | +- Security-first design with proper client scoping and resource isolation. |
| 24 | +- Event-driven streaming for real-time interactions. |
| 25 | +- Multi-model support (OpenAI, Anthropic, Gemini, DMR, Docker AI Gateway). |
| 26 | + |
| 27 | +## Get started with cagent |
| 28 | + |
| 29 | +1. Download the [latest release](https://github.com/docker/cagent/releases) |
| 30 | + for your operating system. |
| 31 | + |
| 32 | + > [!NOTE] |
| 33 | + > You may need to give the release executable permissions. |
| 34 | + > On MacOS and Linux, do so by running: |
| 35 | +
|
| 36 | + ```console |
| 37 | + chmod +x /path/to/downloads/cagent-linux-<arm/amd>64 |
| 38 | + ``` |
| 39 | + |
| 40 | +1. Optional: Rename the binary as needed and update your PATH to include |
| 41 | + cagent's executable. |
| 42 | + |
| 43 | +1. Set the following environment variables: |
| 44 | + |
| 45 | + ```bash |
| 46 | + # If using the Docker AI Gateway, set this env var or use |
| 47 | + # the `--models-gateway url_to_docker_ai_gateway` CLI flag |
| 48 | + |
| 49 | + export CAGENT_MODELS_GATEWAY=url_to_docker_ai_gateway |
| 50 | + |
| 51 | + # Alternatively, you to need set keys for remote inference services |
| 52 | + # These are not needed if you are using Docker AI Gateway |
| 53 | + |
| 54 | + export OPENAI_API_KEY=your_api_key_here # For OpenAI models |
| 55 | + export ANTHROPIC_API_KEY=your_api_key_here # For Anthopic models |
| 56 | + export GOOGLE_API_KEY=your_api_key_here # For Gemini models |
| 57 | + ``` |
| 58 | + |
| 59 | +1. Create an agent by saving this sample as `assistant.yaml`: |
| 60 | + |
| 61 | + ```yaml {title="assistant.yaml"} |
| 62 | + agents: |
| 63 | + root: |
| 64 | + model: openai/gpt-5-mini |
| 65 | + description: A helpful AI assistant |
| 66 | + instruction: | |
| 67 | + You are a knowledgeable assistant that helps users with various tasks. |
| 68 | + Be helpful, accurate, and concise in your responses. |
| 69 | + ``` |
| 70 | +
|
| 71 | +1. Start your prompt with your agent: |
| 72 | +
|
| 73 | + ```bash |
| 74 | + cagent run my-agent.yaml |
| 75 | + ``` |
| 76 | + |
| 77 | +## Create an agentic team |
| 78 | + |
| 79 | +```yaml {title="agentic-team.yaml"} |
| 80 | +agents: |
| 81 | + root: |
| 82 | + model: claude |
| 83 | + description: "Main coordinator agent that delegates tasks and manages workflow" |
| 84 | + instruction: | |
| 85 | + You are the root coordinator agent. Your job is to: |
| 86 | + 1. Understand user requests and break them down into manageable tasks |
| 87 | + 2. Delegate appropriate tasks to your helper agent |
| 88 | + 3. Coordinate responses and ensure tasks are completed properly |
| 89 | + 4. Provide final responses to the user |
| 90 | + When you receive a request, analyze what needs to be done and decide whether to: |
| 91 | + - Handle it yourself if it's simple |
| 92 | + - Delegate to the helper agent if it requires specific assistance |
| 93 | + - Break complex requests into multiple sub-tasks |
| 94 | + sub_agents: ["helper"] |
| 95 | + |
| 96 | + helper: |
| 97 | + model: claude |
| 98 | + description: "Assistant agent that helps with various tasks as directed by the root agent" |
| 99 | + instruction: | |
| 100 | + You are a helpful assistant agent. Your role is to: |
| 101 | + 1. Complete specific tasks assigned by the root agent |
| 102 | + 2. Provide detailed and accurate responses |
| 103 | + 3. Ask for clarification if tasks are unclear |
| 104 | + 4. Report back to the root agent with your results |
| 105 | +
|
| 106 | + Focus on being thorough and helpful in whatever task you're given. |
| 107 | +
|
| 108 | +models: |
| 109 | + claude: |
| 110 | + provider: anthropic |
| 111 | + model: claude-sonnet-4-0 |
| 112 | + max_tokens: 64000 |
| 113 | +``` |
| 114 | +
|
| 115 | +[See the reference documentation](https://github.com/docker/cagent/blob/main/docs/user-guide.md#configuration-reference). |
| 116 | +
|
| 117 | +## Learn more about cagent |
| 118 | +
|
| 119 | +For more information, see the following documentation in the |
| 120 | +[GitHub repository](https://github.com/docker/cagent): |
| 121 | +
|
| 122 | +- [User guide](https://github.com/docker/cagent/blob/main/docs/user-guide.md) |
| 123 | +- [Configuration reference](https://github.com/docker/cagent/blob/main/docs/user-guide.md#configuration-reference) |
0 commit comments