Self-hosted AI agent backend. LangGraph power without vendor lock-in.

Replace LangGraph Platform with your own infrastructure. Built with FastAPI + PostgreSQL for developers who demand complete control over their agent orchestration.

🔌 Agent Protocol Compliant: Aegra implements the Agent Protocol specification, an open-source standard for serving LLM agents in production.

🎯 Perfect for: Teams escaping vendor lock-in • Data sovereignty requirements • Custom deployments • Cost optimization

• 🤝 Human-in-the-Loop Support: Interactive agent workflows with approval gates and user intervention points
• 📊 Langfuse Integration: Complete observability and tracing for your agent runs with automatic metadata capture

Aegra is participating in Hacktoberfest! We welcome meaningful contributions.

What we're looking for:

• Feature development and enhancements
• Bug fixes that improve stability
• Substantial documentation improvements
• Testing and feedback on real use cases

What we're NOT looking for:

• Single typo fixes
• Whitespace changes
• Low-effort PRs for swag hunting

Quality over quantity. If you're here to build something real, we'd love your help.

Check out our Contributing Guidelines and open issues to get started.

• 🏠 Self-Hosted: Run on your infrastructure, your rules
• 🔄 Drop-in Replacement: Use existing LangGraph Client SDK without changes
• 🛡️ Production Ready: PostgreSQL persistence, streaming, authentication
• 📊 Zero Vendor Lock-in: Apache 2.0 license, open source, full control
• 🚀 Fast Setup: 5-minute deployment with Docker
• 🔌 Agent Protocol Compliant: Implements the open-source Agent Protocol specification
• 💬 Agent Chat UI Compatible: Works seamlessly with LangChain's Agent Chat UI

• Python 3.11+
• Docker (for PostgreSQL)
• uv (Python package manager)

# Clone and setup
git clone https://github.com/ibbybuilds/aegra.git
cd aegra
# Install uv if missing
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync env and dependencies
uv sync

# Activate environment
source .venv/bin/activate  # Mac/Linux
# OR .venv/Scripts/activate  # Windows

# Environment
cp .env.example .env

# Start everything (database + migrations + server)
docker compose up aegra

# Health check
curl http://localhost:8000/health

# Interactive API docs
open http://localhost:8000/docs

You now have a self-hosted LangGraph Platform alternative running locally.

Aegra works seamlessly with LangChain's Agent Chat UI. Simply set NEXT_PUBLIC_API_URL=http://localhost:8000 and NEXT_PUBLIC_ASSISTANT_ID=agent in your Agent Chat UI environment to connect to your Aegra backend.

New to database migrations? Check out our guides:

• 📚 Developer Guide - Complete setup, migrations, and development workflow
• ⚡ Migration Cheatsheet - Quick reference for common commands

Quick Development Commands:

# Docker development (recommended)
docker compose up aegra

# Local development
docker compose up postgres -d
python3 scripts/migrate.py upgrade
python3 run_server.py

# Create new migration
python3 scripts/migrate.py revision --autogenerate -m "Add new feature"

Use the same LangGraph Client SDK you're already familiar with:

import asyncio
from langgraph_sdk import get_client

async def main():
    # Connect to your self-hosted Aegra instance
    client = get_client(url="http://localhost:8000")

    # Create assistant (same API as LangGraph Platform)
    assistant = await client.assistants.create(
        graph_id="agent",
        if_exists="do_nothing",
        config={},
    )
    assistant_id = assistant["assistant_id"]

    # Create thread
    thread = await client.threads.create()
    thread_id = thread["thread_id"]

    # Stream responses (identical to LangGraph Platform)
    stream = client.runs.stream(
        thread_id=thread_id,
        assistant_id=assistant_id,
        input={
            "messages": [
                {"type": "human", "content": [{"type": "text", "text": "hello"}]}
            ]
        },
        stream_mode=["values", "messages-tuple", "custom"],
        on_disconnect="cancel",
    )

    async for chunk in stream:
        print(f"event: {getattr(chunk, 'event', None)}, data: {getattr(chunk, 'data', None)}")

asyncio.run(main())

Key Point: Your existing LangGraph applications work without modification! 🔄

Client → FastAPI → LangGraph SDK → PostgreSQL
 ↓         ↓           ↓             ↓
Agent    HTTP     State        Persistent
SDK      API    Management      Storage

• FastAPI: Agent Protocol-compliant HTTP layer
• LangGraph: State management and graph execution
• PostgreSQL: Durable checkpoints and metadata
• Agent Protocol: Open-source specification for LLM agent APIs
• Config-driven: aegra.json for graph definitions

aegra/
├── aegra.json           # Graph configuration
├── auth.py              # Authentication setup
├── graphs/              # Agent definitions
│   └── react_agent/     # Example ReAct agent
├── src/agent_server/    # FastAPI application
│   ├── main.py         # Application entrypoint
│   ├── core/           # Database & infrastructure
│   ├── models/         # Pydantic schemas
│   ├── services/       # Business logic
│   └── utils/          # Helper functions
├── tests/              # Test suite
└── deployments/        # Docker & K8s configs

Copy .env.example to .env and configure values:

cp .env.example .env

# Database
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/aegra

# Authentication (extensible)
AUTH_TYPE=noop  # noop, custom

# Server
HOST=0.0.0.0
PORT=8000
DEBUG=true

# LLM Providers
OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=...
# TOGETHER_API_KEY=...

aegra.json defines your agent graphs:

{
  "graphs": {
    "agent": "./graphs/react_agent/graph.py:graph"
  }
}

• Agent Protocol-compliant REST endpoints
• Persistent conversations with PostgreSQL checkpoints
• Streaming responses with network resilience
• Config-driven agent graph management
• Compatible with LangGraph Client SDK
• Human-in-the-loop support
• Langfuse integration for observability and tracing

• Docker containerization
• Database migrations with Alembic
• Comprehensive test suite
• Authentication framework (JWT/OAuth ready)
• Health checks and monitoring endpoints

• Interactive API documentation (FastAPI)
• Hot reload in development
• Clear error messages and logging
• Extensible architecture
• 📚 Developer Guide - Complete setup, migrations, and development workflow
• ⚡ Migration Cheatsheet - Quick reference for common commands

✅ Completed

• Agent Chat UI compatibility
• Agent Protocol API implementation
• PostgreSQL persistence and streaming
• Authentication framework
• Human-in-the-loop support
• Langfuse integration

🎯 Next

• Custom HTTP endpoints support
• Generative user interfaces support
• Redis-backed streaming buffers
• Advanced deployment recipes

🚀 Future

• Performance optimizations
• Custom UI themes and branding
• Aegra CLI for migration and image building

We welcome contributions! Here's how you can help:

🐛 Issues & Bugs

• Report bugs with detailed reproduction steps
• Suggest new features and improvements
• Help with documentation

💻 Code Contributions

• Improve Agent Protocol spec alignment
• Add authentication backends
• Enhance testing coverage
• Optimize performance

📚 Documentation

• Deployment guides
• Integration examples
• Best practices

Get Started: Check out CONTRIBUTING.md, our Developer Guide, and our good first issues.

Apache 2.0 License - see LICENSE file for details.

⭐ If Aegra helps you escape vendor lock-in, please star the repo! ⭐
_{Built with ❤️ by developers who believe in infrastructure freedom}