Skip to main content

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
  • Webhooks: Get a POST with the result when a run or a cron-fired run finishes
  • 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
  • aegra-cli: Command-line interface for project management

Documentation

For full documentation, see the docs/ directory.

Metadata

Release files for aegra-api 0.12.0

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.12.0
File Size Uploaded Provenance Actions
aegra_api-0.12.0.tar.gz 584.9 kB Without provenance Details for aegra_api-0.12.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aegra-api 0.12.0
File Interpreter ABI Platform Actions
aegra_api-0.12.0-py3-none-any.whl Python 3 none any Details for aegra_api-0.12.0-py3-none-any.whl

Total release size: 855.0 kB

Release files / aegra_api-0.12.0.tar.gz

Download URL aegra_api-0.12.0.tar.gz
Size 584.9 kB
Tags Source
SHA-256 checksum
How to use checksums
7ba86c91bb66566a362ae45bfc5d32364975477eb7744449c93389dec6814b68
BLAKE2b-256 checksum
How to use checksums
0be4c8504edc99fe150b92e2b25a10c2b2044d8b3d5a273bf6badab5c7e7a39c
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.12.0-py3-none-any.whl

Download URL aegra_api-0.12.0-py3-none-any.whl
Size 270.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0ba2a074263f2063785c1e579b2ab08578531b84c14e3c72d9f731cd2fb4d686
BLAKE2b-256 checksum
How to use checksums
f5f3fe28e94add3d6b85a9a9223a064acd1904034b941c156e7ad8f2be9d813b
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.12.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.

Release history Release notifications | RSS feed

This release

0.12.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page