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 会处理这组请求,而不是要求你手写逐个分派逻辑。

ToolNode 批量执行与消息回写

在图状态里执行两次工具调用

下面不接真实模型,而是手工构造一条 AIMessage,这样可以把测试重点放在 ToolNode 本身,并得到确定性输出。图只有一个工具节点:初始状态进入 ToolNode,执行完成后结束;MessagesState 会把节点返回的新消息追加到原消息历史。

python
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)

预期输出

text
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 负责执行并形成观察结果,消息状态负责保留完整上下文。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 ToolNode 执行工具请求

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通