# swisnl/agents-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/swisnl/agents-sdk
- Repository: https://github.com/swisnl/agents-sdk

## Overview

##### Main Components
- Agents: Represented by classes in src/Agent.php, which encapsulate an agent’s behavior. Agents coordinate tasks and can hand off work to one another (see handoff and multi-agent sections in the README).
- Tools: Defined in src/Tool and extended in examples (like WeatherAgent). These are custom capabilities that agents can call to perform external operations.
- Orchestrator: The component responsible for managing conversation flow and routing instructions between agents. This is implemented in src/Orchestrator.php and its subcomponents.
- Observers: Used to monitor agent behavior by capturing events such as before handoff or on tool call (found in src/AgentObserver.php and its concrete implementations).
- Tracing: Classes in src/Tracing (e.g., OpenAIExporter, Processor, Span) that capture execution traces and enable debugging/observability.
- Helpers & Models: Utility functions and support classes (in src/Helpers and src/Model) that aid in parameter handling, serialization of conversations, and configuration.
- Tests & Examples: Although not part of the runtime system, these directories are essential to understanding typical workflows (e.g., examples/Agents and tests/Integration) and verifying system behavior.

##### Relationships and Interactions Between Components
- The Orchestrator acts as the central controller, receiving user instructions and coordinating the execution of agents.
- Agents execute tasks by leveraging Tools; they may also trigger handoffs to other agents based on the workflow logic.
- Observers and Tracing components are “attached” to the Orchestrator and agents, intercepting events like tool calls or agent handoffs, and logging or streaming them.
- Helpers and Models support these interactions by providing common routines and encapsulating data structures required for operation.

##### Highlighting Architectural Patterns and Design Principles
- Modular and Extensible Design: Agents, Tools, and Observers are loosely coupled, making it easy to add new functionalities without interference.
- Separation of Concerns: The orchestrator handles workflow and messaging, while individual agents and tools manage specific functionalities.
- Observer Pattern: Allows for monitoring and tracing agent behavior.
- Dependency Injection (explicitly or implicitly through constructor parameters in agents/tools) promotes testability and flexibility.
- Streamed Responses: The system supports both traditional and streaming modes (as shown by the streamed agent observers and responses).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    U["User Input"]:::user

    %% Core Framework
    subgraph "Core Framework"
        O["Orchestrator (src/Orchestrator.php)"]:::orchestrator
        subgraph "Agent Components"
            AG["Agent (src/Agent.php)"]:::agent
            AG2["Agent (handoff)"]:::agent
        end
        subgraph "Tool Components"
            T["Tool (src/Tool)"]:::tool
            TA["WeatherAgent (example)"]:::tool
        end
    end

    %% Orchestrator Subcomponents
    subgraph "Orchestrator Subcomponents"
        OI["ObserverInvoker (src/Orchestrator/ObserverInvoker.php)"]:::orchestrator
        ORC["RunContext (src/Orchestrator/RunContext.php)"]:::orchestrator
        OSA["StreamedAgentObserver (src/Orchestrator/StreamedAgentObserver.php)"]:::orchestrator
    end

    %% Observability Components
    subgraph "Observability"
        AO["AgentObserver (src/AgentObserver.php)"]:::observer
        TO["ToolObserver (src/ToolObserver.php)"]:::observer
        subgraph "Tracing"
            TOpen["OpenAIExporter (src/Tracing/OpenAIExporter.php)"]:::tracing
            TProc["Processor (src/Tracing/Processor.php)"]:::tracing
            TSpan["Span (src/Tracing/Span.php)"]:::tracing
            TSFac["SpanFactory (src/Tracing/SpanFactory.php)"]:::tracing
            TTrace["Trace (src/Tracing/Trace.php)"]:::tracing
            TAObs["TraceAgentObserver (src/Tracing/TraceAgentObserver.php)"]:::tracing
        end
    end

    %% Supporting Components
    subgraph "Supporting Components"
        H1["ArrayHelper (src/Helpers/ArrayHelper.php)"]:::helper
        H2["ConversationSerializer (src/Helpers/ConversationSerializer.php)"]:::helper
        H3["EnvHelper (src/Helpers/EnvHelper.php)"]:::helper
        H4["StringHelper (src/Helpers/StringHelper.php)"]:::helper
        H5["ToolHelper (src/Helpers/ToolHelper.php)"]:::helper
        M["ModelSettings (src/Model/ModelSettings.php)"]:::model
    end

    %% Testing & Examples
    subgraph "Testing & Examples"
        EX["Examples (examples/)"]:::test
        TST["Tests (tests/)"]:::test
    end

    %% External API (optional)
    Ext["ExternalAPI"]:::external

    %% Connections
    U -->|"instructions"| O
    O -->|"dispatches"| AG
    O -->|"invokes"| OI
    O -->|"manages"| ORC
    O -->|"streams"| OSA
    AG -->|"executes"| T
    AG -->|"handoffs"| AG2
    T -->|"invokes"| TA
    AG -->|"notifies"| AO
    T -->|"notifies"| TO
    AG -->|"traced_by"| TTrace
    T -->|"traced_by"| TTrace
    AO -->|"reports_to"| TOpen
    AO -->|"reports_to"| TProc
    TO -->|"reports_to"| TSFac
    TAObs -->|"monitors"| AG
    O -->|"calls"| Ext
    EX -->|"demonstrates"| O
    TST -->|"validates"| O

    %% Supporting Components Connections (dotted links)
    AG --- H1
    AG --- H2
    O --- H3
    AG --- H4
    T --- H5
    AG --- M

    %% Click Events
    click AG "https://github.com/swisnl/agents-sdk/blob/master/src/Agent.php"
    click T "https://github.com/swisnl/agents-sdk/tree/master/src/Tool"
    click TA "https://github.com/swisnl/agents-sdk/blob/master/examples/Agents/WeatherAgent.php"
    click O "https://github.com/swisnl/agents-sdk/blob/master/src/Orchestrator.php"
    click OI "https://github.com/swisnl/agents-sdk/blob/master/src/Orchestrator/ObserverInvoker.php"
    click ORC "https://github.com/swisnl/agents-sdk/blob/master/src/Orchestrator/RunContext.php"
    click OSA "https://github.com/swisnl/agents-sdk/blob/master/src/Orchestrator/StreamedAgentObserver.php"
    click AO "https://github.com/swisnl/agents-sdk/blob/master/src/AgentObserver.php"
    click TO "https://github.com/swisnl/agents-sdk/blob/master/src/ToolObserver.php"
    click TOpen "https://github.com/swisnl/agents-sdk/blob/master/src/Tracing/OpenAIExporter.php"
    click TProc "https://github.com/swisnl/agents-sdk/blob/master/src/Tracing/Processor.php"
    click TSpan "https://github.com/swisnl/agents-sdk/blob/master/src/Tracing/Span.php"
    click TSFac "https://github.com/swisnl/agents-sdk/blob/master/src/Tracing/SpanFactory.php"
    click TTrace "https://github.com/swisnl/agents-sdk/blob/master/src/Tracing/Trace.php"
    click TAObs "https://github.com/swisnl/agents-sdk/blob/master/src/Tracing/TraceAgentObserver.php"
    click H1 "https://github.com/swisnl/agents-sdk/blob/master/src/Helpers/ArrayHelper.php"
    click H2 "https://github.com/swisnl/agents-sdk/blob/master/src/Helpers/ConversationSerializer.php"
    click H3 "https://github.com/swisnl/agents-sdk/blob/master/src/Helpers/EnvHelper.php"
    click H4 "https://github.com/swisnl/agents-sdk/blob/master/src/Helpers/StringHelper.php"
    click H5 "https://github.com/swisnl/agents-sdk/blob/master/src/Helpers/ToolHelper.php"
    click M "https://github.com/swisnl/agents-sdk/blob/master/src/Model/ModelSettings.php"
    click EX "https://github.com/swisnl/agents-sdk/tree/master/examples/"
    click TST "https://github.com/swisnl/agents-sdk/tree/master/tests/"

    %% Style Definitions
    classDef user fill:#fdd,stroke:#900,stroke-width:2px;
    classDef orchestrator fill:#cfc,stroke:#090,stroke-width:2px;
    classDef agent fill:#ccf,stroke:#33f,stroke-width:2px;
    classDef tool fill:#fcf,stroke:#c0c,stroke-width:2px;
    classDef observer fill:#ffd,stroke:#cc0,stroke-width:2px;
    classDef tracing fill:#ffc,stroke:#cc0,stroke-width:2px;
    classDef helper fill:#efe,stroke:#4a4,stroke-width:2px;
    classDef model fill:#eef,stroke:#44f,stroke-width:2px;
    classDef test fill:#ddd,stroke:#777,stroke-width:2px;
    classDef external fill:#eef,stroke:#00f,stroke-width:2px;
```
