FastAPI LangGraph Agent 模板

这是一个生产就绪（Production-ready）的后端模板，旨在通过 FastAPI 和 LangGraph 构建 AI Agent。它处理了最棘手的部分——状态化对话、长期记忆、工具调用（Tool Calling）、可观测性、速率限制（Rate Limiting）和身份验证，让你能够专注于业务逻辑。

专为 AI 工程师打造，旨在提供坚实的基础，而非仅供学习的示例项目。

包含内容

• LangGraph：支持检查点（Checkpointing）、工具调用和人工介入（Human-in-the-loop）的状态化 Agent。
• 长期记忆：通过 mem0 + pgvector 实现，支持用户级语义搜索，并具备缓存层。
• LLM 服务：支持模型循环切换（Circular model fallback）、指数退避重试（Exponential backoff retries）和总超时控制。
• 可观测性：所有 LLM 调用均集成 Langfuse 追踪；内置 Prometheus 指标 + Grafana 面板。
• 身份验证：基于 JWT 的会话管理；通过 slowapi 实现速率限制。
• 数据库：集成 Alembic 迁移；可选配 Valkey/Redis 缓存层。
• 结构化日志：每一行日志均包含请求/会话/用户上下文信息。

快速开始

git clone  my-agent && cd my-agent
cp .env.example .env.development   # 填写你的 API keys
make install
make docker-up                     # 启动 API 和 PostgreSQL

访问 http://localhost:8000/docs 查看交互式 API 文档。

如需在无 Docker 环境下进行本地开发，请参考 docs/getting-started.md。

文档

指南	内容涵盖
Getting Started	前置条件、本地设置、首次 API 调用
Architecture	系统设计、请求流程、组件图
Configuration	所有环境变量及其默认值
Authentication	JWT 流程、会话、端点参考
Database & Migrations	Schema、Alembic 迁移、pgvector
LLM Service	模型、重试机制、故障转移、超时控制
Memory	mem0 长期记忆、缓存层
Observability	Langfuse、结构化日志、Prometheus、性能分析
Evaluation	评估框架、自定义指标、报告
Docker	Docker、Compose、完整监控栈

项目结构

app/
  api/v1/          # 路由处理程序
  core/
    langgraph/     # Agent 图 + 工具
    prompts/       # 系统提示词模板
    cache.py       # Valkey/Redis + 内存缓存故障转移
    config.py      # 配置设置
    middleware.py  # 指标、日志上下文、性能分析
    limiter.py     # 速率限制
  models/          # SQLModel ORM 模型
  schemas/         # Pydantic 请求/响应 Schema
  services/        # LLM、数据库、记忆服务
alembic/           # 数据库迁移
evals/             # LLM 评估框架

贡献

欢迎提交 PR。请阅读 docs/getting-started.md 配置开发环境，并遵循 AGENTS.md 中的编码规范。

若发现安全问题，请私下上报——详情参考 SECURITY.md。

许可证

参考 LICENSE。

常见问题解答

概览

这个模板是什么？ 这是一个基于 FastAPI + LangGraph 构建的生产就绪型 AI Agent 后端基础。它集成了你通常需要手动配置的组件：状态化对话、长期记忆、工具调用、可观测性、速率限制和 JWT 身份验证。

它与基础的 LangGraph 设置有何不同？ LangGraph 的基础快速入门仅止于“Agent 本地运行”。本模板添加了 Alembic 迁移、mem0 + pgvector 长期记忆、Langfuse 追踪、Prometheus + Grafana 面板、JWT 会话、slowapi 速率限制、包含请求上下文的结构化日志以及循环故障转移的 LLM 服务——这些都是你在生产环境中必须手动构建的功能。

设置与配置

我需要 Docker 吗？ 推荐但非强制。make docker-up 可同时启动 API 和 PostgreSQL。仅进行本地设置请查看 docs/getting-started.md。

支持哪些 LLM 提供商？ 目前：仅限 OpenAI，通过 app/services/llm/registry.py 中的 LLMRegistry 实现。计划通过 LangChain 的 init_chat_model 支持多提供商（Anthropic、Google、OpenRouter）——详见 #51。请在 .env.development 中通过 DEFAULT_LLM_MODEL 配置你的模型。

如何配置长期记忆？ 长期记忆是自托管的：mem0 在进程内运行，并持久化到你现有的 PostgreSQL 中（利用 pgvector）——无需单独的 mem0 云账户或 API Key。你只需要一个有效的 OPENAI_API_KEY（用于事实提取和嵌入）并启用 pgvector 扩展。详情请参考 docs/memory.md。

开发

如何添加自定义工具？ 只需在 app/core/langgraph/tools/ 下放入一个带有 @tool 装饰器的 LangChain 函数，并在该包导出的 tools 列表中注册即可。Agent 会在下次启动时自动加载它，无需修改图结构。