揭秘deep-agents-from-scratch工具层设计:InjectedState与Command如何实现工具与状态安全交互

原创2026-10-25 18:37:371,637 阅读

揭秘deep-agents-from-scratch工具层设计:InjectedState与Command如何实现工具与状态安全交互

deep-agents-from-scratch 是 LangChain 团队开源的"从零构建 Deep Agent"教程仓库,基于 LangGraph 用 TODO 任务规划、虚拟文件系统与子 Agent 委派三大模式搭建可落地的 AI Agent。本文将聚焦它的工具层设计,讲清楚两个核心机制:InjectedState 如何把 Agent 状态安全地注入工具、Command 如何让工具把执行结果写回状态——这正是"工具与状态安全交互"的完整链路。

🧭 先看懂:Agent 的工具调用循环

在深入工具层之前,先回顾标准 ReAct 循环:LLM 发出 Tool Call,工具节点执行工具,工具结果以 ToolMessage 的形式回到 LLM,如此循环直到 LLM 不再调用工具。

deep-agents-from-scratch中Agent与工具循环交互示意图:LLM发起Tool Call,工具返回Observation

这套循环在 0_create_agent.ipynb 中有完整演示。问题来了:工具只返回字符串,那它怎么读取甚至修改 Agent 的全局状态(如文件、TODO 列表)? 这正是 deep-agents-from-scratch 工具层要解决的核心问题。

❓ 痛点:工具想读状态,但 LLM"看不见"state

最直觉的做法是把 state 直接作为工具函数的参数:

@tool
def calculator(operation, a, b, state):
    ...

但这行不通:工具的参数列表会被绑定到 LLM,由 LLM 负责生成 arguments。而 LLM 的上下文里并没有完整的 state 数据,它既填不出来,也只能靠"猜"——这就是典型的幻觉隐患。

state作为工具参数的反模式示意图:LLM无法凭空生成state参数

🔑 InjectedState:参数对 LLM 隐藏,执行时才注入

deep-agents-from-scratch 的解法是 InjectedState 注解。只要把参数声明为:

state: Annotated[DeepAgentState, InjectedState]

LangGraph 在做两件事:

  1. 生成工具 schema 时剔除该参数——LLM 根本看不到 state,自然不会去"编造"它;
  2. ToolNode 执行工具时注入真实 state——工具拿到的是当前线程里权威的状态数据。

同理,InjectedToolCallId 会把当前工具调用的 tool_call_id 注入进来,方便工具构造与调用对应的 ToolMessage。

InjectedState状态注入流程图:LLM生成工具调用后,ToolNode在执行时注入真实state

项目里的只读工具就是典型用法,例如 read_todos 直接 state.get("todos", <a href="https://link.gitcode.com/i/3e8865f22b4544bbebd7bd460c3fe1d8" target="_blank">]) 读取任务列表;[file_tools.py 中的 ls()、read_file() 也是通过注入的 state 访问虚拟文件系统。整个过程对 LLM 完全透明,且数据零幻觉。

deep-agents-from-scratch中User、LLM与Tools三者交互的时序图

✍️ Command:工具不止能读,还能安全写回状态

只读工具直接 return 即可;但 write_todos、write_file 这类工具需要同时更新状态里的多个字段。此时返回值不再是普通字符串,而是一个 Command:

return Command(
    update={
        "todos": todos,
        "messages": [
            ToolMessage(f"Updated todo list to {todos}", tool_call_id=tool_call_id)
        ],
    }
)

这段代码出自 write_todos,它一次完成两件事:

  • 更新 todos 字段:把最新任务列表写回状态;
  • 追加 messages:返回一条带 tool_call_id 的 ToolMessage,保证 LLM 侧的"调用—响应"消息对严格配对。

messages 字段由框架自动追加,todos、files 等字段按 state.py 中定义的 reducer 规则合并——例如 files 使用 file_reducer 做字典合并,新文件覆盖同名旧文件、其余文件保留。写回路径因此是结构化、可预测的:LLM 无法直接操纵状态结构,只能经由这些预定义通道修改。

🚀 进阶:task 工具用 Command 回收子 Agent 成果

最精彩的应用在 task_tool.py。父 Agent 通过 task() 工具委派任务给专职子 Agent:

  • 上下文隔离:子 Agent 只携带任务描述,看不到父 Agent 的完整对话历史,避免上下文污染;
  • 成果回收:子 Agent 跑完后,task() 返回一个 Command,把子 Agent 产生的 files 变更与最终结论(包装成 ToolMessage)一次性合并回父 Agent 状态。

Deep Agent上下文卸载(Offload Context)工具层架构:Plan、Write/Retrieve文件、Sub-Agent委派

这正是 README 中"Context offloading to file systems"与"Context isolation through sub-agent delegation"两大上下文工程模式落地的关键:虚拟文件把长上下文搬出对话窗口,而 InjectedState + Command 保证所有读写都安全、原子地发生在状态之上。

📂 关键源码导读

想动手深入,建议按以下路径阅读(仓库为只读,可直接 clone 本地研究):

总结

deep-agents-from-scratch 的工具层设计可以概括为一句话:读状态用 InjectedState,写状态用 Command。前者把 LLM"隔离"在权威数据之外,杜绝幻觉注入;后者把状态修改收敛到框架管理的结构化通道,让工具与状态交互既灵活又安全。掌握这套模式,你就能为任何 LangGraph Agent 设计出可靠的数据读写工具。

登录后查看全文
deep-agents-from-scratch