# docker/cagent architecture

> Architecture diagram of the GitHub repository docker/cagent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/docker/cagent
- Repository: https://github.com/docker/cagent

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        CLI["CLI Frontend"]:::ui
        TUI["Optional TUI & Desktop"]:::ui
    end

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        Config["Configuration Loader\n(pkg/config)"]:::core
        Session["Session & Persistence\n(pkg/session)"]:::core
        Orchestrator["Multi-Agent Orchestrator\n(pkg/app, pkg/agent, pkg/chat, pkg/evaluation, pkg/history)"]:::core
        Telemetry["Telemetry & Logging\n(pkg/telemetry)"]:::core
    end

    %% Adapters & Plugins
    subgraph "Adapters & Plugins"
        direction TB
        Providers["Provider Adapters\n(pkg/model/provider)"]:::adapter
        ToolsBuiltIn["Built-in Tools\n(pkg/tools/builtin)"]:::adapter
        ToolsMCP["MCP Gateway & Remote\n(pkg/tools/mcp, pkg/remote, pkg/gateway)"]:::adapter
        OCI["OCI Builder & Registry\n(pkg/oci)"]:::adapter
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AIAPIs["AI Provider APIs"]:::external
        MCPServers["MCP Tool Servers"]:::external
        DockerReg["Docker Registry"]:::external
    end

    %% Connections
    CLI -->|"parses commands"| Config
    Config -->|"loads model"| Orchestrator
    Orchestrator -->|"read/write state"| Session
    Orchestrator -->|"invoke provider"| Providers
    Orchestrator -->|"invoke tool"| ToolsBuiltIn
    Orchestrator -->|"invoke tool"| ToolsMCP
    Orchestrator -->|"report events"| Telemetry
    TUI ---|"UI events & updates"| Orchestrator
    CLI -->|"push/pull commands"| OCI
    OCI -->|"push/pull images"| DockerReg

    Providers -->|HTTP/gRPC| AIAPIs
    ToolsMCP -->|HTTP/SSE/stdio| MCPServers

    %% Click Events
    click CLI "https://github.com/docker/cagent/tree/main/cmd/root/"
    click Config "https://github.com/docker/cagent/tree/main/pkg/config/"
    click Session "https://github.com/docker/cagent/tree/main/pkg/session/"
    click Session "https://github.com/docker/cagent/tree/main/pkg/memory/database/sqlite/"
    click Orchestrator "https://github.com/docker/cagent/blob/main/pkg/app/app.go"
    click Orchestrator "https://github.com/docker/cagent/blob/main/pkg/agent/agent.go"
    click Orchestrator "https://github.com/docker/cagent/blob/main/pkg/chat/chat.go"
    click Orchestrator "https://github.com/docker/cagent/blob/main/pkg/evaluation/evaluation.go"
    click Orchestrator "https://github.com/docker/cagent/blob/main/pkg/history/history.go"
    click Providers "https://github.com/docker/cagent/tree/main/pkg/model/provider/"
    click ToolsBuiltIn "https://github.com/docker/cagent/tree/main/pkg/tools/builtin/"
    click ToolsMCP "https://github.com/docker/cagent/tree/main/pkg/tools/mcp/"
    click ToolsMCP "https://github.com/docker/cagent/blob/main/pkg/remote/push.go"
    click ToolsMCP "https://github.com/docker/cagent/blob/main/pkg/remote/pull.go"
    click ToolsMCP "https://github.com/docker/cagent/blob/main/pkg/gateway/catalog.go"
    click Telemetry "https://github.com/docker/cagent/tree/main/pkg/telemetry/"
    click TUI "https://github.com/docker/cagent/tree/main/pkg/tui/"
    click TUI "https://github.com/docker/cagent/tree/main/pkg/desktop/"
    click OCI "https://github.com/docker/cagent/tree/main/pkg/oci/"
    click OCI "https://github.com/docker/cagent/blob/main/pkg/remote/push.go"
    click OCI "https://github.com/docker/cagent/blob/main/pkg/remote/pull.go"

    %% Styles
    classDef ui fill:#f0f8ff,stroke:#000,stroke-width:1px
    classDef core fill:#ffe4b5,stroke:#000,stroke-width:1px
    classDef adapter fill:#e6e6fa,stroke:#000,stroke-width:1px
    classDef external fill:#f5f5f5,stroke:#666,stroke-dasharray: 5 5,stroke-width:1px
```
