# i-am-bee/beeai-framework architecture

> Architecture diagram of the GitHub repository i-am-bee/beeai-framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/i-am-bee/beeai-framework
- Repository: https://github.com/i-am-bee/beeai-framework

## Overview

##### Main Components
- Agents: Both core and experimental agents (e.g., reactive agents, remote agents, tool-calling agents) are located under directories like “beeai_framework/agents” in Python and “src/agents” in TypeScript.
- Backends: These components, handling chat interactions and message processing, are in “beeai_framework/backend” and “src/backend”. They typically use different AI providers.
- Adapters: Several adapters exist for various providers (Amazon Bedrock, Anthropic, Azure OpenAI, Groq, etc.) organized under their respective “adapters” directories. They abstract external model integrations.
- Tools: A variety of tools—from search to weather and code execution—reside in “beeai_framework/tools” (or “src/tools”) and are integrated to extend agent capabilities.
- Memory & Cache: Modules that implement different memory strategies (sliding, token-based, unconstrained, etc.) are under “beeai_framework/memory” and their tests/examples.
- Emitter & Events: Components that handle telemetry/logging and event flows (located in both “emitter” and “events” directories) provide observability and debugging.
- Workflows: The orchestration layer for building multi-agent systems, evident from the “workflows” directories. They link agent interactions in a structured sequence.
- Supporting Utilities: Helpers for configuration, retry logic, parsing, serialization, and general utilities, spread over several directories.

##### Out Relationships & Data Flow
- How an external request (or user interaction) enters the system and is routed into a workflow.
- How agents interact with backend services that use the adapters to communicate with external AI providers.
- Present how tools are invoked by agents to extend functionalities, and how caching, memory, and logging/emitter components provide support during processing.
- Error handling and event propagation paths showing how errors and telemetry data are managed.

##### Architectural Patterns & Design Principles
- Modularity and Abstraction – The separation of concerns is clear: adapters encapsulate provider-specific logic, agents handle interaction logic, workflows orchestrate multi-agent behavior, and utilities / middleware (cache, emitter, memory) provide cross-cutting functionalities.
- Adapter Design Pattern – For integrating multiple external AI/model providers, each adapter (e.g., amazon_bedrock, anthropic, azure_openai) follows a similar structure.
- Layered Architecture – The system is organized in layers (interface/workflow → agents → backend/adapters → external providers), with clear interfaces between each.
- Extensibility – With tool integrations and customizable agent architectures, the design encourages adding more functionality (e.g., new providers or tools).

##### Relevant Technologies & Frameworks
- Python and TypeScript versions of the framework (with each having similar modules, tests, and docs).
- AI integration through models provided by vendors like OpenAI, Ollama, watsonx, etc.
- Tools integrations (e.g., LangChain, custom search tools) are highlighted as part of extension points.
- Emphasis on event logging, caching, and memory management, which are built-in to scale production deployments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    R("User Request")
    
    subgraph "Workflow Orchestration"
        W1("Python Workflows"):::workflow
        W2("TypeScript Workflows"):::workflow
    end
    
    subgraph "Agents"
        A1("Python Agents"):::agent
        A2("TypeScript Agents"):::agent
    end
    
    subgraph "Backends"
        B1("Python Backends"):::backend
        B2("TypeScript Backends"):::backend
    end
    
    subgraph "Tools"
        T1("Python Tools"):::tools
        T2("TypeScript Tools"):::tools
    end
    
    subgraph "Adapters"
        D1("Python Adapters"):::adapter
        D2("TypeScript Adapters"):::adapter
    end
    
    subgraph "AI Providers"
        P1("OpenAI"):::external
        P2("Amazon Bedrock"):::external
        P3("Anthropic"):::external
        P4("Azure OpenAI"):::external
        P5("Groq"):::external
    end
    
    subgraph "Memory & Cache"
        M1("Python Memory"):::memory
        C1("Python Cache"):::memory
        M2("TypeScript Memory"):::memory
        C2("TypeScript Cache"):::memory
    end
    
    subgraph "Emitter & Events"
        E1("Python Emitter"):::emitter
        E2("TypeScript Emitter"):::emitter
    end
    
    subgraph "Utilities"
        U1("Python Utilities"):::utility
        U2("TS Helpers"):::utility
        U3("TS Internals"):::utility
    end

    %% Primary flow
    R --> W1
    R --> W2
    W1 --> A1
    W2 --> A2
    A1 --> B1
    A2 --> B2
    A1 --> T1
    A2 --> T2
    B1 --> D1
    B2 --> D2
    D1 --> P1
    D1 --> P2
    D1 --> P3
    D1 --> P4
    D1 --> P5
    D2 --> P1
    D2 --> P2
    D2 --> P3
    D2 --> P4
    D2 --> P5

    %% Support and cross-cutting concerns (dashed lines)
    A1 -.-> U1
    A2 -.-> U1
    T1 -.-> C1
    T2 -.-> C2
    B1 -.-> E1
    B2 -.-> E2
    U1 -.-> M1
    U1 -.-> M2

    %% Click Events
    click W1 "https://github.com/i-am-bee/beeai-framework/tree/main/python/beeai_framework/workflows"
    click W2 "https://github.com/i-am-bee/beeai-framework/tree/main/typescript/src/workflows"
    click A1 "https://github.com/i-am-bee/beeai-framework/tree/main/python/beeai_framework/agents"
    click A2 "https://github.com/i-am-bee/beeai-framework/tree/main/typescript/src/agents"
    click B1 "https://github.com/i-am-bee/beeai-framework/tree/main/python/beeai_framework/backend"
    click B2 "https://github.com/i-am-bee/beeai-framework/tree/main/typescript/src/backend"
    click T1 "https://github.com/i-am-bee/beeai-framework/tree/main/python/beeai_framework/tools"
    click T2 "https://github.com/i-am-bee/beeai-framework/tree/main/typescript/src/tools"
    click D1 "https://github.com/i-am-bee/beeai-framework/tree/main/python/beeai_framework/adapters"
    click D2 "https://github.com/i-am-bee/beeai-framework/tree/main/typescript/src/adapters"
    click M1 "https://github.com/i-am-bee/beeai-framework/tree/main/python/beeai_framework/memory"
    click C1 "https://github.com/i-am-bee/beeai-framework/tree/main/python/beeai_framework/cache"
    click M2 "https://github.com/i-am-bee/beeai-framework/tree/main/typescript/src/memory"
    click C2 "https://github.com/i-am-bee/beeai-framework/tree/main/typescript/src/cache"
    click E1 "https://github.com/i-am-bee/beeai-framework/tree/main/python/beeai_framework/emitter"
    click E2 "https://github.com/i-am-bee/beeai-framework/tree/main/typescript/src/emitter"
    click U1 "https://github.com/i-am-bee/beeai-framework/tree/main/python/beeai_framework/utils"
    click U2 "https://github.com/i-am-bee/beeai-framework/tree/main/typescript/src/internals/helpers"
    click U3 "https://github.com/i-am-bee/beeai-framework/tree/main/typescript/src/internals"

    %% Styles
    classDef workflow fill:#E0BBE4,stroke:#000,stroke-width:2px;
    classDef agent fill:#FDE4CF,stroke:#000,stroke-width:2px;
    classDef backend fill:#CFF09E,stroke:#000,stroke-width:2px;
    classDef adapter fill:#A0CED9,stroke:#000,stroke-width:2px;
    classDef tools fill:#FFDFD3,stroke:#000,stroke-width:2px;
    classDef memory fill:#FBC7C7,stroke:#000,stroke-width:2px;
    classDef emitter fill:#C1FFC1,stroke:#000,stroke-width:2px;
    classDef utility fill:#D0E6A5,stroke:#000,stroke-width:2px;
    classDef external fill:#FFC0CB,stroke:#000,stroke-width:2px;
```
