How docker/cagent works
Project type and purpose
• cagent is a Go-based, CLI-first multi-agent orchestration runtime.
• It loads YAML-defined “agent teams,” spins up a core engine that coordinates interactive agents, tool-calling (via MCP or built-in tools), AI provider adapters, session persistence, telemetry, and an optional TUI.
• It also supports “push” and “pull” of agent configurations as OCI images (Docker registry integration).
File structure
• Top-level directories:
• cmd/… ➔ entrypoints for all CLI commands (run, new, eval, push, pull, debug, etc.)
• pkg/… ➔ core libraries (config loading, session/DB, agent orchestration, tool wrappers, provider adapters, telemetry, TUI, desktop sockets, OCI builder, remote push/pull, etc.)
• examples/, docs/ ➔ sample YAMLs and usage guides
• Key patterns:
• Hexagonal/plugin architecture – pkg/model/provider/* and pkg/tools/builtin + pkg/tools/mcp implement provider and tool “plugins”
• MVC-like layering – CLI layer (cmd), orchestration layer (pkg/app, pkg/agent), infrastructure/adapters (pkg/config, pkg/session, pkg/remote, pkg/oci, pkg/telemetry)
• Optional TUI under pkg/tui that depends on core orchestration
Extract architecture insights from README
• Core components: multi-agent engine, YAML config, MCP gateway, AI model providers
• Workflow: CLI command ➔ config ➔ session store ➔ agent event loop ➔ tool calls or provider calls ➔ output/feedback
• Push/pull: OCI image builder (pkg/oci) + remote registry adapter
Main components & their interactions (
A. CLI Frontend (cmd/*)
– Parses flags/commands, dispatches to core functions (run, new, push, pull)
B. Configuration Loader (pkg/config)
– Reads/validates/upgrade YAML definitions into internal model
C. Session & Persistence (pkg/session, pkg/memory/database/sqlite)
– Manages agent state, conversation history, memory, SQLite migrations
D. Multi-Agent Orchestrator (pkg/app, pkg/agent, pkg/chat, pkg/evaluation, pkg/history)
– Coordinates agent event loop, delegations, think/tool loops, evaluation of responses
E. Provider Adapters (pkg/model/provider/*)
– Abstracts OpenAI, Anthropic, Gemini, DMR, Docker Model Runner – HTTP/gRPC clients
F. Tool Subsystem
1. Built-in Tools (pkg/tools/builtin) – todo, think, filesystem, shell, etc.
2. MCP Gateway & Remote (pkg/tools/mcp, pkg/remote, pkg/gateway) – stdio, HTTP, SSE transport to external tool servers
G. Telemetry & Logging (pkg/telemetry)
– Captures anonymous event data, HTTP senders, global context
H. Optional TUI & Desktop Integration (pkg/tui, pkg/desktop)
– Presents interactive UI in terminal, cross-platform socket/Windows/Unix support
I. OCI Builder & Registry (pkg/oci, pkg/remote for push/pull)
– Builds a container image from YAML, pushes/pulls to Docker Hub
External Systems:
• AI Provider APIs (OpenAI, Anthropic, Gemini, DMR endpoint)
• MCP Tool Servers (e.g. duckduckgo, rust-mcp-filesystem)
• Docker Registry (for push/pull)
Architectural patterns & principles
• Layered architecture: CLI → core engine → adapters → external systems
• Hexagonal/plugins: provider & tool interfaces, easy to extend
• Separation of concerns: config, orchestration, persistence, UI, telemetry, build
• Dependency inversion: core engine depends on abstractions (provider.Tool interfaces)