LangGraph返回含ToolMessage的Command报错及状态更新问题

1. 正确返回包含ToolMessage的Command(update=...) #

不要直接在update中传递包含ToolMessage的列表字面量，而是用函数式更新或LangGraph内置的add操作符追加消息，同时确保传递ToolMessage实例而非字典：

from langgraph.types import Command, add
from langchain_core.messages import ToolMessage

def your_node(state: AgentState) -> Command:
    # 构造ToolMessage实例
    tool_msg = ToolMessage(
        content="工具执行结果内容",
        tool_call_id="对应工具调用的ID"  # 必须和之前ToolCall的ID匹配
    )
    
    # 方式一：lambda函数实现函数式更新
    return Command(update={"messages": lambda msgs: msgs + [tool_msg]})
    
    # 方式二：用LangGraph的add操作符（更简洁）
    # return Command(update=add(messages=[tool_msg]))

错误根源是直接传递可变列表或ToolMessage的字典形式，导致框架尝试哈希不可哈希对象，函数式更新或add操作符可规避该问题。

2. 让ToolMessage在state["messages"]中持久化 #

绝对不要直接修改state["messages"]，LangGraph的状态是不可变快照，直接修改不会被框架跟踪，后续流程会沿用原始状态，导致消息丢失。必须通过返回Command触发框架状态更新：

• 严格使用上述函数式更新或add操作符的方式返回Command
• 确保ToolMessage的tool_call_id与之前触发工具调用的ToolCall消息ID完全匹配（否则可能被框架过滤）

3. 确保Command更新可哈希的推荐方案 #

• 优先用LangGraph内置操作符：比如add（追加列表元素）、set（设置字段值），这些操作符生成的更新指令天然可哈希
• 可变字段用函数式更新：对于列表、字典这类可变类型的状态字段，一律用lambda或自定义函数生成新值，不要直接传递可变对象
• 静态值用不可变类型：如果需要传递静态值，用元组代替列表、frozendict代替普通字典，确保值本身可哈希
• 传递消息实例而非字典：所有消息对象（如ToolMessage、HumanMessage）都传递实例，不要转成字典，LangGraph内置消息类都实现了可哈希接口

内容的提问来源于stack exchange，提问作者CodingButStillAlive