Aegra

---

Aegra is a drop-in replacement for LangSmith Deployments. Use the same LangGraph SDK, same APIs, but run it on your own infrastructure with PostgreSQL persistence.

Works with: Agent Chat UI | LangGraph Studio | AG-UI / CopilotKit

🆕 New: Agent Protocol v2 streaming. Thread-scoped SSE with content-block events, per-subgraph lifecycle, and native human-in-the-loop resume — the wire the latest LangGraph SDKs and useStream() target. Enabled by default. See the streaming guide.

🚀 Quick Start

Using the CLI (Recommended)

Prerequisites: Python 3.12+, Docker (for PostgreSQL)

pip install aegra-cli

# Initialize a new project — prompts for location, template, and name
aegra init

# Follow the printed next steps:
cd <your-project>
cp .env.example .env     # Add your OPENAI_API_KEY to .env
uv sync                  # Install dependencies
uv run aegra dev         # Start PostgreSQL + dev server

Note: Always install aegra-cli directly — not the aegra meta-package. The aegra package on PyPI is a convenience wrapper that does not support version pinning.

From Source

git clone https://github.com/aegra/aegra.git
cd aegra
cp .env.example .env
# Add your OPENAI_API_KEY to .env

docker compose up

Open http://localhost:2026/docs to explore the API.

Your existing LangGraph code works without changes:

from langgraph_sdk import get_client

client = get_client(url="http://localhost:2026")

assistant = await client.assistants.create(graph_id="agent")
thread = await client.threads.create()

async for chunk in client.runs.stream(
    thread_id=thread["thread_id"],
    assistant_id=assistant["assistant_id"],
    input={"messages": [{"type": "human", "content": "Hello!"}]},
):
    print(chunk)

🔥 Why Aegra?

Based on LangChain pricing as of February 2026. An enterprise tier with self-hosting is also available at custom pricing.

	LangSmith Deployments	Aegra
Deploy agents	Local dev only (Free), paid cloud (Plus)	Free, unlimited
Custom auth	Not available (Free), available (Plus)	Python handlers (JWT/OAuth/Firebase)
Scheduled cron jobs	Not available (Free), available (Plus)	Built-in, free
Self-hosted	Enterprise only (license key required)	Always (Apache 2.0)
Own database	Managed only (Free/Plus), bring your own (Enterprise)	Bring your own Postgres
Tracing	LangSmith only	Any OTLP backend (Langfuse, Phoenix, etc.)
Data residency	LangChain cloud (Free/Plus), your infrastructure (Enterprise)	Your infrastructure
SDK	LangGraph SDK	Same LangGraph SDK

✨ Features

• Agent Protocol compliant - Works with Agent Chat UI, LangGraph Studio, CopilotKit
• Worker architecture - Redis job queue with 30 concurrent runs per instance, lease-based crash recovery, and horizontal scaling across multiple instances
• Scheduled cron jobs - Trigger runs on a schedule with standard 5-field or seconds-level 6-field expressions, IANA timezone support, and multi-instance safe SKIP LOCKED claim
• Human-in-the-loop - Approval gates and user intervention points
• Streaming - Real-time SSE streaming with cross-instance pub/sub and automatic reconnection with event replay. Supports both the legacy run-scoped stream and Agent Protocol v2 thread-scoped streaming (content-block events, per-subgraph lifecycle, HITL resume) for the latest LangGraph SDKs and useStream()
• Persistent state - PostgreSQL checkpoints via LangGraph
• Configurable auth - JWT, OAuth, Firebase, or none
• Unified Observability - Fan-out tracing support via OpenTelemetry
• Semantic store - Vector embeddings with pgvector
• Custom routes - Add your own FastAPI endpoints

🛠️ CLI Commands

aegra init              # Interactive — asks for location, template, and name
aegra init ./my-agent   # Create at path (still prompts for template)

aegra dev               # Start development server (hot reload + auto PostgreSQL)
aegra serve             # Start production server (no reload)
aegra up                # Build and start all Docker services
aegra down              # Stop Docker services

aegra version           # Show version info

📚 Documentation

docs.aegra.dev — Full documentation with guides, API reference, and configuration.

Topic	Description
Quickstart	Get a running server in under 5 minutes
Configuration	aegra.json format and all options
Authentication	JWT, OAuth, Firebase, or custom auth handlers
Worker Architecture	Redis job queue, crash recovery, horizontal scaling
Scheduled cron jobs	Trigger runs on a schedule with timezone support and multi-instance safe claim
Streaming	8 SSE stream modes with reconnection
Store	Key-value and semantic search storage
Observability	Fan-out tracing to Langfuse, Phoenix, or any OTLP backend
Deployment	Docker, PaaS, and Kubernetes deployment
Migration	Migrate from LangSmith Deployments

💬 Community & Support

• Discord - Chat with the community
• GitHub Discussions - Ask questions, share ideas
• GitHub Issues - Report bugs

🏗️ Built With

• FastAPI - HTTP layer
• LangGraph - State management & graph execution
• PostgreSQL - Persistence & checkpoints
• Redis - Job queue, SSE pub/sub, crash recovery
• OpenTelemetry - Observability standard
• pgvector - Vector embeddings

🤝 Contributing

We welcome contributions! See Contributing guide and check out good first issues.

💖 Support the Project

The best contribution is code, PRs, and bug reports - that's what makes open source thrive.

For those who want to support Aegra financially, whether you're using it in production or just believe in what we're building, you can become a sponsor. Sponsorships help keep development active and the project healthy.

📄 License

Apache 2.0 - see LICENSE.

---