langchain-langgraph-agents

用途

本技能面向使用 Python 编写 LangGraph 1.0 ReAct 智能体的团队，帮助避免两类典型故障：

模糊提示导致循环触顶（P10）：create_react_agent 默认 recursion_limit=25。像“帮我处理我的账户”这类提示无法收敛，模型反复调用工具直到抛出 GraphRecursionError: Recursion limit of 25 reached without hitting a stop condition。在 Sonnet 上、3 个工具的智能体，一次失控循环可能花费 5-15 美元（假设工具本身不昂贵）。
旧版 AgentExecutor 静默吞掉工具错误（P09）：旧执行器默认 handle_parsing_errors=True 并捕获工具异常，把错误字符串作为下一次观察返回。当错误序列化为空（如 ValueError("") 或无响应体的 HTTP 500）时，循环继续且无信号，智能体说“找不到答案”，实际是三次工具调用前的静默崩溃。

主要能力

用 @tool + Pydantic 定义带类型 schema 的工具，docstring 作为工具描述，建议不超过 1024 字符（P11）。
用 create_react_agent(model, tools, checkpointer=MemorySaver()) 构建智能体，这是 LangGraph 1.0 中已移除的 initialize_agent 工厂的替代（P41）。
以 {"messages": [...]} 和线程级 config（thread_id）调用，输出为完整更新后的状态。
按预期智能体深度设置 recursion_limit：交互式 1-3 个工具建议 5-10；任务完成型 10-15；规划/研究型 20-30；多智能体 supervisor 40+。
通过中间件（如 TokenBudget 回调）添加每会话 token 预算，交互式智能体 50K token 约 0.25 美元，后台规划型可提高到 200K-500K。
默认抛出并传播工具错误，不再静默吞掉；需要容错时由工具自身显式降级（返回字符串而非静默吞掉）。
提供 create_react_agent、自定义 StateGraph、supervisor 与旧版方案的选型决策表。

使用方式

定义工具：使用 @tool("lookup_account", args_schema=LookupAccountArgs)，在函数内对无效输入抛出真实异常。异步工具用 @tool 装饰 async def，LangGraph 会通过 await 调用。
构建智能体：create_react_agent(model=model, tools=[...], checkpointer=MemorySaver())。checkpointer 按线程持久化状态，多轮对话和中断恢复必需。
调用：传入 {"messages": [{"role": "user", "content": "..."}]}，config 中设置 {"configurable": {"thread_id": "user-42"}, "recursion_limit": 10}。
设置 recursion_limit：在调用时而非构建时设置。触发时抛出 GraphRecursionError，应捕获并给出用户提示，不要在无成本保护下重试。
添加 token 预算：实现 BaseCallbackHandler 子类，在 on_llm_end 中累计 token_usage 并在超限时抛出 RuntimeError，通过 config 的 callbacks 传入。
错误传播：工具抛出的异常会从 agent.invoke() 传播出来；需要容错时在工具内部捕获并返回模型可推理的字符串。

适用场景

单智能体工具调用循环：使用 create_react_agent。
多阶段流水线（计划→执行→审查）：使用自定义 StateGraph。
多智能体 supervisor：create_supervisor + 用 create_react_agent 构建的 worker。
2026 年后的新代码：不要使用 AgentExecutor 或 initialize_agent（1.0 中已移除/弃用，P41；intermediate_steps 形状变化，P42）。
单次强制工具调用（如“始终分类到某个桶”）：跳过智能体，使用 model.bind_tools([Schema], tool_choice={"type": "tool", "name": "Schema"})，但绝不要循环强制 tool_choice（P63）。

限制与前置条件

需要 Python 3.10+。
需要 langgraph >= 1.0, < 2.0 与 langchain-core >= 1.0, < 2.0。
至少一个提供商包：pip install langchain-anthropic 或 langchain-openai。
需要已完成 langchain-langgraph-basics（L25），即已了解 StateGraph、MessagesState 和 checkpointers。
需要提供商 API key：ANTHROPIC_API_KEY 或 OPENAI_API_KEY。
工具 docstring 过长会被截断（Anthropic 约 1024 字符，OpenAI 约 2KB），示例应移到系统提示中。
强制 tool_choice 会阻止 stop_reason="end_turn"，导致智能体无法终止。

常见错误与修复

GraphRecursionError：降低 recursion_limit 至交互式 5-10，并添加重复工具调用提前停止节点。
ImportError: cannot import name 'initialize_agent'：改用 from langgraph.prebuilt import create_react_agent。
AttributeError: 'ToolCall' object has no attribute 'tool'：使用 step.tool_name（或字典形式的 step["name"]），并检查 isinstance(step, ToolCall)。
智能体说“找不到答案”但工具实际抛错：迁移到 create_react_agent，错误默认抛出。
设置 tool_choice 后智能体循环：智能体循环使用 tool_choice="auto"，强制选择仅用于单次调用。
智能体幻觉出不存在的工具名：使用 create_react_agent，依赖提供商原生工具调用，白名单在传输层强制。
RuntimeError: Token budget exceeded：TokenBudget 回调按预期触发，提高上限或缩小智能体范围。
工具描述被截断导致参数错误：缩短 docstring，将示例移入系统提示。

迁移示例

旧版（LangChain 0.2）使用 initialize_agent、handle_parsing_errors=True、return_intermediate_steps=True，并通过 action.tool 访问中间步骤。新版（LangGraph 1.0）使用 create_react_agent 与 MemorySaver，调用时传入 messages 和 config，中间步骤变为 messages 列表中的 ToolMessage，通过 m.name 访问。