# shubhamsaboo/multi-agent-orchestrator architecture

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

- Interactive diagram: https://gitdiagram.com/shubhamsaboo/multi-agent-orchestrator
- Repository: https://github.com/shubhamsaboo/multi-agent-orchestrator

## Overview

##### Project Type & Purpose
- The project is an open-source framework that orchestrates multiple AI agents to handle complex conversations. It supports both Python and TypeScript implementations, offering pre-built agents, classifiers, context management, and integrations with external APIs (e.g., Amazon Bedrock, Lex Bot, Anthropic, OpenAI) for intelligent routing and collaborative agent execution.
- The README emphasizes advanced use cases such as multi-turn conversations, team coordination via the SupervisorAgent, and various deployment targets (local, cloud, AWS Lambda, etc).

##### File Structure
- Notice separate folders for different languages (“python” and “typescript”) that each implement similar orchestrator logic (agents, classifiers, storage, retrievers).
- A comprehensive “docs” directory indicates a strong emphasis on documentation and developer guides, while “examples” contains multiple demo applications (chat apps, ecommerce simulators, FastAPI streaming, etc) that illustrate how the orchestration works in various environments.
- The centralized core module (e.g., within python/src/multi_agent_orchestrator and typescript/src) includes components for agents, classifiers, retrievers, storage, and utility functions—indicating a modular and extensible architecture.

##### Key Components to Model
a. Core Orchestrator:
- Central routing logic: Accepts user input, invokes classifiers to decide which agent should handle the request, and manages conversation context.

b. Agent Components:
- The SupervisorAgent should be distinctly highlighted to showcase its role in coordinating multiple subordinate agents.

c. Classifier Module:
- Component that analyzes incoming requests to dynamically select the right agent based on conversation history and agent characteristics.

d. Conversation & Context Management:
- Components for “Conversation History” or “Context Management,” showing how state is maintained across multiple interactions.

e. Storage & Retrievers:

f. External Integrations:
- External APIs and services (such as AWS services for Amazon Bedrock, Lex, Lambda functions or even external endpoints for Anthropic/OpenAI etc).

g. Demo Apps & Clients:
- How example applications (e.g., chat-demo-app, ecommerce-support-simulator, FastAPI streaming) interface with the orchestrator. This can be represented as client/user interfaces interacting with the orchestrator.

##### Relationships & Data Flows
- User input → Classifier → Agent Selection → Agent processing → Context storage update → Response to user.
- Potential callbacks for streaming responses.

##### Architectural Patterns and Principles
- Modular/extensible design: Each agent module registers with the orchestrator; new agents can be added seamlessly.
- Separation of concerns: Distinct boundaries between routing, processing, storage, and external service communication.
- For the SupervisorAgent’s “agent-as-tools” model, demonstrate the hierarchy where one lead agent orchestrates multiple parallel subordinate agents.

##### Technologies & Languages
- Integration with AWS services (Amazon Bedrock, Lambda, etc.) and third-party APIs.
- Tools such as Jest, Astro, and CDK (visible in examples) can be annotated as supporting development or deployment pipelines.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User & Clients Layer
    subgraph "User & Clients"
        U["User"]:::client
        PD["Python Demo Apps"]:::client
        TD["TypeScript Demo Apps"]:::client
    end

    %% Core Framework Layer
    subgraph "Core Framework"
        O["Multi-Agent Orchestrator"]:::core
        C["Classifier Module"]:::core
        subgraph "Agents"
            PA["Python Agents"]:::agent
            TA["TypeScript Agents"]:::agent
            SPA["SupervisorAgent (Python)"]:::agentSpecial
            STA["SupervisorAgent (TypeScript)"]:::agentSpecial
        end
        CS["Conversation & Context (Chat Storage)"]:::storage
        ST["Storage"]:::storage
        R["Retrievers"]:::storage
    end

    %% External Integrations Layer
    subgraph "External Integrations"
        EI["External APIs (AmazonBedrock,Lex,Lambda,Anthropic,OpenAI)"]:::external
    end

    %% Data Flow Connections
    U -->|"sends_input"| O
    PD -->|"routes_to"| O
    TD -->|"routes_to"| O

    O -->|"classifies"| C
    O -->|"routes_to_agents"| PA
    O -->|"routes_to_agents"| TA
    C -->|"selects_agent"| PA
    C -->|"selects_agent"| TA

    PA -->|"delegates"| SPA
    TA -->|"delegates"| STA

    SPA -->|"calls_external"| EI
    STA -->|"calls_external"| EI
    PA -->|"calls_external"| EI
    TA -->|"calls_external"| EI

    PA -->|"updates_context"| CS
    TA -->|"updates_context"| CS
    O -->|"updates_context"| CS

    CS -->|"persists_in"| ST
    CS -->|"retrieves_from"| R
    CS -->|"responds_to"| U

    %% Click Events for Core Components and Mapped Files
    %% Core Orchestrator
    click O "https://github.com/shubhamsaboo/multi-agent-orchestrator/blob/main/python/src/multi_agent_orchestrator/orchestrator.py"
    click O "https://github.com/shubhamsaboo/multi-agent-orchestrator/blob/main/typescript/src/orchestrator.ts"

    %% Agent Components
    click PA "https://github.com/shubhamsaboo/multi-agent-orchestrator/tree/main/python/src/multi_agent_orchestrator/agents"
    click TA "https://github.com/shubhamsaboo/multi-agent-orchestrator/tree/main/typescript/src/agents"

    %% SupervisorAgent
    click SPA "https://github.com/shubhamsaboo/multi-agent-orchestrator/blob/main/python/src/multi_agent_orchestrator/agents/supervisor_agent.py"
    click STA "https://github.com/shubhamsaboo/multi-agent-orchestrator/blob/main/typescript/src/agents/supervisorAgent.ts"

    %% Classifier Module
    click C "https://github.com/shubhamsaboo/multi-agent-orchestrator/tree/main/python/src/multi_agent_orchestrator/classifiers"
    click C "https://github.com/shubhamsaboo/multi-agent-orchestrator/tree/main/typescript/src/classifiers"

    %% Conversation & Context Management (Chat Storage)
    click CS "https://github.com/shubhamsaboo/multi-agent-orchestrator/blob/main/python/src/multi_agent_orchestrator/storage/chat_storage.py"
    click CS "https://github.com/shubhamsaboo/multi-agent-orchestrator/blob/main/typescript/src/storage/chatStorage.ts"

    %% Storage & Retrievers
    click ST "https://github.com/shubhamsaboo/multi-agent-orchestrator/tree/main/python/src/multi_agent_orchestrator/storage"
    click ST "https://github.com/shubhamsaboo/multi-agent-orchestrator/tree/main/typescript/src/storage"
    click R "https://github.com/shubhamsaboo/multi-agent-orchestrator/tree/main/python/src/multi_agent_orchestrator/retrievers"
    click R "https://github.com/shubhamsaboo/multi-agent-orchestrator/tree/main/typescript/src/retrievers"

    %% Demo Apps & Clients
    click PD "https://github.com/shubhamsaboo/multi-agent-orchestrator/tree/main/examples/python"
    click PD "https://github.com/shubhamsaboo/multi-agent-orchestrator/tree/main/examples/python-demo"
    click PD "https://github.com/shubhamsaboo/multi-agent-orchestrator/tree/main/examples/supervisor-mode"
    click TD "https://github.com/shubhamsaboo/multi-agent-orchestrator/tree/main/examples/chat-demo-app"
    click TD "https://github.com/shubhamsaboo/multi-agent-orchestrator/tree/main/examples/ecommerce-support-simulator"
    click TD "https://github.com/shubhamsaboo/multi-agent-orchestrator/tree/main/examples/fast-api-streaming"
    click TD "https://github.com/shubhamsaboo/multi-agent-orchestrator/tree/main/examples/local-demo"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef agent fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef agentSpecial fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef storage fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef client fill:#fefefe,stroke:#333,stroke-width:2px;
```
