做 LangGraph 应用做久了，一定会撞上这样一个场景：图逻辑越拆越细、子图越来越多，一张状态图里塞十几个节点，想改一个分支就得重新发布整张图。更头疼的是不同团队维护的图散落在各自仓库里，你想把对方的能力直接接进自己的流程，只能复制代码、各自维护，版本一多直接失控。RemoteGraph 就是为这种问题准备的，它把一张完整的 LangGraph 图打包成可通过 URL 调用的远程服务，本地图可以像接入一个普通节点那样，把远程图嵌进来组合运行。
这篇文章是我在实际项目中趟过的经验整理，不讲照搬文档的空话，重点拆三件事：RemoteGraph 底层的组合机制是什么，本地图和远程图之间靠什么通信，以及真正组合时哪些配置最容易被忽略。适合正在用 LangGraph 搭多代理应用、想把图服务化拆出去、或者需要多人协作维护图的开发同学。我会尽量把原理讲透，同时给出可以直接抄的代码和参数。
1. 为什么需要 RemoteGraph：本地图的三个边界
1.1 资源边界：一张图不能只在一台机器上跑
先说你最容易遇到的问题。图里如果挂了比较重的计算——批量 embedding、大模型推理、密集型向量检索，全都塞进同一个进程，内存、显存、CPU 会互相挤占。我见过一个知识库问答项目，本地图里用一个节点跑召回，一个节点跑生成，看着挺清爽，上线后发现召回节点一压垮整个进程，问答节点跟着一起超时。
把重活抽出来独立部署成远程图之后，事情就简单了：本地图只做编排和轻逻辑，重计算跑在专门的机器上，两边资源互不干扰。RemoteGraph 就是这种“拆服务”的载体。它让图不再是只能在本地进程里跑的对象，而是变成一个 URL，任何有权限的客户端都能调用。资源隔离、独立扩缩容、按需重启，这些都是本地图很难做到的。
1.2 团队边界：代码耦合是协作的隐形杀手
第二个边界是团队协作。多个团队各维护一张子图，如果靠代码仓库互相引用，就意味着每次改动都要联动发版。A 团队改了内部实现，B 团队必须跟着升级依赖、重新部署，不然接口一断就线上故障。
RemoteGraph 把图变成了接口。团队之间只需要约定好状态 Schema（输入什么、输出什么），远程图内部随便重构。服务的稳定性、灰度发布、回滚，都由图的提供方自己负责。消费方看到的就是一个 URL 加一份接口文档。
我在一家做内容平台的公司里见过这种协作方式：一个团队维护“素材理解”图，负责图片识别、标签提取、文本分类；另一个团队维护“推荐生成”图，负责排序和个性化。两边通过 RemoteGraph 对接后，素材团队升级模型完全不需要通知推荐团队，只要保持输入输出的 JSON 结构不变，组合关系就一直是稳的。这是代码共享模式没法比的效率。
1.3 复用边界：一次部署，多处组合
还有一个容易被忽视的好处是复用。同一张“文档问答”图，顶部入口可能是 Web 应用，也可能是内部运营工具，还可能是自动化的批处理任务。如果每个入口都复制一份图代码，等于同时维护 N 份逻辑，改一个 prompt 要改 N 个仓库。
把通用能力做成远程图，所有入口通过同一个 URL 调用，图只部署一份，逻辑只维护一份。这在多项目多团队的场景下收益非常明显。
2. 核心机制拆解：RemoteGraph 如何“伪装”成本地图
2.1 调用协议：HTTP 之上跑了一整套图运行时
RemoteGraph 关键的设计是：它实现了本地 Runnable 的协议，所以在你的图代码里，它看起来就是一个可以 invoke、可以 stream 的普通对象。但底层每一次调用，走的都是 HTTP 请求，抵达的是远程的 LangGraph 服务端点。
远端的服务不只是“接收参数、返回结果”那么简单，它跑了一整套图运行时。包括图的执行、节点的调度、状态的维护、中断恢复、持久化，全都在远端发生。客户端只负责把输入状态发过去，再把输出状态拿回来。
打个比方：本地子图像你直接把零件拿过来组装，RemoteGraph 像是打电话叫供应商送一整套模块过来。零件还是那个零件，但你不需要自己管理它的生产过程和库存。
这意味着你在本地图里怎么调用一个子图，就可以怎么调用远程图——比如invoke、stream、ainvoke、astream，这些方法远程图基本都有。组合的代码写起来，和组合本地子图的体验非常接近，这是 LangGraph 做得很顺的一点。
2.2 状态 Schema：跨图传递的数据契约
本地图和远程图之间不是靠函数参数传值，而是靠状态（state）来对接。每张 LangGraph 图都有自己定义的输入 Schema 和输出 Schema，远程图也不例外。
组合的时候，你需要保证本地图的状态里包含远程图需要的字段。远程图跑完，会把输出字段合并进本地状态，供后续节点使用。
举个例子，远程图定义输入为：
class InputState(TypedDict): question: str user_context: dict输出为：
class OutputState(TypedDict): answer: str sources: list那么本地图的状态里至少得有question和user_context，并且在远程图返回后，本地逻辑要取answer和sources继续处理。这一步看起来简单，实际踩坑最多，后文“常见问题”部分会展开讲。
这里有一个关键点：所有跨图的数据都必须能 JSON 序列化。本地进程里你可以随意传自定义对象、datetime、numpy 数组，但是跨 HTTP 边界，一切都会被序列化成 JSON，再反序列化成 Python 对象。所以设计远程图接口时，尽量用基础类型和普通 dict/list，别依赖自定义类对象。
2.3 运行时能力：stream、interrupt 与持久化
很多人在第一次用 RemoteGraph 时，默认把它当成“远程函数”，即发一个请求收一个响应。但实际上，远程图是完整的 LangGraph 图，它支持流式输出、人工中断、持久化对话，这些能力在组合时都可以直接使用。
- 流式输出：
stream方法可以按事件返回远端图的运行过程。你可以实时拿到messages流、节点更新等，在自己本地图里透传给前端，而不是等远端全部跑完再一次性返回。 - 中断恢复：如果远程图里有
interrupt()节点，运行到那里会暂停，等待人工输入。客户端拿到暂停状态后，可以用同一个线程再次调用，传入人工反馈，远程图会从暂停位置继续跑。这种“人机协同”在审核、确认场景里非常实用。 - 持久化：远程图服务通常自带持久化能力。只要你传了
thread_id，远端就会维护这个线程的历史状态。下一次调用同一线程，它记得之前聊过什么。这解决了会话记忆的存储问题，本地图完全不需要自己 hold 对话历史。
也就是说，RemoteGraph 不止是把计算搬到了远端，还把 LangGraph 运行时里那套复杂的状态管理和控制流能力一并搬了过去。你在组合图时，可以把远程图当做一个“有记忆、可暂停、能实时汇报”的智能节点来用。
3. 动手实操：构建一个本地 + 远程的组合图
3.1 服务端：把图部署成可调用的远程图
先演示如何把一张普通图变成 RemoteGraph 服务。假设我们有一张“资料检索图”，它接收一个问题，从内部知识库检索相关资料，然后生成带来源的回答。
服务端代码只需要正常定义图：
from typing import TypedDict from langgraph.graph import StateGraph, END class State(TypedDict): question: str answer: str sources: list def retrieve(state: State) -> dict: # 实际逻辑省略：向量检索 + 候选召回 return {"sources": [...]} def generate(state: State) -> dict: # 实际逻辑省略：基于 sources 生成答案 return {"answer": "..."} builder = StateGraph(State) builder.add_node("retrieve", retrieve) builder.add_node("generate", generate) builder.add_edge("retrieve", "generate") builder.set_entry_point("retrieve") builder.add_edge("generate", END) graph = builder.compile()部署时，用 LangGraph 自带的服务命令把它启动起来。不同版本命令略有差异，老版本用langgraph dev，新版本倾向langgraph up，本质都是在本机起一个带 API 的服务，并把上面编译好的图暴露出去。服务起来后，会打印出访问地址，一般是http://localhost:2024这样的形式。
服务端还有两个细节要注意：
- 图 ID：部署后每张图都有一个唯一的 ID，通常默认跟图的变量名或模块名相关。客户端
RemoteGraph第一个参数就是它，写错一个字母都会导致 404。 - 端口：默认端口每家环境可能不一样，部署时最好显式指定，比如
--port 2024，不然客户端配置容易对不上。
3.2 客户端：本地图里接入远程节点
现在写本地图。你不需要在本地重新实现检索逻辑，直接通过 RemoteGraph 调用远端的“资料检索图”。
from langgraph_sdk import RemoteGraph remote_graph = RemoteGraph( "research_agent", # 这是服务端注册的图 ID url="http://localhost:2024", api_key="your-api-key", # 服务端开启了认证就需要传 )接着定义本地图。我习惯用一个包装函数来承接远程图调用，这样方便统一处理超时、重试和异常：
from langgraph.graph import StateGraph, END from typing import TypedDict class LocalState(TypedDict): question: str context_text: str final_answer: str def call_research_agent(state: LocalState) -> dict: # 只把远程图需要的字段传过去 remote_input = { "question": state["question"], "user_context": {"context_text": state["context_text"]}, } result = remote_graph.invoke(remote_input) return {"final_answer": result["answer"]} builder = StateGraph(LocalState) builder.add_node("research", call_research_agent) builder.set_entry_point("research") builder.add_edge("research", END) local_graph = builder.compile()跑起来：
output = local_graph.invoke({ "question": "LangGraph 支持远程图组合吗？", "context_text": "用户在查看技术文档", }) print(output["final_answer"])注意上面的remote_input只传了远程图需要的字段。很多人在这一步踩坑：本地图状态里字段很多，图方便全量传过去，结果远端 Schema 不认。Serde（序列化）报错还算好的，有些服务端会悄悄丢掉未知字段，最后结果少一块，排查起来很闹心。建议只传远端需要的字段，回来也只取自己需要的字段，显式一点永远更稳。
如果你希望本地调用远程图时也能实时拿消息流（比如把远端生成过程透传到前端），可以用stream替代invoke：
def call_research_agent_stream(state: LocalState) -> dict: final_answer = "" for event in remote_graph.stream( {"question": state["question"]}, stream_mode="values", ): # 根据实际返回结构取出 answer 的最新值 answer = event.get("answer") if answer: final_answer = answer return {"final_answer": final_answer}3.3 组合模式进阶：串行、并行、动态路由
单点接入只是最基础的一种。实际项目里，我更常用的是下面三种组合结构。
串行管道：本地图先做预处理，再调远程图，最后本地兜底输出。
builder.add_node("preprocess", preprocess) builder.add_node("remote_core", call_remote_core) builder.add_node("postprocess", postprocess) builder.set_entry_point("preprocess") builder.add_edge("preprocess", "remote_core") builder.add_edge("remote_core", "postprocess") builder.add_edge("postprocess", END)这种结构适合“轻本地、重远端”的分工。本地负责性能敏感的简单逻辑，复杂语义推理交给远程。
并行分发：一张本地图同时调用多个远程图，最后汇总。
from langgraph.constants import Send def dispatch_remotes(state): return [ Send("qa_remote", {"task": "qa", "question": state["question"]}), Send("summary_remote", {"task": "summary", "question": state["question"]}), ] builder.add_node("dispatcher", dispatch_remotes) builder.add_node("qa_remote", call_qa) builder.add_node("summary_remote", call_summary) builder.add_node("merger", merge_results)并行模式下，多个远程图同时开工，互不等待。注意别把所有请求打到一个服务上，最好给不同远端配不同的 URL。如果共用同一个服务，得确保服务端能扛住并发，否则很容易超时。
动态路由：根据输入内容判断走哪张远程图。
def route(state): if "代码" in state["question"]: return "code_expert" if "设计" in state["question"]: return "design_expert" return "general_expert" builder.add_conditional_edges("router", route, { "code_expert": "code_expert", "design_expert": "design_expert", "general_expert": "general_expert", })这本质上是把多个远程图当成了一个“图集群”，本地图负责流量分发。好处是每个远程图可以独立扩展、独立更新，你甚至可以对同一类问题做 A/B 测试——线上同时挂两个版本的远程图，让路由随机分发流量，看哪边效果好。
4. 参数配置与安全边界：RemoteGraph 的关键细节
4.1 构造参数逐项拆解
RemoteGraph看起来构造简单，实际参数里藏着不少坑。我按常用程度一个个说。
| 参数 | 作用 | 容易踩的坑 |
|---|---|---|
graph_id | 服务端注册的图 ID | 写错直接 404，且报错信息可能不够直观 |
url | 服务端基础地址 | 不要带尾斜杠，不要写成网页地址，必须是可以访问 API 的服务端地址 |
api_key | 认证密钥 | 别硬编码，用环境变量注入 |
headers | 自定义请求头 | 可以用来传租户标识、链路追踪 ID，注意别覆盖掉框架自带的头 |
timeout | 单次请求超时时间 | 远程图跑大模型很容易超过默认超时，一定要设大一点 |
尤其是timeout。我第一次接远程图时，用的默认配置，远程端要跑三步大模型推理，动辄几十秒，本地一直报超时，我还以为是网络问题。后来把 timeout 从默认值调到 120 秒，问题立刻消失。如果你构建的远程图里有流式生成或者多节点串联，建议直接给 120 秒以上，甚至可以让客户端配合重试策略一起设计。
4.2 认证与多租户隔离
远程图一旦放到网络上，就不能裸奔。服务端支持 API Key 之类的认证机制，客户端配置时用环境变量管理：
import os remote_graph = RemoteGraph( "research_agent", url=os.getenv("REMOTE_GRAPH_URL"), api_key=os.getenv("REMOTE_GRAPH_API_KEY"), )多团队共用远程图时，我见过一种比较实用的做法：通过自定义 header 传租户 ID，服务端根据租户 ID 做数据隔离。
remote_graph = RemoteGraph( "research_agent", url="http://remote-graph.internal:2024", api_key=os.getenv("REMOTE_GRAPH_API_KEY"), headers={"X-Tenant-ID": "team-a"}, )这时候服务端需要自己解析这个 header，在检索、生成逻辑里按租户过滤数据，保证 A 团队调用时永远看不到 B 团队的数据。这层隔离是应用层做的，RemoteGraph 本身不替你判断。
安全边界上有两个原则：第一，密钥永远不进代码仓库，也不要打进镜像；第二，远程图服务不要暴露在公网，尽量走内网、专线或服务网格，加一层网络层控制比任何代码都稳妥。
4.3 超时、重试与降级策略
远程调用最大的敌人是网络抖动和服务过载。很多图应用线上出问题，不是逻辑写错了，而是远程图偶发超时后没有兜底。我建议所有 RemoteGraph 调用都包一层可靠的封装：
import time def call_remote_with_retry(remote, payload, max_retries=3, timeout=120): for attempt in range(max_retries): try: return remote.invoke(payload, timeout=timeout) except Exception as e: if attempt == max_retries - 1: raise time.sleep(2 ** attempt) # 指数退避 return None更稳的方案是加降级逻辑。远程图挂掉时，本地回退到一个粗糙但能用的逻辑，保证整条链路不断。比如检索服务挂了，就返回缓存结果或者一个固定兜底答案，而不是让用户看到报错。降级逻辑不是偷懒，是线上服务稳定性的基本功。
还要注意一个细节：重试不是每次都安全。如果远程图是有副作用的（比如写库、调用第三方 API），重复发起调用可能产生重复副作用。这种场景优先保证幂等，让远程图支持通过请求 ID 去重，或者重试时复用同一个thread_id配合远端状态来判断是否已经执行过。
5. 常见问题与排查实录
5.1 URL 或 graph_id 不匹配导致连接失败
这是最典型的问题。现象是客户端调用时报连接错误或者 404，本地怎么排查网络都不通。
排查顺序：
- 先在浏览器或 curl 里直接访问
url根路径，确认服务端确实活着。 - 再访问
url下的健康检查或文档端点，确认服务端版本和 API 路径。 - 最后核对
graph_id是否和服务端部署时的图 ID 完全一致，注意大小写和下划线。
我曾经有一次把research_agent写成了research-agent，中间下划线变横线，找了一下午没找到问题。后来在服务端日志里看到请求路径，才发现是 ID 对不上。建议客户端和服务端约定好 ID 命名规范，尽量统一用小写加下划线，并在部署脚本里自动校验。
5.2 状态 Schema 序列化不兼容
远程图能连上，但一传数据就报序列化错误，或者远端报“缺少字段”。十有八九是状态 Schema 两边没对齐。
我遇到过一个真实的例子：本地图状态里有一个字段叫metadata，里面存的是自定义对象，直接传给了远程图。远程图一收到就炸了，因为 JSON 序列化不认这个对象。后来把metadata显式转成 dict，服务端才正常接收。
几点经验：
- 远程图接收的所有字段，必须是 JSON 可序列化的基础类型。
- 服务端和客户端都显式定义好 Schema，并在接口文档中写清楚每个字段的类型和可选性。
- 不要在本地图里把“全量状态”一股脑丢给远程图，只传对方要的，避免无法预期的字段干扰。
5.3 stream_mode 返回格式与预期不一致
用stream接远程图时，很多人会发现返回的事件结构和本地图不太一样。这是因为stream_mode可以配values、updates、messages等多种模式，不同模式返回的事件格式完全不同。
我自己的经验是：如果只是关心最终结果，用stream_mode="values"，每个事件是一个状态快照，取最后一个非空结果就行。如果关心生成过程，用stream_mode="messages"，事件里会带 LLM token 级别的更新，适合做打字机效果。如果你需要两者兼得，传列表：
remote_graph.stream( payload, stream_mode=["values", "messages"], )解析时注意事件是一个 dict，通常包含event字段来区分是values还是messages类型。不同版本字段名可能略有变化，最稳的办法是先打一条日志，把事件结构原样打出来看一眼再写解析逻辑。
5.4 thread_id 管理不当导致状态错乱
远程图是有记忆的，记忆靠thread_id区分。如果你每次调用都传同一个thread_id，远程图会认为这是同一个会话的延续，自动带上之前的历史上下文。这在多用户场景下是大事故：A 用户的问题可能拿到 B 用户的上下文。
我的建议是：
- 每个独立会话都生成一个新的
thread_id，推荐用 UUID。 - 需要跨请求保持上下文时才复用同一个
thread_id，并且要把它们和业务用户 ID、会话 ID 的映射关系存到库里。 - 调试时特别注意，别图省事全局写死一个
thread_id，不然你测着测着就会发现结果越跑越不对劲，因为历史状态一直在沉淀。
另外，远程图的interrupt也是靠thread_id恢复的。如果业务里有人工审核节点，前端页面需要记住对应的thread_id，下次调用时用它继续恢复执行。这个thread_id最好由后端统一管理，不要暴露给前端随意传。
最后分享一个我自己的架构习惯。以前我总想把所有能力都放进一张图里，图大、节点多、状态字段爆炸，改哪里都心惊胆战。用了 RemoteGraph 之后，我会先问自己一个问题：这个模块是不是独立的、稳定的、边界清晰的？如果是，就把它做成单独的远程图，再用本地图做编排。
这种做法的好处是，每张图都只解决一个明确的问题，状态 Schema 简洁，测试路径清晰，部署互不影响。到后期，本地图更像一个“总装车间”，把各种远程图按业务逻辑装配起来。团队拿到这样的架构，协作效率提升非常明显：每个团队守着自己的远程图，出问题在各自的服务日志里查，不用再互相推锅。
如果你刚开始接触 RemoteGraph，建议先拿一个最不重要的模块做试点，把服务端部署、客户端接入、超时重试这一套跑通，再慢慢迁移核心能力。等这条路走顺了，你会发现自己再也不想回到“一张图塞天下”的时代了。
