🤖 OrchAgent: Hierarchical Multi-Agent Platform

OrchAgent is a hierarchical multi-agent workspace built around LangGraph, FastAPI, and Next.js. It routes requests through a Head Supervisor -> Team Supervisor -> Worker structure and exposes reasoning summaries, tool activity, routing, and checkpoints in real time.

🌐 Try OrchAgent now — no setup required → orchagent.vercel.app The hosted product page walks through the orchestration workspace, HITL flow, and live SSE telemetry. Open it from any browser to see what the platform does before cloning the repo.

---

✨ What It Does

• 🧩 Hierarchical Orchestration: A head supervisor delegates to specialized research, writing, and vision team subgraphs, and each team routes work to its own workers.
• 🛡️ HITL & Validation:
  • Interactive Interruption: Head-level routing can pause for human approval, rejection, or feedback before resuming the same thread.
  • Self-Correction Loop: Team validators review worker outputs and send failures back through the supervisor with correction feedback.
• 🖼️ Multimodal Input Path: Text requests can include images, which are routed to the vision team and processed with model-native vision plus image metadata and resize tools.
• 🛠️ Tool-Aware Workers: Research, writing, and vision workers run with task-specific tools, and the worker layer is structured to support state-driven tool filtering.
• 💎 Agentic UI:
  • Real-time SSE streaming for status, route, reasoning, tool, text, and checkpoint events.
  • A workspace UI that shows internal progress instead of only the final answer.
  • Resume controls for HITL actions.
• ⏱️ Trace & Session Logging:
  • SQL-backed trace events for execution replay and inspection.
  • Separate .jsonl session and usage logs for lightweight telemetry.
• ✅ Reliability Work:
  • Backend tests covering workflow compilation, SSE contracts, validator edge cases, resume behavior, disconnect handling, and trace persistence.
  • Frontend build verification and SSE parser tests for stream handling.

---

🎯 Current Scope

This repository is best described as an advanced prototype focused on orchestration, observability, and recovery.

• Strong today: hierarchical routing, normalized SSE streaming, checkpoint/resume, validator loops, traceability, and a dedicated agent workspace UI.
• Still being hardened: authentication, stricter tool sandboxing, production policy controls, and some frontend/runtime configuration cleanup.

---

🏗️ System Architecture

graph TD
    User((User)) -->|Multimodal Request / Feedback| API[FastAPI Backend]
    API -->|Orchestrate| Head[Head Supervisor]
    Head -.->|Interrupts for Approval| User

    %% Final Synthesis Path
    Head --> Finalizer[Finalizer / Synthesizer]
    Finalizer -->|Final Answer| API

    subgraph Vision Team
        Head --> VS[Vision Supervisor]
        VS --> VAnalyst[Vision Analyst]
        VAnalyst --> VTools[Metadata/Resize Tools]
        VAnalyst -.->|Validates Output| VValidator[Vision Validator]
        VValidator -.->|Self-Correction| VS
        VS -.->|FINISH| Head
    end

    subgraph Research Team
        Head --> RS[Research Supervisor]
        RS --> Search[Tavily Search]
        RS --> Scraper[Web Scraper]
        Search -.->|Validates Output| RValidator[Research Validator]
        Scraper -.-> RValidator
        RValidator -.->|Self-Correction| RS
        RS -.->|FINISH| Head
    end

    subgraph Writing Team
        Head --> WS[Writing Supervisor]
        WS --> Writer[Doc Writer]
        WS --> Noter[Note Taker]
        WS --> Chart[Chart Generator]
        Writer -.->|Validates Output| WValidator[Writing Validator]
        WValidator -.->|Self-Correction| WS
        WS -.->|FINISH| Head
    end

    API -->|SSE Stream| UI[Next.js Frontend]
    UI -->|Reasoning, Tools & Interventions| Dashboard[Agentic Workspace]

Loading

---

📂 Project Structure

Path	Description
apps/backend	FastAPI server for LangGraph execution, SSE streaming, resume endpoints, trace persistence, and session logging
apps/backend/services/streaming/	Ownership-aware SSE collector + payload builders (response_collector.py, event_processor.py, event_utils.py)
apps/backend/services/orchestration_service.py	Single seam between the chat route and agent_core/workflow/agent_tools
apps/backend/services/event_recording_service.py	Façade over JSONL session logs
apps/backend/schemas/{turn,message}.py	Pydantic response shapes for ChatTurn and chat-message rows
apps/frontend	Next.js 16 agent workspace UI with chat, tool activity, reasoning, timeline, and HITL controls
apps/frontend/src/lib/cn.ts	Shared cn(...) class-name helper (clsx + tailwind-merge)
packages/agent-core	Shared orchestration primitives: state schema, supervisor logic, team builder, validator nodes
packages/agent-core/src/agent_core/{config,router_schema,safeguards,fallback_messages}.py	LLM-Driven Routing infra: SAFEGUARDS constants, RouterDecision schema, safeguard helpers, centralised user-facing fallback strings
packages/agent-tools	Shared worker tools for web research, document I/O, Python execution, and image utilities
packages/agent-tools/src/agent_tools/{config,errors}.py	Unified tool timeouts (TIMEOUTS) + ToolErrorPayload envelope
packages/prompt-kit	Prompt templates for worker personas and team behavior
packages/prompt-kit/src/prompt_kit/fragments.py	Reusable prompt fragments (CRITICAL_GUIDELINES, WORKER_CONSTRAINTS, ROUTER_DECISION_GUIDANCE)
infra/scripts/{capture,diff}_baseline.sh	Refactor verification scripts (plan §1.2/§1.5)
docs/	Architectural recommendations and research reports
plans/	Project roadmap and detailed feature implementation plans

---

🚀 Quick Start

1. Environment Setup

Create an .env file in the apps/backend directory and set up your API keys.

# apps/backend/.env
OPENAI_API_KEY=your_openai_api_key
TAVILY_API_KEY=your_tavily_api_key

2. Run with Docker

The easiest way to spin up the entire stack:

./infra/scripts/start-dev.sh

This compose stack runs in development mode with bind mounts and autoreload. Changes under apps/backend, apps/frontend, and packages/* are reflected without rebuilding containers. Rebuild the stack only when dependencies, lockfiles, or Dockerfiles change. The frontend container may run npm install on first boot to populate its dev node_modules volume.

3. Backend Development & Testing (Local)

cd apps/backend
uv sync
uv run pytest tests/ -v
uv run uvicorn main:app --reload --port 8002

4. Frontend Development (Local)

cd apps/frontend
npm install
npm run dev

5. Frontend Verification

cd apps/frontend
node --test src/lib/chat-stream.test.mjs
npm run build

6. Container Logs

docker compose -f infra/compose/docker-compose.yml logs -f backend
docker compose -f infra/compose/docker-compose.yml logs -f frontend

---

📄 License

This project is licensed under the MIT License.

---

Developed with precision by DONGRYEOLLEE