A production-grade monorepo portfolio of 10 progressive Agentic AI projects built on the LangChain / LangGraph / LangSmith / MCP stack. Designed as an industry-standard reference architecture covering single-agent ReAct loops, production RAG, cross-session memory, multi-agent supervisor hierarchies, human-in-the-loop (HITL) safety, Model Context Protocol (MCP) integrations, deep autonomous subagents, typed structured outputs, and automated evaluation harnesses.
The monorepo is architected around modular FastAPI agent services, a reusable Next.js 15 chat shell, and a shared Python infrastructure package (common) for model routing, streaming telemetry, and evaluation gates.
┌────────────────────────────────────────────────────────┐
│ apps/chat-ui (Next.js 15) │
│ • Token-by-token SSE streaming │
│ • Collapsible Tool Call Inspection Trees │
│ • Direct Deep Links to LangSmith Traces │
└───────────────────────────┬────────────────────────────┘
│ HTTP POST (SSE stream)
▼
┌────────────────────────────────────────────────────────┐
│ FastAPI Agent Service (/agents/*) │
│ • /v1/chat/completions (OpenAI-compatible) │
│ • StateGraph Execution & Checkpointing │
│ • Interrupt Handling & Resumption Endpoints │
└─────────────┬───────────────────────────┬──────────────┘
│ │
┌────────────────┴───────────────┐ │
▼ ▼ ▼
┌─────────────────────────────┐ ┌───────────────────────────┐ ┌───────────────────────────────┐
│ common.llm │ │ common.ui_bridge │ │ common.tracing │
│ • Multi-provider routing │ │ • Typed SSE event codec │ │ • LangSmith telemetry setup │
│ • OpenRouter / Ollama │ │ • token / tool / trace │ │ • Scoped project contexts │
└──────────────┬──────────────┘ └───────────────────────────┘ └───────────────┬───────────────┘
│ │
▼ ▼
┌─────────────────────────────┐ ┌───────────────────────────────┐
│ LLMs (Claude, GPT-4o, Llama)│ │ LangSmith Observability Platform│
└─────────────────────────────┘ └───────────────────────────────┘
| Project | Pattern | Core Technologies | Eval & Observability | Status |
|---|---|---|---|---|
| P0: Foundation & Smoke | Shared Infra Validation | FastAPI, SSE Bridge, Next.js 15, LangSmith | Unit + integration smoke tests | ✅ Completed |
| P1: ReAct Research Agent | Single-Agent Reasoning | create_react_agent, Tavily Search, OpenRouter |
30 multi-hop Q&A benchmark (94.7% recall) | ✅ Completed |
| P2: Production RAG | Retrieval & Reranking | Semantic Chunking, Qdrant, Cohere Rerank | Faithfulness & Context-Precision evals | ⏳ Planned |
| P3: Conversational Memory | Multi-Tier State Store | LangGraph MemorySaver + PostgreSQL Store |
20 multi-turn recall benchmarks | ⏳ Planned |
| P4: Multi-Agent Supervisor | Hierarchical Orchestration | LangGraph Subgraphs, Command handoffs |
15 collaborative research tasks | ⏳ Planned |
| P5: HITL Approval Workflow | Human-in-the-Loop Safety | LangGraph interrupt(), Resumable Checkpoints |
10 destructive mutation scenarios | ⏳ Planned |
| P6: MCP Tool Server | Protocol-Driven Tooling | Python mcp SDK, langchain-mcp-adapters |
12 cross-tool workflow evaluations | ⏳ Planned |
| P7: Deep Research Agent | Long-Horizon Autonomy | Parallel Send API, Context Offloading |
LLM-as-a-Judge report rubrics | ⏳ Planned |
| P8: Structured-Output Agent | Typed Schema Extraction | Pydantic v2, Retry Prompt Injection | 30 malformed input edge cases | ⏳ Planned |
| P9: Eval & Observability | CI/CD Quality Gates | LangSmith evaluate(), Trajectory Matching |
Meta-evals against human labels | ⏳ Planned |
| P10: Production Capstone | Full-Stack Deployment | Docker, FastAPI, Rate Limiting, Sentry | Locust load tests + online evals | ⏳ Planned |
LearnAgenticAI/
├── .github/
│ └── workflows/
│ ├── ci.yml # Python (uv, ruff, mypy, pytest) + TypeScript (vitest, typecheck, lint)
│ └── openwiki-update.yml # Automated documentation synchronization
├── agents/
│ ├── P0-smoke/ # Smoke validation agent (FastAPI + LangChain)
│ │ ├── src/P0_smoke/ # Server and agent graph implementation
│ │ ├── tests/ # Unit and integration test suites
│ │ └── pyproject.toml # Agent package definition
│ ├── P1-react-agent/ # Autonomous ReAct research agent (Tavily + web reading)
│ │ ├── src/P1_react_agent/ # ReAct graph, prompts, and SSE bridge
│ │ ├── data/ # 30-question multi-hop eval dataset
│ │ ├── tests/ # Unit, integration, and eval test suites
│ │ ├── eval.py # Offline evaluation CLI benchmark
│ │ └── pyproject.toml # Agent package definition
│ └── ... # P2 through P10 agent packages
├── apps/
│ └── chat-ui/ # Next.js 15 chat shell with Tailwind CSS & Lucide icons
│ ├── app/ # App Router pages and health routes
│ ├── components/ # ChatWindow, ToolCallTree, TraceLink, MessageBubble
│ ├── lib/ # API streaming client and TypeScript types
│ └── tests/ # Vitest test suite
├── common/ # Shared Python workspace package
│ ├── src/common/
│ │ ├── config.py # Pydantic BaseSettings environment configuration
│ │ ├── llm.py # Multi-model factory (OpenRouter, Ollama, OpenAI)
│ │ ├── tracing.py # LangSmith context manager and telemetry setup
│ │ ├── ui_bridge.py # Typed SSE event formatters (token, tool, trace)
│ │ └── tools/ # Shared search, filesystem, and data tools
│ └── tests/ # Unit tests for shared infrastructure
├── docker/
│ ├── docker-compose.yml # Local Postgres (pgvector) and Qdrant services
│ └── .env.example # Docker environment templates
├── docs/ # Architecture specifications and implementation plans
├── scripts/
│ ├── test.sh # Monorepo test runner (Python + TypeScript)
│ ├── dev-up.sh # Bootstrap local Docker infrastructure
│ └── dev-down.sh # Tear down local Docker services
└── pyproject.toml # uv monorepo workspace configuration
Route dynamically across LLM providers based on project load and reasoning requirements:
from common.llm import get_model
# High-reasoning agent model
model = get_model(project="P1-react-agent", task="reasoning")
# Cost-optimized evaluator model
eval_model = get_model(project="P2-rag", task="eval")Isolate project traces cleanly in LangSmith with automatic environment scoping:
from common.tracing import setup
# Automatically configures LANGSMITH_PROJECT="LearnAgenticAI/P1-react-agent"
with setup("P1-react-agent"):
response = agent.invoke({"messages": [...]})Format events predictably for consumer frontends:
from common.ui_bridge import to_sse
# Stream individual tokens
yield to_sse("token", {"delta": "Hello"})
# Stream tool start and completion telemetry
yield to_sse("tool_start", {"id": "call_1", "tool": "tavily_search", "args": {"query": "LangGraph"}})
yield to_sse("tool_end", {"id": "call_1", "result": "..."})
# Attach LangSmith trace URL
yield to_sse("trace_meta", {"run_id": "8f2a...", "project": "LearnAgenticAI/P1-react-agent"})# Clone the repository
git clone git@github.com:atandra2000/LearnAgenticAI.git
cd LearnAgenticAI
# Copy environment configuration files
cp .env.example .env
cp docker/.env.example docker/.env
cp apps/chat-ui/.env.example apps/chat-ui/.env.local
# Edit .env and supply your API keys:
# OPENROUTER_API_KEY=...
# LANGSMITH_API_KEY=...# Sync Python workspace packages
uv sync --all-packages --all-extras
# Install frontend dependencies
pnpm --dir apps/chat-ui install
# Start local backing services (PostgreSQL + Qdrant)
bash scripts/dev-up.shIn terminal 1 (Backend Agent):
cd agents/P0-smoke
uv run uvicorn P0_smoke.server:app --reload --port 8000In terminal 2 (Next.js Chat UI):
pnpm --dir apps/chat-ui devOpen http://localhost:3000 to interact with the agent.
The repository enforces strict typing, linting, and automated testing across both Python and TypeScript workspaces.
# Run the complete test suite (Python pytest + TypeScript vitest)
bash scripts/test.sh
# Python Linting & Formatting
uv run ruff check .
uv run ruff format --check .
# Python Static Type Analysis
uv run mypy common/src agents/P0-smoke/src
# TypeScript Typecheck & Linting
pnpm --dir apps/chat-ui typecheck
pnpm --dir apps/chat-ui lintDistributed under the MIT License. See LICENSE for more details.