README.md

metadata

title: AgentGraph
emoji: 🕸️
colorFrom: purple
colorTo: indigo
sdk: docker
pinned: false
license: mit
app_port: 7860
hf_oauth: true
hf_oauth_scopes:
  - read-repos
hf_oauth_expiration_minutes: 480

🕸️ AgentGraph

A comprehensive agent monitoring and knowledge graph extraction system for understanding AI agent behavior and decision-making processes.

🚀 Quick Start

Option 1: Automated Setup (Recommended)

The easiest way to get started is using our setup script:

# 1. Clone the repository
git clone https://huggingface.co/spaces/holistic-ai/AgentGraph
cd AgentGraph

# 2. Run the setup script
./setup.sh

The script will:

• Guide you through environment configuration
• Prompt for your OpenAI API key
• Choose between Docker or local development setup
• Automatically handle all dependencies and services

Option 2: Manual Docker Setup

If you prefer manual control:

# 1. Clone and setup environment
git clone https://huggingface.co/spaces/holistic-ai/AgentGraph
cd AgentGraph
cp .env.example .env
# Edit .env and add your OpenAI API key

# 2. Build and run with Docker
docker build -t agentgraph .
docker run -d --name agentgraph-app -p 7860:7860 --env-file .env agentgraph

# 3. Access the application
open http://localhost:7860

Option 3: Local Development

For development work:

# 1. Setup environment
cp .env.example .env
# Edit .env with your API keys

# 2. Quick setup (installs dependencies and starts development server)
python main.py --first-run

# Or step by step:
python main.py --setup        # Set up environment
python main.py --init-db      # Initialize database
python main.py --dev          # Start development servers

🔧 Configuration

Required Environment Variables

• OPENAI_API_KEY: Your OpenAI API key (required for knowledge extraction)

Optional Environment Variables

• LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY: For AI monitoring integration
• OPENAI_MODEL_NAME: Model to use (default: gpt-4o-mini)
• DB_URI: Database connection string (default: SQLite)

See .env.example for all available configuration options.

📋 Features

• 📊 Real-time Agent Monitoring: Track agent behavior and performance metrics
• 🕸️ Knowledge Graph Extraction: Extract and visualize knowledge graphs from agent traces
• 📈 Interactive Dashboards: Comprehensive monitoring and analytics interface
• 🔄 Trace Analysis: Analyze agent execution flows and decision patterns
• 🎨 Graph Visualization: Beautiful interactive knowledge graph visualizations
• 🔬 Causal Analysis: Advanced causal inference and component analysis
• 🧪 Perturbation Testing: Security and robustness evaluation
• 🔗 Platform Integration: Connect to LangSmith, Langfuse, and other monitoring platforms

🏗️ Architecture

AgentGraph follows a 5-stage pipeline architecture:

1. Input Processing: Trace upload, analysis, and chunking
2. Knowledge Extraction: Multi-agent CrewAI-based extraction
3. Prompt Reconstruction: Template extraction and context resolution
4. Perturbation Testing: Robustness and security evaluation
5. Causal Analysis: Causal inference and relationship analysis

🛠️ Technology Stack

• Backend: FastAPI + Python 3.11+
• Frontend: React + TypeScript + Vite
• Knowledge Extraction: Multi-agent CrewAI system
• Visualization: Cytoscape, D3.js, React Force Graph
• AI Integration: OpenAI, LiteLLM, Langfuse, LangSmith
• Database: SQLAlchemy (SQLite/PostgreSQL/MySQL)
• Deployment: Docker, Hugging Face Spaces ready

📖 Usage

1. Upload Traces: Import agent execution traces in various formats
2. Configure Processing: Choose extraction methods and parameters
3. Extract Knowledge: Automatically generate knowledge graphs
4. Analyze & Visualize: Explore graphs, relationships, and patterns
5. Test Robustness: Run perturbation tests and security evaluations
6. Causal Analysis: Understand causal relationships and component influences

🐛 Troubleshooting

Environment Variable Issues

If you see "Invalid API key" errors:

# Check your configuration
python -c "from utils.config import debug_config; debug_config()"

# Restart Docker container after updating .env
docker restart agentgraph-app

Common Issues

• Missing Dependencies: Run python main.py --first-run for automatic setup
• Port Conflicts: Change the port with --port 8080
• API Key Problems: Ensure your .env file has the correct format (no quotes or extra spaces)

🤝 Contributing

We welcome contributions! Please see our contributing guidelines for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with ❤️ for AI agent research and monitoring.