FastAPI LangGraph Agent 生产就绪模板
开箱即用的 AI Agent 后端模板，集成了 LangGraph、长期记忆、可观测性与认证。
证据显示：README 和 SECURITY.md 提到 JWT 认证、速率限制、CORS 配置、密码 bcrypt 哈希、输入消毒，但未提供具体实现细节。依赖项包括多个包，但未提供漏洞扫描或固定版本（除 langfuse 外）。外部效果：模板会调用外部 LLM API 和 Langfuse 追踪，但未明确说明数据流向。回滚：未提及。来源归属：未验证发布者身份。扣分原因：缺少具体实现证据，依赖安全未充分处理，外部效果和数据流透明度不足。
证据显示：README 和 pyproject.toml 中依赖项一致，但未提供测试结果。依赖可用性：依赖项众多，但未提供锁定文件或版本范围。失败消息：文档提到重试和回退，但未提供具体错误消息。扣分原因：缺乏测试证据，依赖可用性未充分保证，失败消息未具体化。
证据显示：README 明确目标受众为 AI 工程师，并列出多种使用场景。能力边界：文档提到支持 OpenAI 和计划中的多提供商，但未明确限制。触发精度：未提供具体触发条件。环境适配：提供 Docker 和本地开发说明，但未提供所有环境的详细配置。扣分原因：能力边界和触发精度不明确。
证据显示：README 提供清晰的项目结构、安装步骤、FAQ 和文档链接。命名稳定性：未提及。已知限制：FAQ 提到仅支持 OpenAI，但未全面列出。许可证：MIT 许可证存在。版本控制：pyproject.toml 有版本号，但无变更日志。维护责任：SECURITY.md 提到维护者，但未明确。扣分原因：缺少变更日志和已知限制不全面。
证据显示：README 描述输出为 API 端点，但未提供具体输出格式。边际价值：模板提供多种生产功能，但未与现有方案对比。成本效益：未提供性能或成本数据。扣分原因：输出可用性未具体化，成本效益缺乏数据。
证据显示：README 中的声明部分有文档支持，但未提供外部验证。交叉来源：未提供。事实与推断分离：文档中区分了事实和计划，但不够清晰。扣分原因：缺乏外部验证和清晰的分离。
- 发布者身份未验证，需谨慎对待。
- 依赖项未固定版本，存在供应链风险。
- 外部 LLM 和 Langfuse 调用可能涉及数据外传，需明确数据流。
- 未提供测试结果，可靠性存疑。
这个 Agent 能做什么，适合哪些场景？
FastAPI LangGraph Agent 模板是一个生产级后端起点，用于构建 AI Agent 服务。它处理了状态化对话、长期记忆（通过 mem0 和 pgvector）、工具调用、可观测性（Langfuse、Prometheus、Grafana）、速率限制和 JWT 认证，使开发者可以专注于 Agent 逻辑。该模板包含 LLMRegistry 服务，支持循环回退和指数退避重试，并通过 OpenAI 兼容端点（如 Atlas Cloud）工作。项目提供 Alembic 迁移、可选的 Valkey/Redis 缓存层、结构化日志，以及详细的文档（包括架构、配置和评估）。它适用于 Docker Compose 或本地开发，并附带 Makefile 命令。
启动时会初始化 FastAPI 应用，暴露 /docs 端点下的 API 路由，并连接 PostgreSQL 数据库（通过 SQLModel ORM，带 Alembic 迁移）。Agent 图定义在 app/core/langgraph/ 中，支持带 checkpointing 的状态化对话和工具调用；工具可以添加到 app/core/langgraph/tools/。LLM 调用通过 LLMRegistry，使用 langchain_openai.ChatOpenAI，并配置了 DEFAULT_LLM_MODEL、OPENAI_BASE_URL 和 OPENAI_API_KEY 环境变量；服务在发生故障时会在模型间循环回退，并应用总超时预算。长期记忆由进程内 mem0 提供，并持久化到 PostgreSQL，使用 pgvector 进行语义搜索。所有 LLM 调用都会通过 Langfuse 追踪，Prometheus 暴露指标。JWT 认证用于会话管理，slowapi 实现速率限制。还提供评估框架（evals/）。
- AI 工程师希望在几小时内搭建一个生产级 Agent 后端，而不是从零开始集成所有组件
- 团队需要为多个用户提供具有长期语义记忆的 Agent，而不依赖外部记忆云服务
- 希望在 Langfuse、Prometheus 和 Grafana 中追踪完整 LLM 调用链的开发团队
- 需要带会话和速率限制的 JWT 认证后端，并快速搭建状态化对话
- 希望基于单一 OpenAI 兼容端点（如 Atlas Cloud）尝试不同 LLM 的工程师
- 需要一个包含 Docker、数据库迁移和监控栈的完整模板，用于快速项目启动
这个 Agent 有哪些优点和局限？
- 包含全套生产组件：Alembic 迁移、mem0+pgvector 长期记忆、Langfuse 追踪、Prometheus/Grafana 指标、JWT 会话和 slowapi 速率限制，无需额外组装
- LLM 服务具有指数退避重试和循环回退机制，确保高可用性
- 通过 Atlas Cloud 支持 59 种以上的 OpenAI 兼容模型，可快速切换模型
- 提供了从架构、配置到评估的全面文档，降低了上手难度
- 目前仅原生支持 OpenAI 兼容 API；多提供商支持（如 Anthropic、Google）仍在计划中（issue #51），需要额外适配
- 长期记忆依赖 PostgreSQL + pgvector，需要数据库管理开销
- 生产环境需要 JWT、缓存、监控等额外组件，可能超出简单项目的需求
- 当前主要支持 OpenAI 提供方，若想使用其他提供方（Anthropic、Google）可能需要等待更新或自行修改代码
如何安装或部署这个 Agent？
克隆仓库并进入目录，然后复制 .env.example 为 .env.development 并填入密钥（OPENAI_API_KEY 或 Atlas Cloud 凭证，以及数据库配置）。确保 Docker 已安装，然后运行 make install 和 make docker-up 来启动 API 和 PostgreSQL。对于本地开发，请参阅 docs/getting-started.md。
如何使用这个 Agent？
启动 Docker 后，访问 [http://localhost:8000/docs](http://localhost:8000/docs) 查看交互式 API 文档。应用迁移：make migrate。设置环境变量 DEFAULT_LLM_MODEL 以选择模型。可以通过在 app/core/langgraph/tools/ 中添加 LangChain 装饰的工具，并在该包的 tools 列表中注册，来添加自定义工具，无需修改图。使用 Langfuse 进行追踪，设置 LANGFUSE_TRACING_ENABLED=false 可禁用。有关完整配置，请参阅 docs/configuration.md。
常见问题
此模板是否支持非 OpenAI 模型（如 Anthropic 或 Google）？
LLMRegistry 使用 langchain_openai.ChatOpenAI）。多提供方支持计划在 issue #51 中实现。长期记忆是否需要单独的 mem0 云账户？
OPENAI_API_KEY 用于事实提取和嵌入。是否可以禁用 Langfuse 追踪？
LANGFUSE_TRACING_ENABLED=false 或省略 Langfuse 密钥即可。结构化日志仍会捕获请求/会话/用户上下文。如果 API 无法启动，可能的原因是什么？
make docker-up 会同时启动），.env.development 存在并包含必要密钥，且已运行 make migrate 应用迁移。如何调整速率限制策略？
app/core/limiter.py（slowapi）中配置。您可以调整路由装饰器或默认速率，相关环境变量在 docs/configuration.md 中有说明。