AI Agent / 系统课时
用 ToolNode 执行工具请求
用 ToolNode 执行工具请求
这一节把上一阶段产生的 tool_calls 真正执行起来。你会用 ToolNode 接收包含多个工具请求的 AIMessage,批量调用对应工具,并观察它如何生成带正确 tool_call_id 的 ToolMessage,再借助 MessagesState 的消息合并规则写回状态。
学习目标
- 用
ToolNode根据tool_calls找到并执行对应工具。 - 验证每条
ToolMessage.tool_call_id与原始调用 ID 一一对应。 - 理解
MessagesState如何把工具结果追加到消息历史,供下一次模型调用读取。
ToolNode 接收和返回什么
在常见的 LangGraph 智能体状态中,ToolNode 读取 messages 的最后一条消息,并要求其中存在模型生成的工具调用。对于普通工具,它会把每个执行结果包装成 ToolMessage,再以 {"messages": [...]} 的形状返回。
这层封装解决了两个容易写错的问题:一是根据调用名称选择正确工具并传入参数,二是把执行结果与原始调用 ID 对齐。一个 AIMessage 可以同时包含多个 tool_calls,ToolNode 会处理这组请求,而不是要求你手写逐个分派逻辑。

在图状态里执行两次工具调用
下面不接真实模型,而是手工构造一条 AIMessage,这样可以把测试重点放在 ToolNode 本身,并得到确定性输出。图只有一个工具节点:初始状态进入 ToolNode,执行完成后结束;MessagesState 会把节点返回的新消息追加到原消息历史。
from langchain_core.messages import AIMessage
from langchain_core.tools import tool
from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode
@tool
def add(a: int, b: int) -> int:
"""Add two integers."""
return a + b
@tool
def multiply(a: int, b: int) -> int:
"""Multiply two integers."""
return a * b
builder = StateGraph(MessagesState)
builder.add_node("tools", ToolNode([add, multiply]))
builder.add_edge(START, "tools")
builder.add_edge("tools", END)
graph = builder.compile()
request = AIMessage(
content="",
tool_calls=[
{
"name": "add",
"args": {"a": 2, "b": 3},
"id": "call_add",
"type": "tool_call",
},
{
"name": "multiply",
"args": {"a": 4, "b": 5},
"id": "call_mul",
"type": "tool_call",
},
],
)
result = graph.invoke({"messages": [request]})
tool_messages = sorted(
(message for message in result["messages"] if message.type == "tool"),
key=lambda message: message.tool_call_id,
)
for message in tool_messages:
print(message.tool_call_id, message.content)预期输出
call_add 5
call_mul 20这里的 call_add 和 call_mul 是为了演示而固定的调用 ID。真实模型生成的 ID 通常是动态值,例如 <ID>;关键不是字符串长什么样,而是返回的 ToolMessage.tool_call_id 必须准确引用对应请求。
为什么结果必须写成 ToolMessage
工具返回的整数 5 或 20 本身没有“属于哪一次调用”的信息。如果模型一次提出两个甚至更多请求,只把结果拼成普通文本会丢失对应关系。ToolMessage 同时携带结果内容与 tool_call_id,因此下一次模型推理能够把每条观察结果还原到原始调用。
ToolNode 返回的不是完整状态副本,而是待合并的状态更新。使用 MessagesState 时,messages 字段已经配置了消息 reducer,所以 {"messages": [ToolMessage(...)]} 会追加到历史,而不是覆盖之前的 HumanMessage 或 AIMessage。这正是工具循环能够连续运行的基础。
接回智能体循环
完整循环通常是“模型节点 → 条件路由 → ToolNode → 模型节点”。模型节点先追加一条 AIMessage;若它含有 tool_calls,路由进入工具节点。ToolNode 执行后追加 ToolMessage,再回到模型节点,让模型基于真实工具结果继续回答或发起下一轮调用。
掌握这条消息链后,智能体循环中的职责就很明确:模型负责提出结构化请求,ToolNode 负责执行并形成观察结果,消息状态负责保留完整上下文。