用 FastAPI + LangGraph + MCP 搭 AI Agent,我踩了哪些坑
尝试将 FastAPI、LangGraph 与 MCP(Model Context Protocol)这三种技术栈整合,构建一个 AI Agent 系统,在理论上是可行的,但在实际落地过程中却遇到了诸多意料之外的工程难题。从事件循环冲突到并发性能瓶颈,整个调试过程涉及对底层运行机制的深入理解。本文将梳理五个核心技术难点及其相应的解决方案,为开发者提供实战参考。
01事件循环冲突问题
在集成初期,最直接的报错是“Event loop is closed”。这通常发生在尝试在 LangGraph 的节点函数中调用 MCP Client 时。问题的根源在于 MCP 的 ClientSession 依赖于异步上下文管理器(async with),每次调用都会尝试新建连接并管理事件循环,而 LangGraph 的节点函数可能被多次调用,且 FastAPI 自身拥有独立的事件循环管理机制,两者在资源争夺上产生了冲突。
- 问题现象
一运行即报错 Event loop is closed,导致服务无法启动。 - 原因分析
MCP Client 试图独占事件循环,与 LangGraph 和 FastAPI 的循环管理机制不兼容。 - 解决方案
将 MCP Client 的初始化逻辑提升到 Graph 外部,将其作为全局变量进行复用,避免在节点函数内部重复创建会话。
02多进程初始化与状态传递
解决了单次运行的问题后,部署到 FastAPI 生产环境(通常为多 Worker 架构)时,服务再次崩溃。这是由于在主进程中初始化的 mcp_client 无法被子进程访问,各 Worker 进程拥有独立的内存空间。同时,LangGraph 的节点函数设计遵循“状态驱动”原则,不直接支持 FastAPI 的依赖注入机制(如 Request 或 App 对象),导致无法直接获取 App State 中的客户端实例。
- 问题现象
单元测试通过,但并发请求或多 Worker 部署时服务报错或无法获取客户端。 - 原因分析
多进程内存隔离导致全局变量失效,且 LangGraph 节点函数缺乏获取外部上下文的标准接口。 - 解决方案
利用 contextlib.asynccontextmanager 在 FastAPI 启动时初始化客户端并存入 app.state,并通过自定义 State 类型将其传入 LangGraph 图中,作为基础设施参数传递。
03数据序列化异常
在数据流转环节,如果 MCP Server 返回的结果包含自定义类型(如 datetime 对象或 Pydantic 模型实例),直接将其塞入 LangGraph 的 State 会引发报错。LangGraph 为了支持状态持久化和检查点机制,要求 State 数据必须能够被 JSON 序列化,非标准类型会导致系统无法正常处理中间状态。
- 问题现象
状态更新时报错,提示数据类型无法序列化。 - 原因分析
MCP 返回的数据结构包含 Python 对象或复杂类型,不符合 JSON 标准格式。 - 解决方案
编写数据转换中间件,在数据进入 State 之前,将所有返回结果强制转换为纯字典结构或基础 JSON 兼容类型。
04并发性能瓶颈
在功能跑通后进行压测时,系统在并发请求下响应迅速恶化,最终卡死。这是由于 MCP Client 与 Server 之间默认采用 STDIO(标准输入输出)传输,这种传输方式本质上是串行的,不支持高并发。所有请求都在排队等待同一个连接释放,导致吞吐量极低。
传输方案对比
STDIO 传输(原方案)
默认配置,存在严重并发缺陷
- 基于标准输入输出
- 不支持并发请求
- 高负载下导致排队阻塞
独立进程/SSE(优化方案)
解决并发问题,但存在资源开销
- 每个请求独立启动 Server 进程
- 或使用 SSE(Server-Sent Events)
- 进程间通信开销较大,但可并发运行
05总结与展望
经过上述五个阶段的问题排查与优化,最终形成了一个可用的 AI Agent 基础版本。虽然代码在逻辑上已经跑通,但在工程化层面仍需补充大量的异常处理、重试机制及超时控制。FastAPI + LangGraph + MCP 的组合具有强大的潜力,能够构建灵活的智能应用,但开发者需要充分理解各组件的底层交互机制,才能在复杂的生产环境中稳定运行。
当前文章无评论,是时候发表评论了