AI Agent / 系统课时

把子智能体封装成工具

把子智能体封装成工具

把子智能体直接嵌进父图会共享更多状态;把它封装成工具,则可以只传入完成任务所需的最小参数,并把返回值压缩成稳定结果。这样上层智能体看到的是一个清晰工具契约,而不是子智能体内部的消息、临时变量和中间状态,能显著降低状态污染。

学习目标

  • 将独立 LangGraph 子智能体包装成可调用工具
  • 控制工具输入,只暴露子智能体真正需要的上下文
  • 规范化工具输出,避免把内部状态原样泄漏给上层智能体

工具边界就是上下文边界

子智能体封装成工具时,最重要的不是装饰器,而是输入与输出契约。上层智能体通常只需要传入一个任务描述、少量业务标识或约束;会话历史、内部节点状态、调试字段不应默认全部透传。

返回值也应做同样处理。子智能体可以维护丰富状态,但工具最好只返回上层下一步真正要消费的结果,例如摘要、决策或结构化字段,而不是直接返回整个 state。

上层智能体通过工具边界调用子智能体

将已编译子图包装为工具

下面示例先构建一个独立子图,再用 @tool 把它包装成上层可调用能力。工具函数只接收 query,调用子图后只返回 answer,因此 internal_notes 不会暴露给调用方。

python
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"}))

预期输出

text
specialist result for: check refund policy

这个工具已经可以加入上层智能体的工具集合。上层只知道工具名称、描述、参数 query 和返回文本,不需要知道子图有几个节点,也不会自动获得 internal_notes。

不要把父状态整包传入

最常见的状态污染来自“方便起见直接传整个父状态”。这样会让子智能体意外依赖父图字段,也会把不必要的历史消息、权限信息或中间结果带入子图,导致上下文变长且耦合增强。

更安全的做法是先显式投影输入,再显式投影输出。输入阶段从父状态提取允许字段;输出阶段只把工具契约承诺的结果写回父状态。若需要多个字段,可以定义 Pydantic 模型或 TypedDict 作为工具参数与返回结构,而不是退回无约束字典。

工具封装与子图嵌套的取舍

把子智能体作为工具调用,适合上层智能体需要按需委派、希望保持最小上下文、并且只关心最终能力结果的场景。它的边界清晰,测试时也可以直接对工具输入输出做断言。

如果父图必须观察子图的中间状态、对内部步骤进行检查点恢复,或父子流程之间需要共享多字段状态,那么直接把子图作为图节点通常更合适。工具封装强调的是能力边界,而不是状态透明度。

无论采用哪种方式,都应让上层只依赖稳定契约。对子智能体而言,内部节点、提示词、临时状态都可以演进;只要工具参数和返回语义不变,上层工作流就不需要跟着重构。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

把子智能体封装成工具

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通