LangGraph项目中ToolMessage返回格式错误的解决方案

在LangGraph项目中使用create_react_agent()和create_manager()构建多代理系统时，开发者可能会遇到"KeyError('tool_call_id')"错误。这个问题通常发生在工具函数返回结果时没有正确包含tool_call_id字段的情况下。

问题背景

当使用LangGraph构建基于代理的工作流时，系统需要跟踪每个工具调用的状态。工具函数通过返回Command对象来更新系统状态，其中包含两个关键部分：

1. 状态更新字段
2. 消息列表（通常包含ToolMessage）

错误原因分析

核心问题在于ToolMessage的构造方式。根据LangGraph的设计规范，每个工具调用都需要关联一个唯一的tool_call_id，这个ID应该由LLM在发起工具调用时生成。但在实际实现中，开发者可能会忽略在ToolMessage中包含这个关键字段。

解决方案

正确的实现方式是在返回的Command对象中，确保每个ToolMessage都包含对应的tool_call_id。以下是修正后的代码示例：

@tool
def get_fund_holdings(all_ids: List[str]) -> Command:
    # 工具处理逻辑...
    fund_holding_path = 'path/to/file.xlsx'
    
    return Command(
        update={
            "fund_holding_filename": fund_holding_path,
            "messages": [
                ToolMessage(
                    content=f"文件已保存至{fund_holding_path}",
                    tool_call_id=tool_call_id  # 必须包含这个字段
                )
            ]
        }
    )

实现要点

1. 获取tool_call_id：可以从传入的Message对象中提取，或者通过上下文获取当前工具调用的ID
2. 消息一致性：确保每个工具响应消息都与对应的调用请求匹配
3. 状态管理：Command对象中的update字段应该包含所有需要更新的状态变量

最佳实践建议

1. 在开发工具函数时，始终验证是否包含必要的元数据字段
2. 使用类型提示确保代码符合LangGraph的接口规范
3. 在复杂工作流中，考虑添加日志记录以跟踪工具调用链
4. 对于需要返回多个消息的情况，确保每个ToolMessage都有正确的tool_call_id

总结

正确处理ToolMessage中的tool_call_id是LangGraph工作流正常运行的关键。通过遵循上述解决方案和最佳实践，开发者可以避免常见的状态管理错误，构建更健壮的多代理系统。这个问题也提醒我们，在使用高级框架时，理解底层数据流和接口规范的重要性。