# msdllcpapers/teal-agents architecture

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

- Interactive diagram: https://gitdiagram.com/msdllcpapers/teal-agents
- Repository: https://github.com/msdllcpapers/teal-agents

## Overview

##### Project type and purpose
- Type: Full‑stack, microservices‑style platform for composing AI agents.
- Purpose:
– Core Agent Framework (src/sk‑agents) as a reusable library.
– Multiple “orchestrator” services (assistant, collab, workflow) that coordinate agents, backed by supporting microservices.

##### File structure
- Top‑level Dockerfiles and Makefile: used to build container images for each orchestrator and the core library.
- shared/ska_utils: shared utility library for configuration, telemetry, module loading.
- src/sk‑agents: Python library for building and invoking agents (plugin loader, chat completion factories, middleware).
- src/orchestrators/*: three orchestrators, each containing:
– an orchestrator service (Python FastAPI app, WebSocket endpoints, config loader, conversation management)
– example directories with Docker Compose, API gateway (Kong), data stores (DynamoDB), frontends (React or HTML).
– supporting “services” sub‑folder in assistant orchestrator (auth, data, telemetry).

##### Key README insights
- Core Agent Framework → reusable SDK supporting custom plugins, factories, and middleware.
- Orchestrators → define patterns for grouping agents, expose HTTP/WebSocket APIs, rely on shared components.

##### Main components
a. Client Layer
– React Web App (assistant orchestrator example)
– HTML/JS client (collab orchestrator example)
b. API Gateway
– Kong (routes HTTP/WebSocket traffic to orchestrator and services)
c. Orchestrator Services (per orchestrator)
– AssistantOrchestrator FastAPI service
– CollabOrchestrator service
– WorkflowOrchestrator service
d. Supporting Microservices (assistant orchestrator)
– Auth Service (authenticator)
– Data Service (chat history, context, tickets backed by DynamoDB)
– Ska Services (wrapper around sk‑agents core, custom services)
e. Core Agent Framework
– sk‑agents library (plugin loader, chat completion factory, agent builder)
f. Shared Utilities
– ska_utils (config loader, telemetry, singleton, standardized dates)
g. Data Stores
– AWS DynamoDB tables (chat_history, context, tickets)
– Redis (state store, if used in workflow orchestrator examples)
h. External Services / Plugins
– Weather, Math, Recipient, Test agents (invoked via HTTP or plugin APIs)
– Remote plugin catalog (OpenAPI definitions)
i. Infrastructure / DevOps
– Docker, Docker Compose files, Makefile for building all images
– GitHub Actions workflows for CI/CD

##### Relationships and data flows
- Orchestrator → Auth Service to validate requests
- Orchestrator → Data Service to read/write chat history and user context
- Orchestrator → sk‑agents library to load/invoke agents (local or remote)
- sk‑agents → External Services (weather, math, etc.) via custom plugins
- Data Service → DynamoDB (CRUD operations)
- Telemetry middleware logs events to telemetry backend
- Docker Compose groups orchestrator + Kong + DynamoDB local + frontend

##### Architectural patterns and principles
- Microservices: each service has a single responsibility (auth, data, orchestrator).
- Plugin architecture: dynamic loading of agents via config files and module_loader.
- Separation of concerns: UI layer, API gateway, backend services, data stores.
- Middleware layers: telemetry, authentication, context management.
- Infrastructure as code: YAML configs for Docker Compose, Kong, AWS (via local emulation).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        React["React Web App"]:::ui
        HTML["HTML/JS Client"]:::ui
    end

    %% API Gateway
    subgraph "API Gateway"
        KongAssistant["Kong (Assistant)"]:::gateway
        KongCollab["Kong (Collab)"]:::gateway
        KongWorkflow["Kong (Workflow)"]:::gateway
    end

    %% Orchestrator Stacks
    subgraph "Assistant Orchestrator Stack"
        AO["AssistantOrchestrator Service"]:::service
        Auth["Auth Service"]:::service
        DataSvc["Data Service"]:::service
        SkaSvc["Ska Services Wrapper"]:::service
        DynamoDB["DynamoDB Tables"]:::db
        AO --> Auth
        AO --> DataSvc
        AO --> SkaLib
        DataSvc --> DynamoDB
    end

    subgraph "Collab Orchestrator Stack"
        CO["CollabOrchestrator Service"]:::service
        CO --> SkaLib
        CO --> Redis
    end

    subgraph "Workflow Orchestrator Stack"
        WO["WorkflowOrchestrator Service"]:::service
        WO --> SkaLib
        WO --> Redis
    end

    %% Core Framework & Shared Utils
    subgraph "Core Framework"
        SkaLib["sk-agents Library"]:::core
    end
    subgraph "Shared Utilities"
        Utils["ska_utils"]:::util
    end
    SkaLib --> Utils

    %% Data Stores
    subgraph "Data Stores"
        Redis["Redis State Store"]:::db
    end

    %% External Services / Plugins
    subgraph "External Services / Plugins"
        Weather["Weather Agent"]:::external
        Math["Math Agent"]:::external
        Recip["Recipient Agent"]:::external
        Test["Test Agent"]:::external
    end
    SkaLib --> Weather
    SkaLib --> Math
    SkaLib --> Recip
    SkaLib --> Test

    %% Infrastructure / DevOps
    subgraph "Infrastructure / DevOps"
        Docker["Docker / Compose"]:::infra
        Make["Makefile"]:::infra
        CI["CI/CD Workflows"]:::infra
    end

    %% Flows
    React -->|HTTP/WebSocket| KongAssistant
    HTML -->|HTTP/WebSocket| KongCollab
    KongAssistant -->|routes to| AO
    KongCollab -->|routes to| CO
    KongWorkflow -->|routes to| WO

    %% Click Events
    click React "https://github.com/msdllcpapers/teal-agents/tree/main/src/orchestrators/assistant-orchestrator/example/client"
    click HTML "https://github.com/msdllcpapers/teal-agents/blob/main/src/orchestrators/collab-orchestrator/orchestrator/example/client/client.html"
    click KongAssistant "https://github.com/msdllcpapers/teal-agents/blob/main/src/orchestrators/assistant-orchestrator/example/kong/kong.yaml"
    click KongCollab "https://github.com/msdllcpapers/teal-agents/blob/main/src/orchestrators/collab-orchestrator/orchestrator/example/kong/kong.yaml"
    click KongWorkflow "https://github.com/msdllcpapers/teal-agents/blob/main/src/orchestrators/workflow-orchestrator/examples/03_agents_basic/kong/kong.yaml"
    click AO "https://github.com/msdllcpapers/teal-agents/tree/main/src/orchestrators/assistant-orchestrator/orchestrator"
    click CO "https://github.com/msdllcpapers/teal-agents/blob/main/src/orchestrators/collab-orchestrator/orchestrator/src/collab_orchestrator/app.py"
    click WO "https://github.com/msdllcpapers/teal-agents/blob/main/src/orchestrators/workflow-orchestrator/orchestrator/src/workflow_orchestrator/app.py"
    click Auth "https://github.com/msdllcpapers/teal-agents/blob/main/src/orchestrators/assistant-orchestrator/services/auth/authenticator.py"
    click DataSvc "https://github.com/msdllcpapers/teal-agents/tree/main/src/orchestrators/assistant-orchestrator/services/data"
    click SkaSvc "https://github.com/msdllcpapers/teal-agents/blob/main/src/orchestrators/assistant-orchestrator/services/ska_services.py"
    click SkaLib "https://github.com/msdllcpapers/teal-agents/tree/main/src/sk-agents/src/sk_agents"
    click Utils "https://github.com/msdllcpapers/teal-agents/tree/main/shared/ska_utils/src/ska_utils"
    click DynamoDB "https://github.com/msdllcpapers/teal-agents/blob/main/src/orchestrators/assistant-orchestrator/services/data/impl/dynamo_chat_history_manager.py"
    click Redis "https://github.com/msdllcpapers/teal-agents/blob/main/src/orchestrators/workflow-orchestrator/examples/components/state_redis.yaml"
    click Weather "https://github.com/msdllcpapers/teal-agents/blob/main/src/orchestrators/assistant-orchestrator/example/weather/config.yaml"
    click Math "https://github.com/msdllcpapers/teal-agents/blob/main/src/orchestrators/assistant-orchestrator/example/math/config.yaml"
    click Recip "https://github.com/msdllcpapers/teal-agents/blob/main/src/orchestrators/assistant-orchestrator/example/recipient/config.yaml"
    click Test "https://github.com/msdllcpapers/teal-agents/tree/main/src/orchestrators/assistant-orchestrator/example/test-agent/"
    click Docker "https://github.com/msdllcpapers/teal-agents/blob/main/ao-services.Dockerfile"
    click Make "https://github.com/msdllcpapers/teal-agents/tree/main/Makefile"
    click CI "https://github.com/msdllcpapers/teal-agents/blob/main/.github/workflows/build-and-push-ao-services.yaml"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,color:#000
    classDef gateway fill:#90EE90,stroke:#000,color:#000
    classDef service fill:#32CD32,stroke:#000,color:#000
    classDef core fill:#98FB98,stroke:#000,color:#000
    classDef util fill:#ADFF2F,stroke:#000,color:#000
    classDef db fill:#FFA500,stroke:#000,color:#000
    classDef external fill:#FF6347,stroke:#000,color:#000
    classDef infra fill:#D3D3D3,stroke:#000,color:#000
```
