从LangSmith Deployments迁移到Aegra：5步完整指南，零代码改动实现自托管

• 后端
• 人工智能
• AI Agent

Aegra 是一个开源、自托管的 Agent Protocol 服务器，可作为 LangSmith Deployments（原 LangGraph Platform）的免费替代品：基于 FastAPI + PostgreSQL，让你的 AI Agent 完全跑在自己的基础设施上，且 LangGraph 图代码、SDK 调用几乎零改动即可迁移。本文将带你用 5 步完成这次迁移，并获得数据、成本与可观测性的完全控制权。

为什么要迁移到 Aegra？🎯

托管平台按运行次数、节点执行和席位收费，成本随流量线性上涨；而 Agent 状态、对话历史都存储在第三方服务器上。迁移到 Aegra 后：

一台 $5/月的 VPS 就能同时跑服务、数据库和多个 Agent。完整对比见 docs/why-aegra.mdx，功能支持矩阵见 docs/feature-support.mdx。

迁移前后：什么不变，什么变？

完全不变的部分（这是"零代码改动"的关键）：

• ✅图代码：LangGraph Agent 原样运行
• ✅SDK 调用：get_client()、client.threads、client.runs.stream()全部相同
• ✅Agent Protocol 前端：Agent Chat UI、LangGraph Studio、CopilotKit 直接兼容
• ✅线程状态模型：Threads、Checkpoints、状态检查行为一致
• ✅流式输出与 Human-in-the-Loop：SSE 模式、中断/恢复模式均相同

需要调整的部分只有 4 处：

5步迁移实战 🚀

第1步：安装 Aegra CLI

一条命令安装官方命令行工具（注意直接安装aegra-cli，而非 PyPI 上的aegra元包，后者不支持版本锁定）：

pip install aegra-cli

第2步：拷贝你的 LangGraph 图代码

把原有的 graphs 模块复制到新项目目录即可，一行代码都不用改：

mkdir my-project && cd my-project cp -r /path/to/your/graphs ./graphs

第3步：创建 aegra.json 配置文件

用aegra.json替代langgraph.json，其中graphs部分完全相同：

{ "graphs": { "agent": "./graphs/agent.py:graph" } }

小提示：Aegra 支持回退读取langgraph.json，所以你可以先原样保留，之后再改名，迁移更平滑。仓库自带了多示例项目的配置参考，例如 aegra.json 中注册了 react_agent、HITL、子图等多种 Agent，图实现可查看 examples/react_agent/graph.py。完整配置项（auth、HTTP、CORS、store）见 docs/reference/configuration.mdx。

第4步：配置环境变量与数据库

创建.env文件，写入 LLM 密钥和数据库信息：

# LLM 提供商密钥 OPENAI_API_KEY=sk-... # 已有 PostgreSQL 时，直接指定 DATABASE_URL=postgresql://user:pass@host:5432/aegra

Aegra 使用带pgvector扩展的 PostgreSQL（推荐pgvector/pgvector:pg18镜像）来持久化 Agent 状态并支持向量搜索。使用aegra dev时数据库会通过 Docker 自动拉起，无需手动配置。

第5步：启动服务器，只改客户端 URL

uv sync uv run aegra dev

一条命令完成：启动 Docker 中的 PostgreSQL → 执行数据库迁移 → 以热重载方式在http://localhost:2026启动服务。然后只需把应用代码里的客户端 URL 换掉：

from langgraph_sdk import get_client # 迁移前 # client = get_client(url="https://your-deployment.langsmith.com") # 迁移后：仅改 URL，其余全部不变 client = get_client(url="http://localhost:2026")

线程创建、运行、流式输出、状态检查照常工作。启动后访问http://localhost:2026/health返回{"status": "healthy"}即表示迁移完成，交互 API 文档在/docs页面。

进阶：迁移认证与 Tracing 🔧

• 认证：LangSmith 靠控制台配置，Aegra 改用 Python 认证处理器。写好authenticate函数（支持 JWT 校验等），然后在aegra.json中加一行"auth": {"path": "./my_auth.py:auth"}即可。示例可参考 examples/jwt_mock_auth_example.py，认证实现位于 libs/aegra-api/src/aegra_api/core/auth_registry.py。
• Tracing：原来自动上报 LangSmith，现在通过环境变量发送 OTLP，且可同时扇出到多个后端：

OTEL_TARGETS="LANGFUSE,PHOENIX"

可观测性源码与配置说明见 libs/aegra-api/src/aegra_api/observability/ 目录与 docs/guides/observability.mdx。

迁移注意事项 ⚠️

• 环境要求：Python 3.12+；本地开发需 Docker（用于拉起 PostgreSQL）；生产推荐 Docker 或 Linux 服务器
• 暂未支持的功能：RemoteGraph尚无计划，使用前可查 docs/feature-support.mdx 确认完整矩阵
• 验证清单：/health健康检查 → 跑通一次runs.stream→ 检查/docs中各 Agent 端点
• 生产部署：开发用aegra dev，生产用aegra up或docker compose up，部署指南见 docs/guides/deployment.mdx

总结

从 LangSmith Deployments 迁移到 Aegra 本质上只是换一个配置文件名、一条数据库、一个 URL：图代码、SDK、前端全部保留。5 步走完后，你就拥有了免费的无限部署、自己掌控的数据库、可自由选择的 Tracing 后端和代码级认证——这就是自托管 AI Agent 后端的完整价值。

• 后端
• 人工智能
• AI Agent