aegra

aegra

Open source LangGraph Platform alternative - Self-hosted AI agent backend with FastAPI and PostgreSQL. Zero vendor lock-in, full control over your agent infrastructure.

Stars: 137

Visit
 screenshot

Aegra is a self-hosted AI agent backend platform that provides LangGraph power without vendor lock-in. Built with FastAPI + PostgreSQL, it offers complete control over agent orchestration for teams looking to escape vendor lock-in, meet data sovereignty requirements, enable custom deployments, and optimize costs. Aegra is Agent Protocol compliant and perfect for teams seeking a free, self-hosted alternative to LangGraph Platform with zero lock-in, full control, and compatibility with existing LangGraph Client SDK.

README:

Aegra banner

Aegra - Open Source LangGraph Platform Alternative

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

GitHub stars License Issues Discord Reddit Follow on X

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


๐Ÿ”ฅ Why Aegra vs LangGraph Platform?

Feature LangGraph Platform Aegra (Self-Hosted)
Cost $$$+ per month Free (self-hosted), infra-cost only
Data Control Third-party hosted Your infrastructure
Vendor Lock-in High dependency Zero lock-in
Customization Platform limitations Full control
API Compatibility LangGraph SDK Same LangGraph SDK
Authentication Lite: no custom auth Custom auth (JWT/OAuth/Firebase/NoAuth)
Database Ownership No bring-your-own database BYO Postgres (you own credentials and schema)
Tracing/Telemetry Forced LangSmith in SaaS Your choice (Langfuse/None)

โœจ Core Benefits

  • ๐Ÿ  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

๐Ÿš€ Quick Start (5 minutes)

Prerequisites

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

Get Running

# 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

Verify It Works

# 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.

๐Ÿ’ฌ Agent Chat UI Compatible

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.

๐Ÿ‘จโ€๐Ÿ’ป For Developers

New to database migrations? Check out our guides:

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"

๐Ÿงช Try the Example Agent

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! ๐Ÿ”„

๐Ÿ—๏ธ Architecture

Client โ†’ FastAPI โ†’ LangGraph SDK โ†’ PostgreSQL
 โ†“         โ†“           โ†“             โ†“
Agent    HTTP     State        Persistent
SDK      API    Management      Storage

Components

  • 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

๐Ÿ“ Project Structure

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

โš™๏ธ Configuration

Environment Variables

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=...

Graph Configuration

aegra.json defines your agent graphs:

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

๐ŸŽฏ What You Get

โœ… Core Features

  • 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

โœ… Production Ready

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

โœ… Developer Experience

  • 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

Star History

Star History Chart

๐Ÿ›ฃ๏ธ Roadmap

โœ… 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

๐Ÿค Contributing

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.

๐Ÿ“„ License

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

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for aegra

Similar Open Source Tools

For similar tasks

For similar jobs