# saadbenchekroun/multi-agent-orchestration architecture

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

- Interactive diagram: https://gitdiagram.com/saadbenchekroun/multi-agent-orchestration
- Repository: https://github.com/saadbenchekroun/multi-agent-orchestration

## Overview

##### Project Type and Purpose
- This is a Python-based, back-end automation system using a “multi-agent” architecture.
- Its goal is to orchestrate specialized AI agents (customer support, sales, development, marketing, admin, design, finance) under a central orchestrator, integrating with external business systems via connectors, persisting context in a vector memory store, and scheduling/prioritizing tasks.

##### File Structure
- Top‐level entry points:
- main.py – CLI entry for launching the agent system, generating config, running as daemon, etc.
- cli.py – Command‐line interface for task management (add/list tasks, view performance).
- Configuration:
- config_generator.py – Utility to scaffold a default config.yaml
- config.yaml – YAML config for API keys, agent settings, memory, connectors, scheduling
- Core modules (core/):
- system.py – AgentSystem main controller
- scheduler.py – Task scheduling, priority queues, recurring jobs
- memory.py – Vector DB store for agent context
- task.py – Task model (id, deps, priority, status)
- Agents (agents/):
- orchestrator.py – Top-level orchestrator agent coordinating workflows
- base.py – Agent base class, shared behaviors
- customer_support.py, sales.py, development.py, marketing.py, admin.py, design.py, finance.py – Domain-specific agents
- Connectors (connectors/):
- crm.py, slack.py, jira.py, github.py, figma.py, quickbooks.py, analytics.py – Integration wrappers for external services
- Tools (tools/):
- browser.py, calculator.py, search.py – Helper utilities invoked by agents for auxiliary tasks
- Other files:
- ok.py – Health check endpoint/verification script
- requirements.txt – Python dependencies

##### README for Additional Insights
- Multi‐agent pattern with a central AgentSystem
- Scheduling system (daily/hourly/weekly routines)
- Memory store for context persistence
- Robust error handling (retries, escalation)
- Monitoring & analytics

a. Main Components
1. User Interface (CLI)
2. Configuration Loader
3. Core AgentSystem
– Scheduler
– Memory Store
– Task Manager
4. Agent Layer
– Orchestrator Agent
– Domain Agents: Customer Support, Sales, Development, Marketing, Admin, Design, Finance
5. Connectors Layer
– External services: CRM, Slack, GitHub, Jira, Figma, QuickBooks, Analytics
6. Tools Layer
– Browser, Search, Calculator utilities
7. External Systems
– Actual business systems (CRM API, Slack channels, GitHub repos, etc.)
b. Relationships and Interactions
– CLI → Config Loader → AgentSystem
– AgentSystem ↔ Scheduler schedules Task objects
– AgentSystem ↔ Memory Store for context reads/writes
– AgentSystem dispatches tasks to individual Agents
– Agents invoke Tools and Connectors as needed
– Connectors communicate with External Systems (APIs)
– Agents report status back to AgentSystem (for error handling, retries, escalation)
– Monitoring/Analytics component subscribes to AgentSystem events
c. Architectural Patterns & Principles
– Multi-agent orchestration pattern (Orchestrator delegates to specialized agents)
– Modular layering: Core → Agents → Connectors → External Systems
– Separation of concerns: scheduling, memory, task management, business logic, integrations
– Retry and escalation flow for error handling
– Vector‐based memory for context persistence
d. Key Technologies & Frameworks
– Python 3.8+ with pyyaml, schedule
– Google Gemini models (AI inference)
– Vector DB for memory (configurable path in memory_settings)
– CLI powered by argparse / custom cli.py

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface"
        direction TB
        CLI_MAIN["main.py"]:::cli
        CLI_TOOL["cli.py"]:::cli
    end

    %% Configuration Layer
    subgraph "Configuration"
        direction TB
        CONFIG_GEN["config_generator.py"]:::config
        CONFIG_FILE["config.yaml"]:::config
    end

    %% Core Orchestration Layer
    subgraph "Core Orchestration"
        direction TB
        AGENT_SYSTEM["AgentSystem\n(core/system.py)"]:::core
        SCHEDULER["Scheduler\n(core/scheduler.py)"]:::core
        MEMORY_STORE["Vector Memory Store\n(core/memory.py)"]:::core
        TASK_MANAGER["Task Model/Manager\n(core/task.py)"]:::core
    end

    %% Agent Layer
    subgraph "Agent Layer"
        direction TB
        ORCHESTRATOR["Orchestrator Agent\n(agents/orchestrator.py)"]:::agent
        BASE_AGENT["Base Agent\n(agents/base.py)"]:::agent
        CS_AGENT["Customer Support Agent\n(agents/customer_support.py)"]:::agent
        SALES_AGENT["Sales Agent\n(agents/sales.py)"]:::agent
        DEV_AGENT["Development Agent\n(agents/development.py)"]:::agent
        MKT_AGENT["Marketing Agent\n(agents/marketing.py)"]:::agent
        ADMIN_AGENT["Admin Agent\n(agents/admin.py)"]:::agent
        DESIGN_AGENT["Design Agent\n(agents/design.py)"]:::agent
        FIN_AGENT["Finance Agent\n(agents/finance.py)"]:::agent
    end

    %% Connectors Layer
    subgraph "Connectors"
        direction TB
        CONN_INIT["connectors/__init__.py"]:::connector
        CRM_CONN["CRM Connector\n(connectors/crm.py)"]:::connector
        SLACK_CONN["Slack Connector\n(connectors/slack.py)"]:::connector
        JIRA_CONN["Jira Connector\n(connectors/jira.py)"]:::connector
        GH_CONN["GitHub Connector\n(connectors/github.py)"]:::connector
        FIGMA_CONN["Figma Connector\n(connectors/figma.py)"]:::connector
        QB_CONN["QuickBooks Connector\n(connectors/quickbooks.py)"]:::connector
        ANALYTICS_CONN["Analytics Connector\n(connectors/analytics.py)"]:::connector
    end

    %% External Systems Layer
    subgraph "External Business Systems"
        direction TB
        CRM_API["CRM API"]:::external
        SLACK_API["Slack API"]:::external
        JIRA_API["Jira API"]:::external
        GH_API["GitHub API"]:::external
        FIGMA_API["Figma API"]:::external
        QB_API["QuickBooks API"]:::external
        ANALYTICS_API["Analytics Service"]:::external
    end

    %% Tools Layer
    subgraph "Tools"
        direction TB
        TOOLS_INIT["tools/__init__.py"]:::tool
        BROWSER["Browser Tool\n(tools/browser.py)"]:::tool
        CALC["Calculator Tool\n(tools/calculator.py)"]:::tool
        SEARCH["Search Tool\n(tools/search.py)"]:::tool
    end

    %% Health & Dependencies
    OK["Health Check\n(ok.py)"]:::other
    REQS["requirements.txt"]:::other

    %% Monitoring & Analytics
    MONITOR["Monitoring & Analytics"]:::external

    %% Connections
    CLI_MAIN -->|uses| CONFIG_GEN
    CLI_TOOL -->|uses| CONFIG_FILE
    CONFIG_GEN -->|generates| CONFIG_FILE
    CONFIG_FILE -->|loads settings| AGENT_SYSTEM
    CONFIG_FILE -->|loads API keys| CONN_INIT

    AGENT_SYSTEM -->|schedules tasks| SCHEDULER
    AGENT_SYSTEM -->|manages tasks| TASK_MANAGER
    AGENT_SYSTEM -->|reads/writes context| MEMORY_STORE
    AGENT_SYSTEM -->|dispatches tasks| ORCHESTRATOR

    ORCHESTRATOR -->|delegates| CS_AGENT
    ORCHESTRATOR -->|delegates| SALES_AGENT
    ORCHESTRATOR -->|delegates| DEV_AGENT
    ORCHESTRATOR -->|delegates| MKT_AGENT
    ORCHESTRATOR -->|delegates| ADMIN_AGENT
    ORCHESTRATOR -->|delegates| DESIGN_AGENT
    ORCHESTRATOR -->|delegates| FIN_AGENT

    CS_AGENT -->|invokes| BROWSER
    SALES_AGENT -->|invokes| SEARCH
    DEV_AGENT -->|invokes| CALC
    MKT_AGENT -->|invokes| BROWSER
    ADMIN_AGENT -->|invokes| SEARCH
    DESIGN_AGENT -->|invokes| BROWSER
    FIN_AGENT -->|invokes| CALC

    CS_AGENT --> CRM_CONN
    SALES_AGENT --> SLACK_CONN
    DEV_AGENT --> GH_CONN
    DEV_AGENT --> JIRA_CONN
    DESIGN_AGENT --> FIGMA_CONN
    FIN_AGENT --> QB_CONN
    MKT_AGENT --> ANALYTICS_CONN

    CRM_CONN --> CRM_API
    SLACK_CONN --> SLACK_API
    JIRA_CONN --> JIRA_API
    GH_CONN --> GH_API
    FIGMA_CONN --> FIGMA_API
    QB_CONN --> QB_API
    ANALYTICS_CONN --> ANALYTICS_API

    AGENT_SYSTEM -->|emits events| MONITOR
    MONITOR -->|records metrics| ANALYTICS_CONN

    CS_AGENT -->|error| AGENT_SYSTEM
    SALES_AGENT -->|error| AGENT_SYSTEM
    DEV_AGENT -->|error| AGENT_SYSTEM
    MKT_AGENT -->|error| AGENT_SYSTEM
    ADMIN_AGENT -->|error| AGENT_SYSTEM
    DESIGN_AGENT -->|error| AGENT_SYSTEM
    FIN_AGENT -->|error| AGENT_SYSTEM

    OK -->|checks| AGENT_SYSTEM
    OK -->|checks| SCHEDULER

    %% Click Events
    click CLI_MAIN "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/main.py"
    click CLI_TOOL "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/cli.py"
    click CONFIG_GEN "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/config_generator.py"
    click CONFIG_FILE "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/config.yaml"
    click AGENT_SYSTEM "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/core/system.py"
    click SCHEDULER "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/core/scheduler.py"
    click MEMORY_STORE "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/core/memory.py"
    click TASK_MANAGER "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/core/task.py"
    click ORCHESTRATOR "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/agents/orchestrator.py"
    click BASE_AGENT "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/agents/base.py"
    click CS_AGENT "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/agents/customer_support.py"
    click SALES_AGENT "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/agents/sales.py"
    click DEV_AGENT "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/agents/development.py"
    click MKT_AGENT "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/agents/marketing.py"
    click ADMIN_AGENT "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/agents/admin.py"
    click DESIGN_AGENT "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/agents/design.py"
    click FIN_AGENT "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/agents/finance.py"
    click CONN_INIT "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/connectors/__init__.py"
    click CRM_CONN "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/connectors/crm.py"
    click SLACK_CONN "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/connectors/slack.py"
    click JIRA_CONN "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/connectors/jira.py"
    click GH_CONN "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/connectors/github.py"
    click FIGMA_CONN "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/connectors/figma.py"
    click QB_CONN "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/connectors/quickbooks.py"
    click ANALYTICS_CONN "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/connectors/analytics.py"
    click TOOLS_INIT "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/tools/__init__.py"
    click BROWSER "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/tools/browser.py"
    click CALC "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/tools/calculator.py"
    click SEARCH "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/tools/search.py"
    click OK "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/ok.py"
    click REQS "https://github.com/saadbenchekroun/multi-agent-orchestration/blob/main/requirements.txt"

    %% Styles
    classDef cli fill:#E8F1FA,stroke:#1E88E5,color:#1E88E5;
    classDef config fill:#FFF4E5,stroke:#FFA726,color:#EF6C00;
    classDef core fill:#E8F5E9,stroke:#43A047,color:#2E7D32;
    classDef agent fill:#F3E5F5,stroke:#8E24AA,color:#6A1B9A;
    classDef connector fill:#E1F5FE,stroke:#039BE5,color:#0277BD;
    classDef tool fill:#FFF3E0,stroke:#FB8C00,color:#EF6C00;
    classDef external fill:#ECEFF1,stroke:#546E7A,color:#37474F;
    classDef other fill:#F5F5F5,stroke:#BDBDBD,color:#616161;
```
