LangGraph代理处理ToolException时update_state报KeyError: 'model'问题排查

错误原因 #

你遇到的KeyError: 'model'是因为手动调用update_state打断了create_agent生成的LangGraph代理的内置执行流程。create_agent构建的图包含预设的分支路由（比如agent_router节点），当你在外部捕获ToolException后直接更新状态，图会尝试继续执行路由逻辑，但此时的状态更新不符合内置流程的预期，导致路由无法找到名为model的目标节点。

此外，create_agent默认已经集成了工具错误处理逻辑，不需要手动捕获异常并更新状态——工具抛出的ToolException可以通过工具自身的错误处理机制自动转换为ToolMessage，无需外部干预。

正确解决方案 #

方案1：利用工具内置错误处理（推荐） #

在定义K8s工具时，通过handle_tool_errors参数配置错误处理函数，让工具自动返回包含错误信息的ToolMessage，无需手动捕获异常。

示例代码：

from langchain.tools import Tool, StructuredTool
from langchain.tools.base import ToolException

# 自定义工具错误处理函数
def k8s_tool_error_handler(error: ToolException) -> str:
    return f"K8s工具执行失败: {str(error)}"

# 定义普通Tool时配置错误处理
k8s_tool = Tool(
    name="kubernetes_operation",
    func=your_k8s_tool_function,  # 替换为你的K8s操作函数
    description="执行Kubernetes操作，比如删除Pod、查询资源等",
    handle_tool_errors=k8s_tool_error_handler
)

# 或者定义结构化工具StructuredTool时配置
k8s_tool = StructuredTool.from_function(
    func=your_k8s_structured_function,  # 替换为你的结构化K8s操作函数
    description="执行结构化Kubernetes操作",
    handle_tool_errors=k8s_tool_error_handler
)

# 传入create_agent构建代理
self.agent = create_agent(
    model,
    tools=[k8s_tool],
    state_schema=MessagesState,
    checkpointer=InMemorySaver()
)

这样配置后，当工具抛出ToolException时，会自动将错误信息封装为ToolMessage并添加到状态中，代理会自动处理后续的多轮对话逻辑，无需手动调用update_state。

方案2：自定义代理图的错误处理节点（进阶） #

如果需要更复杂的错误处理逻辑，可以不使用create_agent的默认图，而是手动构建LangGraph，添加专门的错误处理节点，在工具执行失败时流转到该节点处理错误。

示例简化流程：

from langgraph.graph import StateGraph, END
from langchain_core.messages import ToolMessage
from langchain.tools import ToolException

# 工具执行节点
def tool_node(state):
    last_message = state["messages"][-1]
    tool_call = last_message.tool_calls[0]
    try:
        # 执行工具逻辑，替换为你的实际工具调用代码
        result = your_k8s_tool_function(tool_call["args"])
        return {"messages": [ToolMessage(content=str(result), tool_call_id=tool_call["id"])]}
    except ToolException as e:
        # 返回错误信息，流转回agent节点
        return {
            "messages": [ToolMessage(content=f"工具错误: {str(e)}", tool_call_id=tool_call["id"])]
        }

# 代理思考节点
def agent_node(state):
    # 替换为你的模型调用逻辑
    response = model.invoke(state["messages"])
    return {"messages": [response]}

# 构建图
graph_builder = StateGraph(MessagesState)
graph_builder.add_node("agent", agent_node)
graph_builder.add_node("tools", tool_node)
graph_builder.add_edge("agent", "tools")
graph_builder.add_edge("tools", "agent")
graph_builder.set_entry_point("agent")

# 编译图
self.agent = graph_builder.compile(checkpointer=InMemorySaver())

原代码的问题点 #

1. 错误捕获时机错误：agent.invoke()抛出ToolException时，代理的执行流程已经中断，此时手动调用update_state会导致图的路由逻辑混乱，因为内置路由无法识别手动更新后的状态流转。
2. 重复处理错误：create_agent默认会处理工具错误，手动捕获并更新状态属于重复操作，且不符合LangGraph的状态管理规范。

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