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": {
"path": "./graphs/assistant/graph.py:graph",
"description": "Assistant for support workflows"
}
},
"http": {
"app": "./custom_routes.py:app"
}
}
Graph entries accept either the legacy string import path or an object with a required path and optional description.
The description is used for the graph's default assistant and synchronized on startup when it changes. Only system-owned assistants are synchronized; a user-created assistant with the same ID is left unchanged. An omitted or null description uses Default assistant for graph '<graph_id>'; an empty string is preserved.
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.
Metadata
Release files for aegra-api 0.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aegra_api-0.11.0.tar.gz | 539.1 kB | Without provenance | Details for aegra_api-0.11.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aegra_api-0.11.0-py3-none-any.whl | Python 3 | none | any | Details for aegra_api-0.11.0-py3-none-any.whl |
Total release size: 794.6 kB
Release files / aegra_api-0.11.0.tar.gz
| Download URL | aegra_api-0.11.0.tar.gz |
|---|---|
| Size | 539.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
704a8ac72bf22520057deb4fd5f5dee1e85d1039314cd62a873dfd37738bc82c
|
|
BLAKE2b-256 checksum How to use checksums |
3673faf448a3ef41f46d9449e49b5e621b9c64787eb9d77c2a4f04fbf117a71d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / aegra_api-0.11.0-py3-none-any.whl
| Download URL | aegra_api-0.11.0-py3-none-any.whl |
|---|---|
| Size | 255.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6d49695aecd4133289b9b0e84d39eb67f1fb7581cedcb1554405d93b580648d3
|
|
BLAKE2b-256 checksum How to use checksums |
cbc8fc48d38993d3df858953000e3e98fd884c3ffd6552b8c483424b7f87ac68
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for aegra-api 0.11.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.