# openai/swarm architecture

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

- Interactive diagram: https://gitdiagram.com/openai/swarm
- Repository: https://github.com/openai/swarm

## Overview

##### Main Components

a) Core Components:
- Swarm Client
- Agent System
- Function Execution Engine
- Message Handler
- Context Variable Manager
- Streaming Handler

b) Integration Components:
- OpenAI API Interface
- Chat Completions API
- Tools/Functions Registry

**┌─ Application Layer ─────────────────────────────────┐**

- ┌─ Client Applications ──┐                         │
- Examples            │                         │
- Custom Implementations│                         │
- ┘                         │

- Swarm Core Layer ──────────────────────────────────┤

- ┌─ Swarm Client ────────────────────────┐         │

- ┌─ Agent Manager ─┐  ┌─ Message Flow ┐│         │

- Instructions │  │  - History    ││         │
- Functions    │  │  - Routing    ││         │
- ┘  └───────────────┘│         │

- ┌─ Context Manager ┐ ┌─ Tools Engine ┐│         │

- Variables    │ │  - Execution  ││         │
- State        │ │  - Results    ││         │
- ┘ └───────────────┘│         │
- ┘         │

- Integration Layer ────────────────────────────────┤

- ┌─ OpenAI API ─────┐   ┌─ External Services ─┐    │

- Chat          │   │ - Custom Tools      │    │
- Completions   │   │ - Functions         │    │
- ┘   └─────────────────────┘    │

- ┘

##### Key Elements to Highlight

- Rectangles with rounded corners for main components
- Diamonds for decision points (agent handoffs)
- Blue: Core Swarm components
- Green: External integrations
- Yellow: Client applications
- Gray: Support services

##### Flow Patterns to Illustrate

Main execution loop:

##### Important Relationships

- Agent-to-Agent handoffs
- Function calling patterns
- Context variable flow
- Message history maintenance
- Streaming response path

##### Technical Details

- Model configuration options
- Function schema conversion
- Response object structure
- Context variable scope
- Tool execution patterns

##### Notes

Annotations for:
- Experimental/educational nature
- Stateless design
- OpenAI API dependencies
- Streaming capabilities
- Error handling patterns

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Application
        ClientApps["Client Applications"]:::app
        Examples["Basic Examples & Patterns"]:::app
        CustomImpl["Custom Implementations"]:::app
    end

    subgraph SwarmCore["Swarm Core Layer"]
        SwarmClient["Swarm Client"]:::core
        AgentSystem["Agent System"]:::core
        MessageHandler["Message Handler"]:::core
        ContextManager["Context Variable Manager"]:::core
        FunctionEngine["Function Execution Engine"]:::core
        StreamHandler["Streaming Handler"]:::core
        TypesRegistry["Types & Function Registry"]:::core
        Utils["Utility Functions"]:::core
        REPL["REPL Interface"]:::core
    end

    subgraph Integration
        OpenAI["OpenAI API Interface"]:::external
        ChatAPI["Chat Completions API"]:::external
        ToolsRegistry["Tools/Functions Registry"]:::external
    end

    %% Relationships
    ClientApps --> SwarmClient
    Examples --> SwarmClient
    CustomImpl --> SwarmClient

    SwarmClient --> AgentSystem
    SwarmClient --> MessageHandler
    SwarmClient --> ContextManager
    SwarmClient --> FunctionEngine

    AgentSystem --> MessageHandler
    MessageHandler --> ContextManager
    MessageHandler --> FunctionEngine
    FunctionEngine --> StreamHandler

    FunctionEngine --> OpenAI
    OpenAI --> ChatAPI
    FunctionEngine --> ToolsRegistry

    %% Click Events
    click SwarmClient "https://github.com/openai/swarm/blob/main/swarm/core.py"
    click MessageHandler "https://github.com/openai/swarm/blob/main/swarm/core.py"
    click TypesRegistry "https://github.com/openai/swarm/blob/main/swarm/types.py"
    click Utils "https://github.com/openai/swarm/blob/main/swarm/util.py"
    click REPL "https://github.com/openai/swarm/blob/main/swarm/repl/repl.py"
    click StreamHandler "https://github.com/openai/swarm/blob/main/examples/customer_service_streaming/src/swarm/engines/engine.py"
    click ToolsRegistry "https://github.com/openai/swarm/tree/main/examples/customer_service_streaming/configs/tools/"
    click AgentSystem "https://github.com/openai/swarm/blob/main/examples/customer_service_streaming/src/swarm/assistants.py"
    click FunctionEngine "https://github.com/openai/swarm/blob/main/examples/customer_service_streaming/src/swarm/engines/local_engine.py"
    click Examples "https://github.com/openai/swarm/tree/main/examples/basic/"
    click ContextManager "https://github.com/openai/swarm/blob/main/examples/basic/context_variables.py"
    click FunctionEngine "https://github.com/openai/swarm/blob/main/examples/basic/function_calling.py"

    %% Styles
    classDef core fill:#2374ab,stroke:#2374ab,color:#fff
    classDef external fill:#57a773,stroke:#57a773,color:#fff
    classDef app fill:#ffc857,stroke:#ffc857,color:#000

    %% Legend
    subgraph Legend
        CoreComponent["Core Component"]:::core
        ExternalService["External Service"]:::external
        ApplicationLayer["Application Layer"]:::app
    end
```
