# chatwoot/ai-agents architecture

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

- Interactive diagram: https://gitdiagram.com/chatwoot/ai-agents
- Repository: https://github.com/chatwoot/ai-agents

## Overview

##### Project type and purpose
- This is an open-source Ruby SDK (gem) named “ai-agents” for building multi-agent AI workflows.
- It lets you define “Agent” objects with instructions, tools, and handoff relationships, orchestrate them via a thread-safe “Runner,” maintain shared context, and integrate with multiple LLM providers (OpenAI, Anthropic, etc.) and external services via custom Tools.

##### File structure
- lib/agents — core classes: Agent, AgentRunner, Runner, Tool, CallbackManager, Context, Handoff, etc.
- bin/ — CLI entrypoints (console, setup).
- docs/ — architecture.md, concepts, guides (explains patterns).
- examples/ — sample multi-agent workflows and Tools integrations.
- spec/ — unit tests for all core components.
- .github/workflows — CI.
- Gemfile, Rakefile — build/test tasks.

##### README for additional insights
- Core components section outlines: Agent, AgentRunner (with internal Runner), Context & State, Tools, Handoffs.
- It shows usage patterns: single agent, multi-agent hub-and-spoke, tool definitions.
- Configuration points: provider API keys, models, timeouts, debug flags.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Client["Client/Application"]:::client
    end

    %% Core Library Components
    subgraph "Core Library (lib/agents)"
        AR["AgentRunner<br/>(agent_runner.rb)"]:::core
        R["Runner<br/>(runner.rb)"]:::core
        A["Agent<br/>(agent.rb)"]:::core
        HM["Handoff Manager<br/>(handoff.rb)"]:::core
        RC["Shared Context Store<br/>(run_context.rb)"]:::core
        CM["Callback Manager<br/>(callback_manager.rb)"]:::core
        ME["Message Extractor<br/>(message_extractor.rb)"]:::core
        Res["Result<br/>(result.rb)"]:::core
        AGT["Agent-Tool Adapter<br/>(agent_tool.rb)"]:::core
        TW["Tool Wrapper<br/>(tool_wrapper.rb)"]:::core
        TC["Tool Context<br/>(tool_context.rb)"]:::core
        T["Tool Base Class<br/>(tool.rb)"]:::core
        Chat["Chat Adapter<br/>(chat.rb)"]:::core
        Ver["Version<br/>(version.rb)"]:::core
    end

    %% LLM Providers
    subgraph "LLM Providers"
        OAI["OpenAI"]:::provider
        AN["Anthropic"]:::provider
        GEM["Gemini"]:::provider
    end

    %% Tools & External
    subgraph "Tools & External Services"
        ExtAPI["External API/DB"]:::tools
    end

    %% Other Project Files
    subgraph "Other Project Files"
        CLI1["bin/console"]:::client
        CLI2["bin/setup"]:::client
        Examples["examples/"]:::client
        Docs["docs/"]:::client
        Specs["spec/"]:::client
        Build["ai-agents.gemspec<br/>Rakefile"]:::client
        CI[".github/workflows/"]:::client
    end

    %% Data Flows
    Client -->|invokes| AR
    AR -->|creates| R
    R -->|delegates to| A
    A -->|builds prompt| Chat
    Chat -->|"LLM request"| OAI
    Chat -->|"LLM request"| AN
    Chat -->|"LLM request"| GEM
    OAI -->|"LLM response"| Chat
    AN -->|"LLM response"| Chat
    GEM -->|"LLM response"| Chat
    Chat -->|parses| ME
    ME -->|identifies tool| AGT
    AGT -->|wraps| TW
    TW -->|invoke| T
    T -->|perform| ExtAPI
    ExtAPI -->|response| T
    T -->|returns output| TW
    TW -->|returns| AGT
    AGT -->|returns| R
    R -->|updates| RC
    R -->|calls| HM
    HM -->|switches agent| A
    R -->|logs events| CM
    R -->|returns| Res
    Res -->|final output| Client

    %% Unlinked project files for reference
    Client --> CLI1
    Client --> CLI2
    Client -.-> Examples
    Client -.-> Docs
    Client -.-> Specs
    Client -.-> Build
    Client -.-> CI

    %% Click Events
    click A "https://github.com/chatwoot/ai-agents/blob/main/lib/agents/agent.rb"
    click AR "https://github.com/chatwoot/ai-agents/blob/main/lib/agents/agent_runner.rb"
    click R "https://github.com/chatwoot/ai-agents/blob/main/lib/agents/runner.rb"
    click RC "https://github.com/chatwoot/ai-agents/blob/main/lib/agents/run_context.rb"
    click TC "https://github.com/chatwoot/ai-agents/blob/main/lib/agents/tool_context.rb"
    click T "https://github.com/chatwoot/ai-agents/blob/main/lib/agents/tool.rb"
    click AGT "https://github.com/chatwoot/ai-agents/blob/main/lib/agents/agent_tool.rb"
    click TW "https://github.com/chatwoot/ai-agents/blob/main/lib/agents/tool_wrapper.rb"
    click HM "https://github.com/chatwoot/ai-agents/blob/main/lib/agents/handoff.rb"
    click CM "https://github.com/chatwoot/ai-agents/blob/main/lib/agents/callback_manager.rb"
    click ME "https://github.com/chatwoot/ai-agents/blob/main/lib/agents/message_extractor.rb"
    click Res "https://github.com/chatwoot/ai-agents/blob/main/lib/agents/result.rb"
    click Chat "https://github.com/chatwoot/ai-agents/blob/main/lib/agents/chat.rb"
    click Ver "https://github.com/chatwoot/ai-agents/blob/main/lib/agents/version.rb"
    click CLI1 "https://github.com/chatwoot/ai-agents/tree/main/bin/console"
    click CLI2 "https://github.com/chatwoot/ai-agents/tree/main/bin/setup"
    click Examples "https://github.com/chatwoot/ai-agents/tree/main/examples/"
    click Docs "https://github.com/chatwoot/ai-agents/tree/main/docs/"
    click Specs "https://github.com/chatwoot/ai-agents/tree/main/spec/"
    click Build "https://github.com/chatwoot/ai-agents/blob/main/ai-agents.gemspec"
    click Build "https://github.com/chatwoot/ai-agents/tree/main/Rakefile"
    click CI "https://github.com/chatwoot/ai-agents/tree/main/.github/workflows/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef provider fill:#d4edda,stroke:#333,stroke-width:1px
    classDef tools fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef client fill:#e2e3e5,stroke:#333,stroke-width:1px
```
