README.md

metadata

title: Template Final Assignment
emoji: 🕵🏻‍♂️
colorFrom: indigo
colorTo: indigo
sdk: gradio
sdk_version: 5.25.2
app_file: app.py
pinned: false
hf_oauth: true
hf_oauth_expiration_minutes: 480

LangGraph Multi-Agent System with Langfuse v3 Observability

A sophisticated multi-agent system built with LangGraph that follows best practices for state management, tracing, and iterative workflows. Features comprehensive Langfuse v3 observability with OpenTelemetry integration.

Architecture Overview

The system implements an iterative research/code loop with specialized agents:

User Query → Lead Agent → Research Agent → Code Agent → Lead Agent (loop) → Answer Formatter → Final Answer

Key Features

• 🤖 Multi-Agent Workflow: Specialized agents for research, computation, and formatting
• 📊 Langfuse v3 Observability: Complete tracing with OTEL integration and predictable span naming
• 🔄 Iterative Processing: Intelligent routing between research and computational tasks
• 🎯 GAIA Compliance: Exact-match answer formatting for benchmark evaluation
• 💾 Memory System: Vector store integration for learning and caching
• 🛠️ Tool Integration: Web search, Wikipedia, ArXiv, calculations, and code execution

Quick Start

Environment Setup

Create an env.local file with required API keys:

# LLM API
GROQ_API_KEY=your_groq_api_key

# Search Tools
TAVILY_API_KEY=your_tavily_api_key

# Observability (Langfuse v3)
LANGFUSE_PUBLIC_KEY=your_langfuse_public_key
LANGFUSE_SECRET_KEY=your_langfuse_secret_key
LANGFUSE_HOST=https://cloud.langfuse.com

# Memory (Optional)
SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_KEY=your_supabase_service_key

Running the System

Important: Use uv run for proper dependency management:

# Run the multi-agent system test
uv run python test_new_multi_agent_system.py

# Test Langfuse v3 observability
uv run python test_observability.py

# Run the main application
uv run python app.py

Basic Usage

import asyncio
from langgraph_agent_system import run_agent_system

async def main():
    result = await run_agent_system(
        query="What is the capital of Maharashtra?",
        user_id="user_123",
        session_id="session_456"
    )
    print(f"Answer: {result}")

asyncio.run(main())

Observability Dashboard

After running queries, check your traces at: https://cloud.langfuse.com

The system provides:

• 🎯 Predictable Span Naming: agent/<role>, tool/<name>, llm/<model>
• 🔗 Session Tracking: User and session continuity across conversations
• 📈 Cost & Latency Metrics: Automatic aggregation by span type
• 🌐 OTEL Integration: Automatic trace correlation across services

Deployment

For Hugging Face Spaces

To generate a requirements.txt file compatible with Python 3.10 for deployment:

uv pip compile pyproject.toml --python 3.10 -o requirements.txt

# Remove Windows-specific packages
# Linux / macOS (bash)
sed -i '/^pywin32==/d' requirements.txt

# Windows (PowerShell)
(Get-Content requirements.txt) -notmatch '^pywin32==' | Set-Content requirements.txt

Environment Variables for Production

Set these in your deployment environment:

• GROQ_API_KEY - Required for LLM inference
• TAVILY_API_KEY - Required for web search
• LANGFUSE_PUBLIC_KEY - Required for observability
• LANGFUSE_SECRET_KEY - Required for observability
• LANGFUSE_HOST - Langfuse endpoint (default: https://cloud.langfuse.com)

Documentation

For detailed architecture, configuration, and usage instructions, see:

• Multi-Agent System Guide - Complete system documentation
• Supabase Setup - Memory system configuration

Configuration Reference

Check out the Hugging Face Spaces configuration reference at https://huggingface.co/docs/hub/spaces-config-reference