AI Agent / 系统课时
把子智能体封装成工具
把子智能体封装成工具
把子智能体直接嵌进父图会共享更多状态;把它封装成工具,则可以只传入完成任务所需的最小参数,并把返回值压缩成稳定结果。这样上层智能体看到的是一个清晰工具契约,而不是子智能体内部的消息、临时变量和中间状态,能显著降低状态污染。
学习目标
- 将独立 LangGraph 子智能体包装成可调用工具
- 控制工具输入,只暴露子智能体真正需要的上下文
- 规范化工具输出,避免把内部状态原样泄漏给上层智能体
工具边界就是上下文边界
子智能体封装成工具时,最重要的不是装饰器,而是输入与输出契约。上层智能体通常只需要传入一个任务描述、少量业务标识或约束;会话历史、内部节点状态、调试字段不应默认全部透传。
返回值也应做同样处理。子智能体可以维护丰富状态,但工具最好只返回上层下一步真正要消费的结果,例如摘要、决策或结构化字段,而不是直接返回整个 state。

将已编译子图包装为工具
下面示例先构建一个独立子图,再用 @tool 把它包装成上层可调用能力。工具函数只接收 query,调用子图后只返回 answer,因此 internal_notes 不会暴露给调用方。
from typing import TypedDict
from langchain_core.tools import tool
from langgraph.graph import END, START, StateGraph
class SpecialistState(TypedDict, total=False):
query: str
internal_notes: str
answer: str
def prepare(state: SpecialistState) -> SpecialistState:
# 内部笔记属于子智能体状态,不进入工具返回值。
return {"internal_notes": f"classified:{state['query']}"}
def solve(state: SpecialistState) -> SpecialistState:
return {"answer": f"specialist result for: {state['query']}"}
builder = StateGraph(SpecialistState)
builder.add_node("prepare", prepare)
builder.add_node("solve", solve)
builder.add_edge(START, "prepare")
builder.add_edge("prepare", "solve")
builder.add_edge("solve", END)
specialist_graph = builder.compile()
@tool
def specialist_agent(query: str) -> str:
\"\"\"Delegate a focused task to the specialist agent.\"\"\"
result = specialist_graph.invoke({"query": query})
return result["answer"]
print(specialist_agent.invoke({"query": "check refund policy"}))预期输出
specialist result for: check refund policy这个工具已经可以加入上层智能体的工具集合。上层只知道工具名称、描述、参数 query 和返回文本,不需要知道子图有几个节点,也不会自动获得 internal_notes。
不要把父状态整包传入
最常见的状态污染来自“方便起见直接传整个父状态”。这样会让子智能体意外依赖父图字段,也会把不必要的历史消息、权限信息或中间结果带入子图,导致上下文变长且耦合增强。
更安全的做法是先显式投影输入,再显式投影输出。输入阶段从父状态提取允许字段;输出阶段只把工具契约承诺的结果写回父状态。若需要多个字段,可以定义 Pydantic 模型或 TypedDict 作为工具参数与返回结构,而不是退回无约束字典。
工具封装与子图嵌套的取舍
把子智能体作为工具调用,适合上层智能体需要按需委派、希望保持最小上下文、并且只关心最终能力结果的场景。它的边界清晰,测试时也可以直接对工具输入输出做断言。
如果父图必须观察子图的中间状态、对内部步骤进行检查点恢复,或父子流程之间需要共享多字段状态,那么直接把子图作为图节点通常更合适。工具封装强调的是能力边界,而不是状态透明度。
无论采用哪种方式,都应让上层只依赖稳定契约。对子智能体而言,内部节点、提示词、临时状态都可以演进;只要工具参数和返回语义不变,上层工作流就不需要跟着重构。