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.
💬 Community & Support
🏗️ Built With
🤝 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.
