How aniketsarapai/supervisor-multi-agent works
1. Overall shape
This repo is a two-service Python application: a FastAPI backend handles auth, chat orchestration, persistence, and streaming; a Streamlit frontend provides the chat UI and login flow. The two services are intentionally separated and communicate over HTTP, with the frontend calling backend APIs through a configurable BACKEND_URL.
2. Client-facing boundary
The user interacts only with the Streamlit app. That UI is responsible for sign-in/sign-up, showing session history, sending chat requests, and consuming streamed responses. It does not run the agent logic itself; it is a thin presentation layer over backend APIs.
3. Backend API boundary
backend/fastapi_backend.py is the main service entry point. It exposes:
• public health and welcome endpoints,
• a token refresh endpoint,
• protected session/history endpoints,
• and the protected /chat_stream endpoint for real-time agent responses.
This is the main architectural boundary between external clients and the agent system.
4. Authentication and request protection
Auth is Supabase-based. The frontend uses Supabase auth for email/password sign-in. The backend validates incoming JWTs in backend/auth.py using Supabase issuer/audience/signing configuration, and protected routes require Authorization: Bearer <token>. This creates a clear trust boundary: only authenticated users can stream chats or access their session data.
5. Conversation orchestration core
The heart of the system is the LangGraph supervisor in backend/ai_agent.py, with supporting graph/state/tool definitions centralized in utils.py. The supervisor routes each user prompt to the best specialist agent rather than using one monolithic model. This is the key decision point in the architecture.
6. Specialist agents
The agent layer includes separate behaviors for greeting, query refinement, coding, math reasoning, and research. The supervisor delegates to one of these specialists based on the request. For an architecture diagram, this is best shown as one supervisor node feeding multiple specialist nodes, not as independent parallel services.
7. Tool execution layer
Specialist agents can invoke tools through the shared utility layer in utils.py. The tools include Tavily search, DuckDuckGo, Wikipedia, PubMed, a Python REPL, and a calculator via numexpr. This means the agent layer is not just model inference; it can branch into external knowledge and computation services when needed.
8. Streaming data flow
The primary runtime path is: Streamlit sends a chat request to FastAPI, FastAPI validates the JWT, resolves the session/thread, loads prior graph state, appends the user message, then streams LangGraph events back as server-sent events (SSE). The frontend incrementally renders partial output as it arrives. This is a one-way streaming architecture, not bidirectional WebSockets.
9. Session persistence
There are two persistence concerns. First, chat history is stored per authenticated user via Supabase-backed helpers in backend/supabase_database.py. Second, LangGraph state can be checkpointed either in-memory for simple local runs or in Postgres when SUPABASE_DB_URL is configured. So the app persists both user-visible conversation history and agent execution state.
10. Frontend responsibilities
frontend/streamlit_frontend.py owns the UX: login forms, session list/sidebar, message composer, and live stream rendering. It also persists individual chat messages through backend session APIs, rather than writing directly to the database. That keeps all database writes behind the backend boundary.
11. Deployment and runtime topology
The repo is designed for containerized deployment. Dockerfile.backend and Dockerfile.frontend build separate images, docker-compose.yml runs them locally, and cloudbuild.yaml builds and deploys both to Google Cloud Run. In Cloud Run, the backend is deployed first and its URL is injected into the frontend as BACKEND_URL.
12. Operational dependencies
The architecture depends materially on external services: Supabase for auth and storage, OpenRouter (or optionally Groq/OpenAI) for model access, Tavily for web search, and optionally LangSmith for tracing. These are not incidental libraries; they define how the backend gets identity, model responses, tool access, and observability.
13. What to emphasize in a diagram
A useful diagram should show: user → Streamlit UI → FastAPI backend → JWT validation / session persistence → LangGraph supervisor → specialist agents → external tools/LLM provider → SSE stream back to UI. Supabase should appear as both auth provider and data store, and the optional Postgres checkpoint path should be shown separately from chat-history persistence.
14. Key architectural boundary
The most important boundary in the repo is between the presentation layer (Streamlit) and the agent/orchestration layer (FastAPI + LangGraph). Everything important about trust, persistence, streaming, and tool usage lives on the backend side, while the frontend remains mostly a stateful consumer of backend APIs.
Main entry points: utils.py Tools · ai_agent.py Supervisor · fastapi_backend.py API server · streamlit_frontend.py Chat UI
Components 21
Frontend
Streamlit presentation layer and chat UX
- Chat UI · Login, session list, message composer, and live response rendering
frontend/streamlit_frontend.py
Backend
FastAPI API, auth, orchestration, and persistence
- API server · Main HTTP boundary for auth, history, and chat streaming
backend/fastapi_backend.py - JWT auth · Validates Supabase-issued bearer tokens for protected routes
backend/auth.py - Session store · Persists user-visible chat history and session metadata
backend/supabase_database.py - Supervisor · Routes each prompt to the best specialist agent
backend/ai_agent.py - Graph state · Shared message/state definitions and checkpointing setup
utils.py - Greeting · Handles friendly openings and simple conversational turns
backend/ai_agent.py - Refiner · Rewrites or clarifies user questions before deeper handling
backend/ai_agent.py - Coding · Supports programming and code-oriented requests
backend/ai_agent.py - Math · Performs reasoning and calculation-heavy tasks
backend/ai_agent.py - Research · Answers with search-backed and source-backed assistance
backend/ai_agent.py - Tools · Shared external tools for search, lookup, and computation
utils.py
External services
Identity, model, search, and observability dependencies
- Model API · OpenRouter or alternate model backend used by agents
- Supabase · Email/password auth, JWT issuer, and application data storage
- Search APIs · Tavily, DuckDuckGo, Wikipedia, and PubMed lookups
- Python exec · Python REPL and numexpr-based calculation support
Deployment
Container and cloud runtime entrypoints
- Backend image · Built backend runtime for Cloud Run or local compose
Dockerfile.backend - Frontend image · Built frontend runtime for Cloud Run or local compose
Dockerfile.frontend - Compose · Runs backend and frontend together for local development
docker-compose.yml - Cloud build · Builds and deploys both services to Cloud Run
cloudbuild.yaml
Other components
- User · Signs in and chats through the UI
Connections 27
- User → Chat UI: uses · User interacts with the chat application
- Chat UI → API server: HTTP API · Frontend sends login, session, and chat requests to the backend
- API server → JWT auth: protects · Protected routes validate bearer tokens before access
- JWT auth → Supabase: verifies · JWT issuer, audience, and signing config come from Supabase
- API server → Session store: reads/writes · Stores and fetches user-visible session history
- API server → Supervisor: streams · Requests are handed to the LangGraph supervisor for orchestration
- Supervisor → Graph state: uses · Supervisor loads state and checkpointing context
- Supervisor → Greeting: routes to · Delegates simple conversational turns
- Supervisor → Refiner: routes to · Delegates query clarification and rewriting
- Supervisor → Coding: routes to · Delegates programming tasks
- Supervisor → Math: routes to · Delegates reasoning and calculation tasks
- Supervisor → Research: routes to · Delegates research-oriented tasks
- Greeting → Tools: may call · Specialists can use shared tools when needed
- Refiner → Tools: may call · Specialists can use shared tools when needed
- Coding → Tools: may call · Specialists can use shared tools when needed
- Math → Tools: may call · Specialists can use shared tools when needed
- Research → Tools: may call · Specialists can use shared tools when needed
- Tools → Model API: uses · Agents obtain model responses from the configured provider
- Tools → Search APIs: uses · Research tools query external knowledge sources
- Tools → Python exec: uses · Math and code tools execute local computation
- API server → Supabase: history/auth data · Backend persists user-related data through Supabase-backed helpers
- Chat UI → API server: SSE stream · Frontend consumes streamed chat events incrementally
- Compose → Backend image: runs · Local composition includes the backend service image
- Compose → Frontend image: runs · Local composition includes the frontend service image
- Cloud build → Backend image: builds · CI builds and deploys the backend container
- Cloud build → Frontend image: builds · CI builds and deploys the frontend container
- Frontend image → API server: BACKEND_URL · Frontend runtime targets the deployed backend over HTTP