LangGraph部署实践：脚本、FastAPI自建与平台化路径怎么选-平芜编程栈

我最早用LangGraph跑Agent，就是普通的python script.py，跑完看一眼stdout，能用就行。直到有一天同事轻飘飘问了一句"你这个东西能不能给个接口"，我才意识到，从脚本到服务之间不是改一行代码的事。LangGraph本身只解决"图怎么编排"的问题，但你的Agent要真正落地上线，还得想清楚它以什么形态存在、状态存在哪里、并发来了怎么办。这篇文章就围绕LangGraph的部署，聊三条我从实际项目里趟出来的路径：纯脚本、FastAPI自建服务、平台化部署。顺便把每一条路径背后"为什么这么选"的逻辑也讲清楚。

1. 部署之前：脚本和服务之间的三条本质差异

很多人觉得"部署"是个很虚的词，说白了就是把代码从你的电脑挪到一台能长期运行的机器上，然后别人也能用。但LangGraph这种Agent框架有个特殊之处：它天然带状态，而且图的运行是分步的——一次请求可能要经过"用户输入 → 模型决策 → 工具调用 → 更新状态 → 再决策"这么一长串过程。因此脚本和服务之间的差异，远比"有没有端口"大得多。

1.1 生命周期：一次性执行与常驻进程的差别

脚本模式的生命周期是"一锤子买卖"：python agent.py启动、跑完、退出。整个Graph的状态只存在于进程内存中，进程一结束，什么都没了。而服务模式是常驻进程，7x24小时等待请求，状态要么落在内存里持续累积，要么写入外部存储被持久化。

这个差异最直接的影响，体现在LangGraph的checkpointer上。你写第一版Agent时，大概率用的是MemorySaver，它就是把每个thread_id对应的Graph状态存在内存里，方便多轮对话时回忆上下文。这在脚本里完全够用——反正脚本跑完就退，下次从头再来。可一旦你把它挂成服务，内存里的状态会越积越多，进程重启后所有会话上下文全部归零，用户会莫名其妙发现"你刚才还记得我说过什么，怎么一刷新就全忘了"。所以第一步必须想清楚：你的状态生命周期是"任务级"还是"会话级"，前者脚本够用，后者就必须接外部存储。

1.2 输入输出：从命令行参数到HTTP契约

脚本时期的输入很随意，可以是sys.argv、配置文件、环境变量，甚至直接input()。输出更是随心，print、写文件、存JSON，怎么方便怎么来。但服务化之后，你的Agent就变成了一个"接口"，别人只会通过HTTP跟你说话。

这意味着你要做一堆脚本时期完全不用操心的事：定义请求和响应的数据结构、处理错误状态码、加超时、考虑鉴权。更重要的是，Agent本身是异步的——它要编排模型调用、工具调用，一次请求可能耗时几十秒。如果按普通API的思路同步等待，调用方早等崩溃了。所以部署时要把LangGraph的流式输出（astream_events/astream）纳入考虑，让接口可以边跑边往前端推数据。

1.3 可观测性：从print到结构化日志和链路追踪

脚本时代，打几个print就是全部可观测性。出问题了大不了重跑一遍，反正输入是固定的。但服务化之后，一个Agent跑挂了你根本没法"重跑一遍"——因为它的输入来自真实用户、上下文来自历史会话、依赖的外部工具状态千奇百怪。这时候你需要的是结构化日志、耗时指标、请求链路追踪，不然排查问题时只能靠猜。

我见过很多团队在把LangGraph脚本转成服务时，第一个翻车点就是日志。脚本里的print到了FastAPI里全进了控制台，没有request_id，没有trace_id，用户报障时你连他走的是哪条图分支都查不出来。LangGraph本身会输出不少内部事件，但这些事件如果不做结构化处理，就是一堆噪音。部署之前，先把日志规范定下来，比调参重要得多。

2. 路径一：脚本模式，最轻量的起步方式

先说结论：脚本模式不是"不规范"的代名词，它有自己的适用场景，而且是大多数人开始LangGraph的第一站。

2.1 什么场景适合直接跑脚本

在我看来，以下四类场景完全没必要上服务：

个人自动化：比如每天定时抓取数据、调用LLM整理摘要、生成日报，跑完把结果写到本地或推送通知。用户只有你自己，没有并发，没有外部调用方。
批量任务：一次性处理一批文本、一批图片、一批工单，逐条调用LangGraph图去完成。这种任务天然是离线的，脚本模式再合适不过。
原型验证和算法探索：你在验证一个新的Agent编排逻辑，图的结构、工具的参数、提示词的效果都可能随时大改。这种状态下上服务完全是自找麻烦，脚本里改完就跑是最快的反馈循环。
CI/CD里的自动化测试：把Agent跑在测试流程里，验证某个流程是否按预期工作。脚本可以在无服务器环境下快速被拉起，用完即毁。

说白了，判断标准就一条：有没有"别人"要调用它。没有外部调用方，就不存在"服务"，脚本是最自然的存在形式。

2.2 脚本版LangGraph怎么组织才不乱

哪怕只是脚本，我依然建议保持一个最小化的结构边界，别真的把所有代码堆在一个main.py里。一个能长期维护的脚本项目至少应该拆成这样：

agent_scaffold/ ├── graph.py # 图定义：StateGraph、节点、边、工具绑定 ├── tools.py # 工具函数：内部服务调用、外部API封装 ├── config.py # 配置读取：环境变量、API Key、模型参数 ├── run.py # 入口：解析参数、构建图、运行并输出结果

这个结构最大的好处是，将来哪天要从脚本迁移到服务，graph.py和tools.py基本可以原封不动搬过去，你只需要把run.py换成一个FastAPI入口文件。我在项目里就是这么干的，迁移成本低于半小时。

入口部分建议用argparse或click做一个简单的CLI，把"任务类型""输入文件""会话ID"这些参数显式暴露出来。CLI的好处是它可以被各种调度器调用，比如cron、Windows计划任务、CI流水线，谁调它都一样：

# 例子：每天9点跑一次财报摘要任务 0 9 * * * cd /opt/agent-jobs && /usr/bin/python3 run.py --task finance_summary --output /data/reports/ # 例子：外部传入一个会话ID做多轮问答 python run.py --task chat --thread-id user_9527 --message "帮我总结一下这个月的开销"

2.3 脚本模式的隐藏代价

脚本模式最大的坑，不是功能不够，而是状态隔离会被你无意中忽略。比如你图里用了MemorySaver，在脚本里每次重新运行时它都会新建一个状态空间，所以你的"多轮对话"实际上每一轮都是从零开始。很多人在脚本里测对话式Agent，测了半天发现模型根本不记得前面的内容，就是因为MemorySaver的作用范围仅仅是一次进程的执行。

如果在脚本里确实需要跨任务保存状态，就得显式接入SqliteSaver或文件存储。不过我更推荐的做法是：脚本阶段不要过度设计状态，明确"每个任务是独立的"，等迁移到服务时再认真做持久化。此外，脚本模式还有一个容易被忽略的问题：环境一致性。你本地跑得好好的，放服务器上跑就报错——大概率是Python版本、系统依赖、API Key配置不一致。脚本模式下要养成把依赖和环境固定下来的习惯，pyproject.toml或requirements.txt加锁文件，部署时用虚拟环境或容器，否则定时任务会在你睡觉的时候悄悄失败。

3. 路径二：FastAPI自建服务，大多数团队的现实解

当你第一次把Agent给同事调、给前端调，或者给别的系统发请求时，脚本模式就撑不住了。这时候摆在你面前的有两条路：自己用FastAPI包一层，或者直接用官方平台。先说自建，因为它是目前大多数团队真正在走的路。

3.1 为什么是FastAPI而不是Flask，也不是官方Studio

先说FastAPI。LangGraph本身是异步友好的，图的ainvoke、astream都是async方法。FastAPI原生支持async，能直接await调用LangGraph，不用像Flask那样开线程池绕弯子。再加上Pydantic做请求校验、OpenAPI文档自动生成，写接口的体验确实是目前Python生态里最顺的。

那为什么不用官方的LangGraph Studio或LangGraph CLI？很多人有误解，以为装了langgraph-cli跑起Studio，就等于"部署上线"了。其实Studio和CLI本质是开发调试件，它们能在本地直观地看到Agent运行状态、检查点内容、节点执行情况，但那个环境不是为生产设计的——没有鉴权、没有扩展性、没有监控告警，也没有和你的现有基础设施打通。结论很简单：Studio负责"看清楚你的图在干嘛"，FastAPI负责"让你的图对外干活"。

3.2 集成LangGraph的核心代码骨架

一个最小可用的FastAPI + LangGraph服务，核心结构大概长这样：

# graph.py —— 图定义保持纯业务，不掺杂任何HTTP逻辑 from langgraph.graph import StateGraph, START from langgraph.graph.message import add_messages from typing import Annotated, TypedDict class AgentState(TypedDict): messages: Annotated[list, add_messages] def build_graph(checkpointer): g = StateGraph(AgentState) g.add_node("agent", call_model) g.add_node("tools", call_tools) g.add_edge(START, "agent") g.add_conditional_edges("agent", should_continue, ["tools", "__end__"]) g.add_edge("tools", "agent") return g.compile(checkpointer=checkpointer)

# server.py —— 只负责HTTP层 from fastapi import FastAPI from pydantic import BaseModel from langgraph.checkpoint.sqlite import SqliteSaver from graph import build_graph app = FastAPI(title="Agent Service") # 注意：graph和checkpointer都要在模块级别创建，千万别放进请求函数里 _checkpointer = SqliteSaver.from_conn_string("sqlite:///agent_state.db") _graph = build_graph(checkpointer=_checkpointer) class ChatRequest(BaseModel): thread_id: str message: str @app.post("/chat") async def chat(req: ChatRequest): config = {"configurable": {"thread_id": req.thread_id}} result = await _graph.ainvoke( {"messages": [("user", req.message)]}, config=config, ) return {"messages": result["messages"]}

代码量不多，但有一个关键点必须强调：graph实例必须在模块级别创建一次。如果你把build_graph()写在路由函数内部，意味着每一个请求都会重新构建一次整张图，图的节点、边、工具绑定全部从头做一遍。实测下来，这种写法的性能会差一到两个数量级，高并发时CPU直接被打满，而且容易触发模型客户端连接数饱和。

3.3 会话状态与checkpointer的接线方式

脚本阶段你可能从没认真考虑过"状态存哪"，但服务化之后这个问题的答案直接决定你能不能上线。

MemorySaver在服务里最大的问题是：所有请求共享同一个进程内的状态存储，并且进程重启即丢。一旦你的服务被重启（发版、崩溃、扩容），所有用户的对话上下文全没了。所以生产级别的接法一般从以下三种里选：

SqliteSaver：适合单实例部署、请求量中等（每秒个位数到两位数）的场景。部署简单，文件即数据库，备份也方便。上一节代码里用的就是它。
PostgresSaver：适合多实例部署、需要水平扩展的场景。所有实例共享同一个Postgres存储，换一个节点也能读到同一个thread_id的历史状态。这是目前生产环境最主流的选择。
Redis等KV存储：如果你只需要保存最近几轮上下文，可以自己把状态序列化到Redis。优点是快，缺点是需要自己处理LangGraph的检查点协议，可别自作聪明地仓促实现——官方PostgresSaver已经做了大量序列化工作。

关于checkpointer的使用，有个细节值得多说一句：thread_id是隔离会话的唯一标识，你在设计它时就要考虑好命名规则。我见过直接把用户ID当thread_id的，结果同一个用户的所有对话全部串在一起——用户上午聊A项目、下午聊B项目，模型把上午的上下文全带出来了。正确做法是user_id:scene_id:random_salt这种组合，保证每个会话独立的同时，事后还能从ID反查用户和场景。

3.4 并发、超时和流式输出：服务化最容易翻车的三个点

把LangGraph做成FastAPI服务之后，真正的考验在细节里。这里列三个我踩过不止一次、周围同事也普遍中招的点。

第一个坑是异步和同步混用。你也许会在某个工具里调一个同步的第三方SDK，比如requests.post()。如果这个调用直接堵在async路由里，事件循环会被卡住，后续所有请求都得排队。LangGraph的图里工具节点是常驻线程池执行的，但如果整个图是用ainvoke跑在async环境里，工具内部的同步阻塞依然会影响吞吐。我的经验是：工具函数尽量写成async版本，或者用asyncio.to_thread包装同步调用。

第二个坑是超时控制。Agent调用模型的耗时，正常情况下三四秒，慢的时候十几秒甚至更久。但工具调用更不可控——某个API挂了可能让整个图卡到天荒地老。LangGraph的节点执行默认没有全局超时，你得自己在图定义或工具内部做防护。一个实用策略是给每个外部调用设置独立的超时和重试策略，重要工具失败时直接走图里的错误分支，而不是无限等待。

第三个坑是流式输出。如果你的前端需要"打字机效果"，就不能用ainvoke拿最终结果。LangGraph官方推荐用astream_events拿到节点级别的事件流，然后通过StreamingResponse以SSE（Server-Sent Events）推给前端。一个常见误区是直接在路由里把astream的输出转成JSON丢给前端，前端会因为格式混乱而崩溃。正确做法是定义好事件协议，比如：

@app.post("/chat/stream") async def chat_stream(req: ChatRequest): config = {"configurable": {"thread_id": req.thread_id}} async def event_gen(): async for event in _graph.astream_events( {"messages": [("user", req.message)]}, config=config, version="v2", ): if event["event"] == "on_chat_model_stream": delta = event["data"]["chunk"].content if delta: yield f"data: {delta}\n\n" return StreamingResponse(event_gen(), media_type="text/event-stream")

这样前端只需要解析SSE的data行，就能实现逐字输出。说句实在话，流式这块的调试成本比想象中高，但你一旦做出来，整个Agent产品的体验会有一个质的提升。

4. 路径三：平台化与微服务化，把部署交给平台

当你不再只有一个Agent，而是一整套Agent体系——有客服Agent、数据分析Agent、自动化运维Agent——每条路径都自己搭FastAPI、自己管数据库、自己配监控，运维成本会爆炸。这时候就该考虑第三条路：平台化。

4.1 LangGraph Platform能替你解决什么

LangGraph Platform是官方提供的部署服务平台，分云托管和自托管两种形态。它主要解决四件事：

自动把LangGraph图变成REST API：你不用再手写FastAPI那一层，编译好的图直接暴露/messages、/runs、/threads等接口，还能配合thread_id管理会话。
内置持久化层：官方平台把checkpointer的存储作为一个托管服务，你甚至不用知道数据存在哪个数据库。
带权限和访问控制：API Key管理、用户隔离这些都有默认实现，省去自己造轮子的时间。
辅助监控和调试：它把图的运行轨迹、节点耗时、token消耗直接可视化。这个在生产环境排障时太重要了，你能一眼看到失败发生在哪个节点。

如果你用的是自托管方式，流程也相对固定：langgraph-cli会构建一个包含你的图、依赖和配置的Docker镜像，然后在服务器上跑起来：

# 构建镜像 langgraph build -t my-agent:latest # 本地验证 docker run -e OPENAI_API_KEY=$OPENAI_API_KEY -p 8123:8000 my-agent:latest

容器内部的8000端口就是LangGraph API Server，映射到宿主机的8123后，你的业务系统直接访问http://server:8123就可以调用Agent。这个方案比从零手写FastAPI要多一层"标准化的API契约"，而且官方把LangGraph升级时的兼容性都做好了，你不会因为小版本升级而把API逻辑重写一遍。

4.2 自托管路线的边界：官方镜像加业务容器编排

如果不想被平台绑定，也可以走"你出容器、官方出镜像"的混合路线：LangGraph镜像只负责跑图，业务系统（前端、工单系统、CMS）单独部署，中间用API网关统一接入。这样Agent部分获得了官方的稳定性和运维保障，业务部分依然保持你的自由度。

实际部署时要注意一个容易忽略的点：Docker容器里的时区、环境变量、日志采集。比如Agent内部要按北京时间生成日报，而容器默认是UTC，你检查点时看到的created_at永远比预期晚8小时。诸如此类的小问题，在脚本阶段不存在，平台化之后反而需要纳入镜像构建规范里。

4.3 微服务架构下LangGraph的定位

有些团队会走到"微服务拆分"这一步，LangGraph在其中往往扮演"编排大脑"的角色。这时候你要注意它的边界：LangGraph负责的是流程编排和上下文管理，不是万物中转站。

我在实际项目里的拆分思路是这样的：

Agent编排层：单独部署LangGraph服务（或平台托管），负责接收用户请求、调度模型、调用工具、维护会话状态。
工具服务层：每个工具/工具组独立成服务，比如搜索引擎的封装是一个服务，内部数据库查询又是一个服务。Agent层的工具函数只需要向这些服务发HTTP请求。
模型网关层：如果多个Agent共用同一套模型配置，可以单独做一个模型网关服务，统一管理API Key、模型路由、限流和成本统计。
数据服务层：向量数据库、业务数据库、对象存储各自独立，Agent不直接连库，而是通过数据服务接口访问。

这个拆分的好处是，整个链路里每一部分都可以独立伸缩、独立发布、独立排查。坏处也很明显：Agent调一个工具变成调一个网络接口，延迟上去了，出错的环节也变多了。所以微服务化不是越早越好，而是当你的工具函数开始被多个Agent复用、或者某个工具调用量开始显著超过平均水平时，才值得动手。

5. 怎么选：一张取舍表和我踩过的坑

最后把三条路径放到一起做一个直观的对比，顺便把我个人实际踩过的坑和最终选择逻辑分享出来。

维度	脚本模式	FastAPI自建	平台化/微服务
开发上手速度	最快，半天搞定	较快，要写的工程代码不少	学习成本偏高
状态管理	进程内存/本地文件	自己接数据库	平台内置或独立服务
并发扩展	基本没有	单实例靠异步，多实例要加负载均衡	面向扩展设计
运维成本	几乎没有	日志监控数据库备份全得自己管	平台兜底大部分
可控性和自由度	最高	高	受平台约束
适用阶段	验证、个人、批量离线任务	团队生产API、单一或少数Agent	多Agent、高并发、复杂组织架构

这条路线怎么选，我个人的判断依据是"三个什么时候"：

什么时候不用上服务？只要Agent的调用方是你自己的脚本、定时任务、CI流程，脚本模式就足够。别再纠结什么微服务，需求和规模都还没到。
什么时候该上FastAPI？第一个外部调用方出现的时候。哪怕只是一个前端页面来对接，它也需要一个稳定的、带鉴权和超时控制的接口。此时FastAPI + SQLite/PG是性价比最高的组合。
什么时候该平台化？当你有两个以上的Agent、需要共享监控能力、需要更多人协作、或者你发现自己在重复做"接口层平台能力"的时候。这时平台的收益才能覆盖它的学习成本和约束。

5.1 我踩过的坑清单

把这几条写在最后，因为它们都是代码本身不报错、只在上线后被用户锤爆的问题：

第一，同一个thread_id在测试环境被反复使用。我在开发阶段用固定IDtest1测试了无数次，结果接生产后忘了切换逻辑，所有用户都共用同一个会话历史。上线半小时内用户对话全互相串台，直接回滚。教训是：thread_id生成规则要在一开始就设计好，并且通过请求上下文注入，绝不能写死在配置里。

第二，SqliteSaver的锁问题。单实例低并发时SQLite够用，但一旦并发请求到两位数，SQLite会出现数据库被锁的错误。我自己是在高峰期被报警炸醒后，默默把后端换成了Postgres。所以如果你的服务预期有并发，直接上PostgresSaver，别在SQLite上纠结优化。

第三，工具里没有超时。有一次Agent去调一个外部天气API，对方服务挂了，我的工具函数一直在等待。因为FastAPI的路由超时设置得比较长，结果一个用户的请求占了整整两分钟才返回，而且期间占用了线程池。后来所有工具函数统一加了超时和降级逻辑，这个问题才算根治。工具调用是Agent最脆弱的地方，你有多少外部依赖，就有多少隐患。

第四，日志没有trace关联。最早我图方便，在FastAPI里打了几个print，结果Agent报错时查半天也不知道是哪个节点、哪个请求。后来老老实实把request_id传到LangGraph的config里，并在每个节点函数开头把节点名、request_id、当前消息数打出来，排查问题的效率完全不一样。这一点强烈建议越早做越好。

5.2 我的最终建议

我给大多数团队的路线图是这样的：脚本阶段先把Graph和工具拆开，为将来迁移留好结构；当第一个外部调用方出现时，用FastAPI包一层，数据库直接选Postgres；当Agent数量和团队协作复杂度上来之后，再评估平台化或微服务拆分。这条路每一步都是顺滑过渡，不需要推到重来。

最后分享一个我比较受益的小习惯：给LangGraph的检查点加metadata，在config里放进用户ID、场景来源、请求ID。这样你在排查问题时，只要看到一个thread_id，就能知道这个会话属于谁、从哪个页面来的、走的哪条链路。这东西在脚本阶段感知不强，等服务上了生产，能帮你省下大量跟用户对质的时间。