自托管的 LangSmith Deployments 替代方案，基于 FastAPI 和 PostgreSQL 的 AI Agent 后端服务，支持零代码迁移与完全数据主权。
项目定位#
Aegra 是一个面向生产环境的自托管 AI Agent 后端引擎，采用 Apache License 2.0 开源。基于 FastAPI 与 PostgreSQL 构建，核心定位为零代码替代 LangSmith Deployments（原 LangGraph Platform），让使用 LangGraph 构建的 Agent 能够无缝迁移至私有化基础设施，避免供应商锁定与数据合规风险。
Aegra 本身不提供大模型推理服务，需配合外部 LLM API（如 OpenAI）使用，聚焦于 Agent 的运行时编排、状态管理、流式通信与可观测性。
核心能力#
- 协议兼容：兼容 Agent Protocol，即插即用 Agent Chat UI、LangGraph Studio、AG-UI / CopilotKit；原生兼容 LangGraph SDK，迁移无需修改客户端代码
- Worker 架构：基于 Redis 作业队列，单实例 30 并发运行；租约式崩溃恢复；支持跨多实例水平扩展
- 实时流式传输：8 种 SSE 流模式；跨实例 Pub/Sub 机制；自动重连与事件回放
- Human-in-the-loop：内置审批门与用户干预点
- 持久化状态：基于 LangGraph 的 PostgreSQL Checkpoint 持久化
- 语义存储：基于 pgvector 扩展的向量嵌入存储
- 可配置认证：支持 JWT、OAuth、Firebase 或无认证模式，可通过 Python Handler 完全自定义
- 统一可观测性：通过 OpenTelemetry 支持扇出式追踪，可对接 Langfuse、Phoenix 等任意 OTLP 后端
- 自定义路由：允许在 Agent Protocol API 旁添加自定义 FastAPI 端点
架构概览#
Aegra 采用 Monorepo workspace 结构，通过 uv 进行包管理，核心分为服务端（libs/aegra-api）和命令行工具（libs/aegra-cli）。
- 接入层：基于 FastAPI 构建，对外暴露 Agent Protocol REST API，并支持挂载自定义业务路由端点
- 编排与执行层：深度集成 LangGraph，负责 Agent 状态机流转、Subgraph 支持及 Checkpoint 生命周期管理
- 数据持久层：强依赖 PostgreSQL，存储线程状态、Checkpoint 数据及 Key-Value 存储；通过 pgvector 扩展提供向量检索能力
- 异步调度与通信层：引入 Redis 作为核心基础设施，承担 Worker 任务分发、SSE 跨实例消息发布订阅以及崩溃恢复时的租约管理
- 可观测性链路：通过 OpenTelemetry 标准协议采集内部执行指标与链路，支持扇出至多个外部追踪后端
部署方式#
支持 Docker / Docker Compose 原生部署，适配 PaaS 及 Kubernetes 环境。开发模式下通过 aegra dev 可自动拉起内置 PostgreSQL 实例。
前置条件：Python 3.12+、Docker。
CLI 安装（推荐）：
pip install aegra-cli
aegra init
cd <your-project>
cp .env.example .env
uv sync
uv run aegra dev
应安装
aegra-cli而非aegra元包，后者不支持版本锁定。
从源码运行：
git clone https://github.com/aegra/aegra.git
cd aegra
cp .env.example .env
docker compose up
启动后访问 http://localhost:2026/docs 查看自动生成的 API 文档。
CLI 命令#
| 命令 | 说明 |
|---|---|
aegra init | 交互式初始化新项目 |
aegra init ./my-agent | 在指定路径创建项目 |
aegra dev | 启动开发服务器（热重载 + 自动 PostgreSQL） |
aegra serve | 启动生产服务器（无热重载） |
aegra up | 构建并启动所有 Docker 服务 |
aegra down | 停止 Docker 服务 |
aegra version | 显示版本信息 |
配置体系#
- 文件配置：通过项目根目录的
aegra.json文件进行核心参数配置 - 环境变量：通过
.env文件注入敏感信息（如 LLM API Key）及运行时环境变量 - API 接口：遵循 Agent Protocol 标准接口规范，并提供标准 FastAPI Swagger 文档
迁移示例#
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)
适用场景#
- 从 LangSmith Deployments 零代码迁移至自托管环境的团队
- 对数据驻留有严格合规要求的企业级 Agent 部署
- 需要高可用、多租户及跨实例水平扩展的生产级负载场景
- 需要将 Agent 运行时追踪深度对接至自有 OpenTelemetry 后端（如 Langfuse、Phoenix）的研运体系
- 本地快速开发与调试 LangGraph Agent