A production-ready FastAPI template for building AI agent applications with LangGraph integration. This template provides a robust foundation for building scalable, secure, and maintainable AI agent services.

文件	最后提交记录	最后更新时间
.cursor	chore: add pre-commit hooks for linting, formatting, and secret detection - ruff check + ruff-format enforce code style on every commit - detect-secrets blocks accidental API key/secret commits - pre-commit-hooks: trailing whitespace, EOF, YAML/JSON/TOML validation, large file guard, no direct commits to master - Auto-fixed trailing whitespace and missing EOF newlines across repo - Added make pre-commit and make pre-commit-update targets - install target now runs pre-commit install automatically Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	4 个月前
.github	clean up obsolete Docker scripts and align CI build commands	2 个月前
.vscode	chore: add pre-commit hooks for linting, formatting, and secret detection - ruff check + ruff-format enforce code style on every commit - detect-secrets blocks accidental API key/secret commits - pre-commit-hooks: trailing whitespace, EOF, YAML/JSON/TOML validation, large file guard, no direct commits to master - Auto-fixed trailing whitespace and missing EOF newlines across repo - Added make pre-commit and make pre-commit-update targets - install target now runs pre-commit install automatically Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	4 个月前
alembic	changes	2 个月前
app	Merge pull request #83 from JFer11/fix/langfuse-init-startup-crash Don't let Langfuse auth failures crash startup	2 个月前
docs	changes	2 个月前
evals	chore: remove genuinely stale unused imports The 19 unused imports left over after PR-1..8 were not legitimate re-exports — alembic/env.py uses explicit `# noqa: F401` for the model imports it actually needs (Session, Thread, User), and that file isn't even in pyright's scope. The remaining warnings were dead `from typing import Optional, List, Union, Dict, Any` left over from pre-3.10 typing migrations, plus a few genuinely orphaned imports (`json` in config.py, `db_connections` in middleware.py, `tqdm` in evals/main.py, `asyncio` in evals/evaluator.py, re-exported `Message`/`List` in chatbot.py and models). Auto-fixed via `ruff check --select F401 --fix` (a one-shot override of the project's F401 ignore — the ignore stays in place for legitimate noqa cases). Promotes pyright `reportUnusedImport` from warning to error so future stale imports break the build. Baseline: 41 -> 22 warnings, all remaining warnings are stable third-party/style categories. Files cleaned: app/api/v1/chatbot.py, app/core/config.py, app/core/logging.py, app/core/middleware.py, app/models/base.py, app/models/session.py, app/utils/sanitization.py, evals/evaluator.py, evals/helpers.py, evals/main.py. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	4 个月前
grafana	added a panel for average latency and request count too	1 年前
prometheus	added cadvisor and grafana	1 年前
scripts	Merge pull request #81 from JFer11/fix/docker-migration-flow Fix broken initial migration and add explicit Docker migration commands	2 个月前
typings	feat: add pyright static type checker Wires pyright into the dev tooling: pyproject.toml config (basic mode with stub-gap rules demoted to warning), Makefile targets (typecheck, check), pre-commit hook, and a new CI workflow that runs ruff + pyright on PR/push to master. Genuine bugs surfaced and fixed in the same pass: - app/services/memory.py: AsyncMemory and metadata defaults typed as bare AsyncMemory/dict instead of Optional - app/services/llm/service.py: @overload with Type[T] default left T unsolvable; made keyword-only and required Side fixes: Makefile lint/format now use `uv run` (was bare ruff, broken in venv-only setups); ruff added to [dependency-groups].dev so default `uv sync` installs it. Baseline: 0 errors, 94 warnings — warnings are real signal for a follow-up cleanup pass (mostly SQLModel/SQLAlchemy stub gaps). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	4 个月前
.dockerignore	Add evaluation framework and related configurations - Introduced a new evaluation framework in `evals` directory, including `Evaluator` class for model output evaluation. - Added helper functions for processing evaluation metrics and generating reports. - Updated `Makefile` with commands for running evaluations in different modes. - Enhanced `README.md` to document the evaluation framework and usage instructions. - Updated `.dockerignore` and `.gitignore` to include evaluation reports directory. - Added new dependencies in `pyproject.toml` for `tqdm` and `colorama` to support progress bars and colored output. - Configured evaluation settings in `app/core/config.py` for better flexibility. - Created metric prompts for evaluation criteria in `evals/metrics/prompts` directory. - Implemented command-line interface in `evals/main.py` for user interaction during evaluations.	1 年前
.env.example	install Docker dependencies from uv.lock to prevent version drift	2 个月前
.gitattributes	fix: improve Windows/WSL compatibility - Gate uvloop to non-Windows platforms in pyproject.toml - Remove --loop uvloop from make dev (uvicorn auto-detects the loop) - Add .gitattributes to enforce LF line endings on scripts and env files Fixes #43 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	4 个月前
.gitignore	Add evaluation framework and related configurations - Introduced a new evaluation framework in `evals` directory, including `Evaluator` class for model output evaluation. - Added helper functions for processing evaluation metrics and generating reports. - Updated `Makefile` with commands for running evaluations in different modes. - Enhanced `README.md` to document the evaluation framework and usage instructions. - Updated `.dockerignore` and `.gitignore` to include evaluation reports directory. - Added new dependencies in `pyproject.toml` for `tqdm` and `colorama` to support progress bars and colored output. - Configured evaluation settings in `app/core/config.py` for better flexibility. - Created metric prompts for evaluation criteria in `evals/metrics/prompts` directory. - Implemented command-line interface in `evals/main.py` for user interaction during evaluations.	1 年前
.pre-commit-config.yaml	feat: add pyright static type checker Wires pyright into the dev tooling: pyproject.toml config (basic mode with stub-gap rules demoted to warning), Makefile targets (typecheck, check), pre-commit hook, and a new CI workflow that runs ruff + pyright on PR/push to master. Genuine bugs surfaced and fixed in the same pass: - app/services/memory.py: AsyncMemory and metadata defaults typed as bare AsyncMemory/dict instead of Optional - app/services/llm/service.py: @overload with Type[T] default left T unsolvable; made keyword-only and required Side fixes: Makefile lint/format now use `uv run` (was bare ruff, broken in venv-only setups); ruff added to [dependency-groups].dev so default `uv sync` installs it. Baseline: 0 errors, 94 warnings — warnings are real signal for a follow-up cleanup pass (mostly SQLModel/SQLAlchemy stub gaps). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	4 个月前
.python-version	init commit	1 年前
.secrets.baseline	chore: add pre-commit hooks for linting, formatting, and secret detection - ruff check + ruff-format enforce code style on every commit - detect-secrets blocks accidental API key/secret commits - pre-commit-hooks: trailing whitespace, EOF, YAML/JSON/TOML validation, large file guard, no direct commits to master - Auto-fixed trailing whitespace and missing EOF newlines across repo - Added make pre-commit and make pre-commit-update targets - install target now runs pre-commit install automatically Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	4 个月前
AGENTS.md	clean up obsolete Docker scripts and align CI build commands	2 个月前
CLAUDE.md	chore: add pre-commit hooks for linting, formatting, and secret detection - ruff check + ruff-format enforce code style on every commit - detect-secrets blocks accidental API key/secret commits - pre-commit-hooks: trailing whitespace, EOF, YAML/JSON/TOML validation, large file guard, no direct commits to master - Auto-fixed trailing whitespace and missing EOF newlines across repo - Added make pre-commit and make pre-commit-update targets - install target now runs pre-commit install automatically Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	4 个月前
Dockerfile	install Docker dependencies from uv.lock to prevent version drift	2 个月前
LICENSE	chore: add MIT license	1 年前
Makefile	changes	2 个月前
README.md	docs: add FAQ section to README Adapted from PR #70 by @meichuanyi with corrections: clarified that multi-provider LLM support is planned (#51) not current, removed the nonexistent mem0 API key reference (memory is self-hosted via pgvector), and pointed rate-limit troubleshooting at app/core/limiter.py.	3 个月前
SECURITY.md	docs: overhaul documentation with dedicated guides and Mermaid diagrams - Rewrite README to a short landing page (~60 lines) with links to docs/ - Add docs/ directory with 9 focused guides: - getting-started.md: Docker + local setup, first API call, customisation points - architecture.md: system overview, request lifecycle, agent graph (Mermaid) - configuration.md: all env vars with defaults, grouped by concern - database.md: ER diagram, schema explanation, Alembic migration guide - authentication.md: JWT flow diagram, all auth endpoints documented - llm-service.md: model registry, retry/fallback flowchart - memory.md: mem0 + cache sequence diagram, per-user isolation - observability.md: Langfuse, structured logging, Prometheus, profiling - evaluation.md: eval framework, custom metrics, report format - docker.md: full service diagram including Valkey and cAdvisor - Rewrite SECURITY.md (was GitHub template placeholder with fake version numbers) - Delete schema.sql (stale SQLite syntax, replaced by docs/database.md + Alembic)	4 个月前
alembic.ini	feat: integrate Alembic for database migrations - Added Alembic configuration file (alembic.ini) for managing database migrations. - Implemented environment setup for Alembic in env.py to dynamically load database URL from application settings. - Created initial migration script for adding optional username fields to User and Session models. - Updated Makefile with commands for running migrations and managing database states. - Included Alembic as a dependency in pyproject.toml and updated lock file. This setup allows for streamlined database schema management and version control.	4 个月前
docker-compose.yml	chore: add pre-commit hooks for linting, formatting, and secret detection - ruff check + ruff-format enforce code style on every commit - detect-secrets blocks accidental API key/secret commits - pre-commit-hooks: trailing whitespace, EOF, YAML/JSON/TOML validation, large file guard, no direct commits to master - Auto-fixed trailing whitespace and missing EOF newlines across repo - Added make pre-commit and make pre-commit-update targets - install target now runs pre-commit install automatically Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	4 个月前
pyproject.toml	chore: drop SQLModel typing workarounds via sqlmodel>=0.0.25 + col() Two changes that together remove every `# pyright: ignore` comment from the SQL services: * Bumped `sqlmodel>=0.0.25` (was 0.0.24). Release 0.0.25 includes PR #1342, which adds @overload coverage for Insert/Update/Delete to Session.exec — closing sqlmodel#909. Fixes the reportCallIssue / reportArgumentType pair on `db.exec(stmt)` for Update statements without any code change. * Wrapped column references in `col(...)` at the four comparison / order_by sites in database.get_user_sessions and session_naming._claim_session. `col()` is the SQLModel-maintainer-recommended fix (per discussion #1391) for the class-level attribute access typing gap — `Foo.column` exposes the field's Python type instead of the SQLAlchemy column descriptor, so `Foo.col == X` types as `bool`. col() returns Mapped[T] which has the proper column operators, so .where()/.order_by() arguments typecheck cleanly. Side win: deleted the issue-reference comments that previously documented these as known gaps. The workarounds were the documentation; with col() they're no longer workarounds. State: 0 errors, 0 warnings under typeCheckingMode = "standard". Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	4 个月前
uv.lock	chore: drop SQLModel typing workarounds via sqlmodel>=0.0.25 + col() Two changes that together remove every `# pyright: ignore` comment from the SQL services: * Bumped `sqlmodel>=0.0.25` (was 0.0.24). Release 0.0.25 includes PR #1342, which adds @overload coverage for Insert/Update/Delete to Session.exec — closing sqlmodel#909. Fixes the reportCallIssue / reportArgumentType pair on `db.exec(stmt)` for Update statements without any code change. * Wrapped column references in `col(...)` at the four comparison / order_by sites in database.get_user_sessions and session_naming._claim_session. `col()` is the SQLModel-maintainer-recommended fix (per discussion #1391) for the class-level attribute access typing gap — `Foo.column` exposes the field's Python type instead of the SQLAlchemy column descriptor, so `Foo.col == X` types as `bool`. col() returns Mapped[T] which has the proper column operators, so .where()/.order_by() arguments typecheck cleanly. Side win: deleted the issue-reference comments that previously documented these as known gaps. The workarounds were the documentation; with col() they're no longer workarounds. State: 0 errors, 0 warnings under typeCheckingMode = "standard". Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	4 个月前

自动翻译

FastAPI LangGraph 智能体模板

一个可用于生产环境的模板，用于构建基于 FastAPI 和 LangGraph 的 AI 智能体后端。它处理了复杂的部分——有状态对话、长期记忆、工具调用、可观测性、速率限制、身份验证——让您可以专注于智能体逻辑。

专为 AI 工程师打造，他们需要的是坚实的基础，而非教程项目。

包含内容

LangGraph 有状态智能体，支持检查点、工具调用和人在回路
通过 mem0 + pgvector 实现的长期记忆——按用户进行语义搜索，支持缓存
LLM 服务，具有循环模型回退、指数退避重试和总超时预算
所有 LLM 调用均支持 Langfuse 追踪；Prometheus 指标 + Grafana 仪表板
带会话管理的 JWT 身份验证；通过 slowapi 实现的速率限制
Alembic 迁移；可选的 Valkey/Redis 缓存层
结构化日志，每行日志均包含请求/会话/用户上下文

快速开始

git clone <repo-url> my-agent && cd my-agent
cp .env.example .env.development   # fill in your keys
make install
make docker-up                     # starts API + PostgreSQL

打开 http://localhost:8000/docs 查看交互式 API。

如需不使用 Docker 进行本地开发，请参见 docs/getting-started.md。

文档

指南	涵盖内容
快速开始	先决条件、本地设置、首次 API 调用
架构	系统设计、请求流程、组件图
配置	所有环境变量及其默认值
身份验证	JWT 流程、会话、端点参考
数据库与迁移	模式、Alembic 迁移、pgvector
LLM 服务	模型、重试、回退、超时预算
内存	mem0 长期内存、缓存层
可观测性	Langfuse、结构化日志、Prometheus、性能分析
评估	评估框架、自定义指标、报告
Docker	Docker、Compose、完整监控堆栈

项目结构

app/
  api/v1/          # Route handlers
  core/
    langgraph/     # Agent graph + tools
    prompts/       # System prompt template
    cache.py       # Valkey/Redis + in-memory fallback
    config.py      # Settings
    middleware.py  # Metrics, logging context, profiling
    limiter.py     # Rate limiting
  models/          # SQLModel ORM models
  schemas/         # Pydantic request/response schemas
  services/        # LLM, database, memory services
alembic/           # Database migrations
evals/             # LLM evaluation framework

贡献指南

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

安全问题请私下报告——详见 SECURITY.md。

许可证

详见 LICENSE。

常见问题

基本信息

这个模板是什么？ 这是一个基于 FastAPI + LangGraph 构建的生产级 AI 智能体后端基础框架。它集成了您原本需要手动搭建的各类组件：有状态对话、长期记忆、工具调用、可观测性、速率限制以及 JWT 认证。

它与基础的 LangGraph 配置有何不同？ LangGraph 快速入门教程仅停留在“智能体本地运行”阶段。本模板额外添加了 Alembic 数据库迁移、mem0 + pgvector 长期记忆、Langfuse 追踪、Prometheus + Grafana 监控面板、JWT 会话管理、slowapi 速率限制、含请求上下文的结构化日志，以及循环回退 LLM 服务——这些都是您在生产环境中需要单独构建的关键功能。

设置与配置

我需要 Docker 吗？ 推荐使用，但并非必需。make docker-up 命令可同时启动 API 和 PostgreSQL。如需纯本地设置，请参见 docs/getting-started.md。

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

如何配置长期记忆？ 长期记忆为自托管模式：mem0 在进程内运行，并通过 pgvector 持久化到您现有的 PostgreSQL 数据库中——无需单独的 mem0 云账户或 API 密钥。您只需提供有效的 OPENAI_API_KEY（用于事实提取和嵌入生成）并启用 pgvector 扩展即可。详情参见 docs/memory.md。

开发相关

如何添加自定义工具？ 将 LangChain @tool 装饰的函数放在 app/core/langgraph/tools/ 目录下，并在该包导出的 tools 列表中注册。智能体将在下次启动时自动加载该工具，无需修改图结构。

LLM 服务如何处理故障？ 包含两层机制：(1) 通过 tenacity 实现的每调用指数退避重试；(2) 循环回退——如果当前活跃模型重试次数用尽，服务会自动切换到 LLMRegistry 中的下一个模型继续尝试。整个调用过程有总超时控制，以确保延迟可控。详见 docs/llm-service.md。

可以不使用 Langfuse 吗？ 可以。设置 LANGFUSE_TRACING_ENABLED=false（或不提供 Langfuse 密钥）即可。智能体仍可正常运行，结构化日志仍会捕获请求、会话和用户上下文。

故障排除

API 无法启动

确保 PostgreSQL 正在运行（make docker-up 会将其与 API 一同启动）
确认 .env.development 文件存在 — 从 .env.example 复制并填写必要的密钥
应用迁移：make migrate

记忆/语义搜索无结果返回

验证 PostgreSQL 实例中已启用 pgvector 扩展
确认 OPENAI_API_KEY 有效（mem0 调用 OpenAI 进行事实提取和嵌入）
检查 .env.development 中是否设置了 LONG_TERM_MEMORY_MODEL 和 LONG_TERM_MEMORY_EMBEDDER_MODEL

速率限制过于严格 限制在 app/core/limiter.py（slowapi）中定义。调整每条路由的装饰器或该文件中的默认速率。相关环境变量请参见 docs/configuration.md。