# langchain-ai/oap-agent-supervisor architecture

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

- Interactive diagram: https://gitdiagram.com/langchain-ai/oap-agent-supervisor
- Repository: https://github.com/langchain-ai/oap-agent-supervisor

## Overview

##### Project type and purpose
- This is a backend “supervisor” microservice built on top of LangGraph.
- It exposes a LangGraph server that authenticates incoming requests, accepts user messages, and either answers them itself via an LLM or delegates them to specialized child agents (deployed elsewhere on the Open Agent Platform).

##### File structure
- Top‐level files:
- `.env.example`, `pyproject.toml`, `Makefile` → environment, packaging, and build/config scripts
- `langgraph.json` → graph definition used by LangGraph CLI
- Package `oap_supervisor/`:
- `agent.py` → main GraphConfigPydantic class and supervisor logic
- `security/auth.py` → custom authentication handler using Supabase

##### README for additional insights
- Describes dynamic delegation patterns, system prompt configuration, and Supabase‐based JWT authentication.
- Explains that the service sits on LangGraph server and uses RemoteGraph to call child agents.

##### Main components
a. Client (or OAP front‐end / CLI)
b. LangGraph Server hosting the Supervisor Graph
c. Authentication middleware (Supabase JWT verification)
d. Supervisor Agent logic (inside `agent.py`)
e. LLM Provider (default: OpenAI)
f. RemoteGraph invocation to Child Agents
g. Child Specialist Agents (hosted on OAP / LGP)
h. Configuration layer (`langgraph.json`, `GraphConfigPydantic`)

##### Relationships and data flow
1. Client → HTTP/WebSocket → LangGraph Server
2. LangGraph Server → Auth middleware → Supabase (verify JWT)
3. Auth middleware → LangGraph Server → Supervisor Graph
4. Supervisor Graph →
- Either call OpenAI LLM directly for response
- Or call RemoteGraph tool → remote child‐agent graph → child agent LLM → return result
5. Supervisor Graph returns final response back through LangGraph Server → Client

##### Architectural patterns and design principles
- Microservice style: single‐purpose supervisor service
- Plugin/delegation pattern: uses LangGraph “tools” to invoke specialist agents
- Configuration‐as‐code: all agent wiring lives in `GraphConfigPydantic` plus `langgraph.json`
- Secure by default: JWT‐based auth middleware, environment‐driven secrets

##### Technologies, frameworks, and libraries
- Python + LangChain LangGraph Supervisor
- Pydantic for config
- Supabase for auth
- OpenAI (or pluggable LLMs)
- LangGraph CLI & server (dev via `uv run langgraph dev`)

##### Don’t overthink—capture every moving part
- Both in‐process operations (direct LLM calls) and out‐of‐process delegations (RemoteGraph to OAP)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    Client["Client (OAP Frontend/CLI)"]:::external
    LGServer["LangGraph Server"]:::orchestration
    Auth["Authentication Middleware<br/>(Supabase JWT verification)"]:::auth
    Supabase["Supabase Auth Service"]:::external
    Supervisor["Supervisor Agent Logic<br/>(GraphConfigPydantic)"]:::orchestration
    LLM["LLM Provider<br/>(OpenAI default)"]:::external
    RemoteGraph["RemoteGraph Tool"]:::orchestration
    ChildAgents["Child Specialist Agents<br/>(OAP/LGP)"]:::external
    ConfigFiles["Configuration Layer"]:::config
    Env["Environment & Secrets<br/>(.env.example)"]:::config
    Build["Build & Run Scripts<br/>(Makefile)"]:::config
    Packaging["Project Packaging & Dependencies<br/>(pyproject.toml)"]:::config
    GraphDef["LangGraph Graph Definition<br/>(langgraph.json)"]:::config

    %% Flow
    Client -->|"HTTP/WebSocket"| LGServer
    LGServer -->|"authenticate"| Auth
    Auth -->|"verify JWT"| Supabase
    Auth -->|"JWT valid"| LGServer
    LGServer -->|"invoke"| Supervisor
    Supervisor -->|"LLM query/response"| LLM
    Supervisor -->|"invoke RemoteGraph tool"| RemoteGraph
    RemoteGraph -->|"calls"| ChildAgents
    ChildAgents -->|"response"| RemoteGraph
    RemoteGraph -->|"result"| Supervisor
    LLM -->|"response"| Supervisor
    Supervisor -->|"final response"| LGServer
    LGServer -->|"response"| Client

    %% Configuration relationships
    Supervisor -->|"uses config"| GraphDef
    Supervisor -->|"config class"| Supervisor
    ConfigFiles --> Env
    ConfigFiles --> Build
    ConfigFiles --> Packaging
    ConfigFiles --> GraphDef

    %% Click events
    click Auth "https://github.com/langchain-ai/oap-agent-supervisor/blob/main/oap_supervisor/security/auth.py"
    click Supervisor "https://github.com/langchain-ai/oap-agent-supervisor/blob/main/oap_supervisor/agent.py"
    click GraphDef "https://github.com/langchain-ai/oap-agent-supervisor/blob/main/langgraph.json"
    click Env "https://github.com/langchain-ai/oap-agent-supervisor/blob/main/.env.example"
    click Build "https://github.com/langchain-ai/oap-agent-supervisor/tree/main/Makefile"
    click Packaging "https://github.com/langchain-ai/oap-agent-supervisor/blob/main/pyproject.toml"

    %% Styles
    classDef auth fill:#a3be8c,stroke:#2e3440,color:#2e3440
    classDef orchestration fill:#81a1c1,stroke:#2e3440,color:#2e3440
    classDef external fill:#ebcb8b,stroke:#2e3440,color:#2e3440
    classDef config fill:#d8dee9,stroke:#2e3440,color:#2e3440
```
