aegra-api

Aegra API - Self-hosted Agent Protocol server.

Aegra is an open-source, self-hosted alternative to LangSmith Deployments. This package provides the core API server that implements the Agent Protocol, allowing you to run AI agents on your own infrastructure without vendor lock-in.

Features

Agent Protocol Compliant: Works with Agent Chat UI, LangGraph Studio, CopilotKit
Drop-in Replacement: Compatible with the LangGraph SDK
Self-Hosted: Run on your own PostgreSQL database
Streaming Support: Real-time streaming of agent responses
Human-in-the-Loop: Built-in support for human approval workflows
Scheduled Cron Jobs: Trigger runs on a schedule with timezone support and multi-instance safe claim
Vector Store: Semantic search capabilities with PostgreSQL

Installation

pip install aegra-api

Quick Start

The easiest way to get started is with the aegra-cli:

# Install the CLI
pip install aegra-cli

# Initialize a new project (interactive)
aegra init
cd <your-project>

# Configure environment
cp .env.example .env
# Add your OPENAI_API_KEY to .env

# Install dependencies and start developing
uv sync
uv run aegra dev

Manual Setup

If you prefer manual setup:

# Install dependencies
pip install aegra-api

# Set environment variables
export POSTGRES_USER=aegra
export POSTGRES_PASSWORD=aegra_secret
export POSTGRES_HOST=localhost
export POSTGRES_DB=aegra

# Run migrations
alembic upgrade head

# Start server
uvicorn aegra_api.main:app --port 2026 --reload

Configuration

aegra.json

Define your agent graphs in aegra.json:

{
  "graphs": {
    "agent": "./graphs/my_agent/graph.py:graph",
    "assistant": "./graphs/assistant/graph.py:graph"
  },
  "http": {
    "app": "./custom_routes.py:app"
  }
}

Environment Variables

# Database
POSTGRES_USER=aegra
POSTGRES_PASSWORD=aegra_secret
POSTGRES_HOST=localhost
POSTGRES_DB=aegra

# Authentication
AUTH_TYPE=noop  # Options: noop, custom

# Server
HOST=0.0.0.0
PORT=2026

# Configuration
AEGRA_CONFIG=aegra.json

# LLM (for example agents)
OPENAI_API_KEY=sk-...

# Observability (optional)
OTEL_TARGETS=LANGFUSE,PHOENIX

API Endpoints

Endpoint	Method	Description
`/assistants`	POST	Create assistant from graph_id
`/assistants/search`	POST	Search assistants
`/assistants/{assistant_id}`	GET	Get assistant details
`/threads`	POST	Create conversation thread
`/threads/{thread_id}/state`	GET	Get thread state
`/threads/{thread_id}/runs`	POST	Execute graph (background)
`/threads/{thread_id}/runs/stream`	POST	Execute graph (streaming)
`/threads/{thread_id}/runs/{run_id}/cancel`	POST	Cancel a run
`/runs/crons`	POST	Create a stateless cron job
`/threads/{thread_id}/runs/crons`	POST	Create a thread-bound cron job
`/runs/crons/{cron_id}`	PATCH/DELETE	Update or delete a cron job
`/runs/crons/search`	POST	Search cron jobs
`/runs/crons/count`	POST	Count cron jobs
`/store/items`	PUT	Save to vector store
`/store/items/search`	POST	Semantic search
`/store/namespaces`	POST	List store namespaces
`/health`	GET	Health check

Creating Graphs

Agents are Python modules exporting a compiled graph variable:

# graphs/my_agent/graph.py
from typing import TypedDict
from langgraph.graph import StateGraph, START, END

class State(TypedDict):
    messages: list[str]

def process_node(state: State) -> State:
    messages = state.get("messages", [])
    messages.append("Processed!")
    return {"messages": messages}

# Build the graph
builder = StateGraph(State)
builder.add_node("process", process_node)
builder.add_edge(START, "process")
builder.add_edge("process", END)

# Export as 'graph'
graph = builder.compile()

Architecture

+---------------------------------------------------------+
|  FastAPI HTTP Layer (Agent Protocol API)                |
|  - /assistants, /threads, /runs, /store endpoints       |
+---------------------------------------------------------+
|  Middleware Stack                                        |
|  - Auth, CORS, Structured Logging, Correlation ID       |
+---------------------------------------------------------+
|  Service Layer (Business Logic)                          |
|  - LangGraphService, AssistantService, StreamingService |
+---------------------------------------------------------+
|  LangGraph Runtime                                       |
|  - Graph execution, state management, tool execution    |
+---------------------------------------------------------+
|  Database Layer (PostgreSQL)                             |
|  - AsyncPostgresSaver (checkpoints), AsyncPostgresStore |
+---------------------------------------------------------+

Package Structure

libs/aegra-api/
├── src/aegra_api/
│   ├── api/              # Agent Protocol endpoints
│   │   ├── assistants.py # /assistants CRUD
│   │   ├── threads.py    # /threads and state management
│   │   ├── runs.py       # /runs execution and streaming
│   │   └── store.py      # /store vector storage
│   ├── services/         # Business logic layer
│   ├── core/             # Infrastructure (database, auth, orm)
│   ├── models/           # Pydantic request/response schemas
│   ├── middleware/       # ASGI middleware
│   ├── observability/    # OpenTelemetry tracing
│   ├── utils/            # Helper functions
│   ├── main.py           # FastAPI app entry point
│   ├── config.py         # HTTP/store config loading
│   └── settings.py       # Environment settings
├── tests/                # Test suite
├── alembic/              # Database migrations
└── pyproject.toml

aegra-cli: Command-line interface for project management

Documentation

For full documentation, see the docs/ directory.

Release files for aegra-api 0.10.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aegra-api 0.10.6
File	Size	Uploaded
aegra_api-0.10.6.tar.gz	512.3 kB	Sep 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for aegra-api 0.10.6
File	Interpreter	ABI	Platform	Reset
aegra_api-0.10.6-py3-none-any.whl 251.4 kB Sep 25, 2026	Python 3	none	any	Details

Total release size: 763.7 kB

Release files / aegra_api-0.10.6.tar.gz

Download URL	aegra_api-0.10.6.tar.gz
Size	512.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`bbf2737c4c1731f6c4e3e3f0663dbe0c6bc3c3b9f5e1a34bf0692273ffc49c9c`
BLAKE2b-256 checksum How to use checksums	`0ffb09d41053e7b09dc7448e4d6911c3a126bc0f264c50ba94f8354a70a5e561`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / aegra_api-0.10.6-py3-none-any.whl

Download URL	aegra_api-0.10.6-py3-none-any.whl
Size	251.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d39c9bda058027830746bd41ea16e8025db32f2f3cbb95320b1cc5b07f3e1b0d`
BLAKE2b-256 checksum How to use checksums	`ad6f713e94ba140b4cc0237d42fce04c71fd106d49a9ab8e0b74825f70ed0e2b`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`