一、ToolNode 是什么ToolNode是LangGraph 官方预封装的工具执行节点专门用来执行 LLM 输出的tool_calls自动完成工具分发调用、结果封装成ToolMessage更新到 state 的 messages。定位Agent 闭环里标准化的「工具执行器」替代手写循环调用工具、拼装消息的样板代码包路径from langgraph.prebuilt import ToolNode二、底层内部完整执行流程输入State 中最后一条消息是携带tool_calls的AIMessage读取 state [messages] 最后一条 AIMessage遍历里面所有tool_call支持并行批量调用多个工具根据tool_call[name]在传入的 tools 列表匹配对应 BaseTool解析tool_call[args]执行工具同步 / 异步自动适配捕获工具异常异常内容也包装到 ToolMessage将每一个执行结果封装成独立ToolMessage带上tool_call_id返回{messages: [ToolMessage, ...]}更新 graph state执行完成之后消息流回到 LLM 节点由大模型整理结果或者继续调用工具关键约束ToolNode只负责执行工具不会调用大模型不会做业务判断它不会自己判断要不要执行工具要不要进入 ToolNode由条件边tools_condition判断三、最简基础代码示例from langgraph.prebuilt import ToolNode, tools_condition from langgraph.graph import StateGraph, START, MessagesState from langchain_openai import ChatOpenAI from langchain_core.tools import tool # 1. 定义工具 tool def add(a: int, b: int) - int: 两个数字相加 return a b tools [add] llm ChatOpenAI(modelgpt-4o).bind_tools(tools) # LLM节点 def call_llm(state: MessagesState): return {messages: [llm.invoke(state[messages])]} builder StateGraph(MessagesState) builder.add_node(llm, call_llm) # 注册ToolNode绑定工具列表 builder.add_node(tools, ToolNode(tools)) builder.add_edge(START, llm) # 条件路由有tool_calls就跳tools否则结束 builder.add_conditional_edges(llm, tools_condition) builder.add_edge(tools, llm) graph builder.compile()四、ToolNode 可配置参数ToolNode( tools: Sequence[BaseTool | Callable], name: str tools, # 工具执行异常时是否捕获自动封装到ToolMessage handle_tool_errors: bool | ToolExceptionHandler True )handle_tool_errorsTrue默认工具抛异常不会直接崩溃整个图异常文本放进 ToolMessage 返回给 LLM模型可以重试或者报错告知用户如果关闭异常捕获工具报错会直接中断整个 workflow五、ToolNode vs 手写 FunctionNode 实现工具调用方式 A官方 ToolNode开箱即用优点原生支持批量并行调用多个 tool_call自动处理消息格式ToolMessage tool_call_id 关联自带异常捕获机制兼容所有 LangChain 工具tool / MCP‑Adapter 工具 / LangChain 内置工具 缺点自定义拦截逻辑弱权限校验、日志、参数清洗要在外面再加 FunctionNode方式 B自己用 FunctionNode 手写工具调度适合场景需要完全接管工具执行全流程自定义鉴权、审批弹窗、人工确认自定义限流、审计日志过滤 / 修改工具入参拒绝执行高危工具手写伪代码对比def custom_tool_executor(state): last_msg state[messages][-1] tool_messages [] for tc in last_msg.tool_calls: # 手动匹配工具、调用、封装ToolMessage ... return {messages: tool_messages}工程最佳实践llm → FunctionNode(权限/校验/日志) → ToolNode(真实执行工具)六、ToolNode 和 MCP 的关系ToolNode不关心工具来源是什么本地tool函数 → BaseTool → 传给 ToolNodeMCP Server 的能力通过langchain‑mcp‑adapters转为 BaseTool → 同样直接丢给 ToolNodeMCP 只是工具提供方ToolNode 依然是 Agent 图中统一的执行节点上层工作流代码完全不用修改七、tools_condition 配套路由规则和 ToolNode 成对出现tools_condition是 LangGraph 提供的判断函数如果 AIMessage 存在tool_calls→ 返回tools跳转到 ToolNode没有 tool_calls → 返回__end__结束流程八、异步场景AsyncToolNode如果你的工具全部是异步实现ToolNode 自动适配ainvoke 你在 graph 使用ainvoke / astream即可实现全异步非阻塞。九、高频面试背诵版ToolNode是 LangGraph 预置的工具执行节点输入携带tool_calls的 AIMessage自动调度执行工具输出标准化ToolMessage。内置能力批量并行调用多工具、自动消息封装、默认捕获工具异常。它只负责执行决策交给 LLM 节点分支跳转交给条件边 tools_condition。ToolNode 对接任意实现 BaseTool 协议的工具本地函数、MCP 适配器工具、第三方 API 工具。当需要自定义权限、审批、前置拦截时可以在 ToolNode 前面增加自定义 FunctionNode不需要重写 ToolNode 本身。完整 Agent 闭环链路START → LLM节点 →判断是否调用工具→ ToolNode → LLM节点十、常见坑点忘记给 LLM 调用.bind_tools(tools)→ LLM 不会输出 tool_calls永远不会走到 ToolNodetool_call 的 name 和工具名称不一致 → ToolNode 找不到工具抛出异常异步调用 graph但工具是同步阻塞函数 → 性能下降工具执行报错没有开启异常捕获时整个工作流直接崩溃