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
Related Packages
- aegra-cli: Command-line interface for project management
Documentation
For full documentation, see the docs/ directory.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
aegra_api-0.10.3.tar.gz
(455.4 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
aegra_api-0.10.3-py3-none-any.whl
(232.4 kB
view details)
File details
Details for the file aegra_api-0.10.3.tar.gz.
File metadata
- Download URL: aegra_api-0.10.3.tar.gz
- Upload date:
- Size: 455.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9c501dffac0fa2e480c7b3b823617e44405b5914e642d38fe8074aee66f2a6c4
|
|
| MD5 |
0d9ac8bd09e163a521cb10c734c1ecdc
|
|
| BLAKE2b-256 |
ab6461cf61c35b11243f7e6948971be5e9699e3f5c6408669994268306ed5e89
|
File details
Details for the file aegra_api-0.10.3-py3-none-any.whl.
File metadata
- Download URL: aegra_api-0.10.3-py3-none-any.whl
- Upload date:
- Size: 232.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
75f8d1e171abca70636c4abd9a808e69f8f95cb55f9cf1581b9bac1ee4305b3f
|
|
| MD5 |
69419aed11a17912e4d3be0aa8bb0858
|
|
| BLAKE2b-256 |
e55b3a0cbb8580d8b6f4f6edfdc0c7676cc1c17a51a7cd708f825a9ed3a4ecc7
|
