LangChain 怎样把工具调用结果映射到消息历史

在 LangChain 里，工具调用结果要回到消息历史，关键不是把字符串直接 append 到列表，而是保留一条完整的“模型请求—工具结果”配对关系：模型产生带有 tool_calls 的 AIMessage，工具执行后返回带有同一个 tool_call_id 的 ToolMessage。如果工具还要修改 Agent 状态，就让工具返回 Command，在同一次状态更新里放入 ToolMessage 和自定义字段。

官方文档：https://docs.langchain.com/oss/python/langchain/messages

这篇只围绕消息映射和状态写回展开，示例使用 LangChain 当前推荐的消息对象写法，不绑定某一家模型服务商。

工具调用为什么会在历史里“缺一条”

一次完整的工具交互至少包含三类消息：用户的 HumanMessage、模型提出调用请求的 AIMessage，以及工具返回结果的 ToolMessage。AIMessage.tool_calls 记录工具名、参数和调用 ID；ToolMessage 的 tool_call_id 必须与它回应的调用 ID 相同。

最常见的错误是只保存工具函数的返回字符串，或者新建 ToolMessage 时使用了另一个 ID。模型下一轮看到的历史就不完整，轻则无法继续回答，重则出现“工具已经执行但模型不知道”的错觉。

先用最小配方把结果配回消息

下面的片段手动演示映射关系。真实 Agent 中，工具节点通常会代为创建结果消息，但这个最小版本适合排查历史为何断开。

from langchain.messages import AIMessage, HumanMessage, ToolMessage

# 这个模型消息代表一次工具调用请求；id 是后续配对的唯一线索。
ai_message = AIMessage(
    content=[],
    tool_calls=[{
        "name": "get_weather",
        "args": {"city": "Shanghai"},
        "id": "call_weather_01",
    }],
)

# 工具执行后，把结果放入 ToolMessage，并复用原始调用 ID。
tool_message = ToolMessage(
    content="Shanghai: cloudy, 22C",
    tool_call_id="call_weather_01",
)

# 下一轮模型需要同时看到用户问题、调用请求和工具结果。
history = [
    HumanMessage("上海今天适合带伞吗？"),
    ai_message,
    tool_message,
]

这里的三个对象不是三个孤立日志：tool_call_id 把结果指回 AIMessage.tool_calls 中的那一项，模型再次被调用时才有足够上下文继续生成自然语言回答。

不要只改工具返回值，要保留消息对象

工具可以返回字符串或结构化对象，LangChain 会把普通返回值包装成 ToolMessage。但如果你在自定义图节点里手动更新状态，就要明确把消息对象放进 messages 字段；只更新一个业务字段不会自动产生可供模型读取的工具结果。

工具调用参数也不要从历史文本里猜。优先读取 AIMessage.tool_calls 中的 name、args 和 id，执行后用同一条记录的 id 构造结果。多工具并行时，每个结果都要独立匹配，不能因为完成顺序不同就复用第一个 ID。

工具需要修改状态时返回 Command

如果工具除了返回天气、检索结果等内容，还要把用户偏好、计数器或业务状态写回 AgentState，可以返回 Command。官方工具文档要求在这类更新中放入与当前调用匹配的 ToolMessage，否则消息历史和自定义状态会出现分叉。

from langchain.agents import AgentState
from langchain.messages import ToolMessage
from langchain.tools import ToolRuntime, tool
from langgraph.types import Command

class CustomerState(AgentState):
    # 自定义字段会与消息列表一起进入图状态。
    customer_name: str

@tool
def set_customer_name(new_name: str, runtime: ToolRuntime) -> Command:
    """保存称呼，并把工具结果写入消息历史。"""
    return Command(
        update={
            "customer_name": new_name,
            "messages": [
                ToolMessage(
                    content=f"称呼已保存为：{new_name}",
                    # 必须回填本次工具调用的 ID，避免结果错配。
                    tool_call_id=runtime.tool_call_id,
                )
            ],
        }
    )

runtime.tool_call_id 是当前工具调用的关联键，业务字段则是图状态的一部分。这样后续模型既能在历史里读到“称呼已保存”，又能从状态字段读取结构化值。

并行调用和异常结果怎么处理

多工具场景里，最稳妥的做法是把调用 ID 当成主键：每次执行都保留原始 ID，成功时写入对应结果，失败时也写入对应的错误信息。不要用“第几个工具”作为关联依据，因为并行执行的完成顺序可能变化。

如果一个工具真的无法返回结果，可以构造内容明确的 ToolMessage，例如“查询超时，请稍后重试”，并保留相同的 tool_call_id。这样模型知道调用已经结束，也能决定重试、换工具或向用户解释限制。

完整排查思路

遇到“工具执行成功但下一轮回答不对”时，先打印或记录一条调用的 name、args、id，再确认对应的 ToolMessage.tool_call_id 是否一致，最后确认该消息实际被追加到了当前图状态的 messages。若工具还要更新业务字段，则检查 Command.update 是否同时包含消息和自定义状态。

一句话记忆：AIMessage 负责提出调用，工具负责产生结果，ToolMessage 负责把结果带回模型，tool_call_id 负责让两者配对；需要改状态时，用 Command 把消息和状态放在同一次更新里。

相关问题

ToolMessage 的 tool_call_id 可以自己生成吗？

不建议。它应当对应 AIMessage.tool_calls 中已有的调用 ID；自己生成会破坏模型请求与工具结果的关联。

工具返回字典后还需要手动创建 ToolMessage 吗？

普通工具返回值通常会被框架包装成工具消息；只有你手动更新图状态、需要同时写入自定义字段或实现特殊错误处理时，才需要显式构造并放入 ToolMessage。