Aegra子图组合教程:3步掌握嵌套LangGraph图,快速构建可复用的多Agent协作系统
Aegra子图组合教程:3步掌握嵌套LangGraph图,快速构建可复用的多Agent协作系统
Aegra 是一个开源、可自托管的 AI Agent 后端平台,被视为 LangGraph Platform 的免费替代品,基于 FastAPI 和 PostgreSQL 构建。本教程带你用 3 个步骤掌握 Aegra 子图(subgraph)组合技巧:将多个独立的 LangGraph 图嵌套为一个整体,构建可复用的多 Agent 协作系统,全程无需重复造轮子。
为什么需要Aegra子图:多Agent协作的痛点
如果你用过 LangGraph,应该体会过这种场景:
- 搜索 Agent、代码 Agent、审批 Agent 各自逻辑复杂,堆在一个
graph.py里互相纠缠,改一处崩一片; - 同一个"ReAct Agent"想在多个业务流程中复用,只能复制粘贴;
- 主流程里想插一段人工审批,状态管理瞬间失控。
子图(Subgraph)就是解法:把复杂的 Agent 逻辑拆成可复用、可组合的模块——父图(parent graph)直接把另一个已编译的图当作一个普通节点来调用。Aegra 会在父子图边界之间透明地处理状态管理、事件流式输出和中断(interrupt),你几乎不需要感知"边界"的存在。
📌 能力速览:子图流式输出、子图中断、子图检查点(checkpoint)持久化,在 Aegra 中均已原生支持(参见 docs/feature-support.mdx)。
Aegra子图组合基础:3步完成嵌套
第1步:把编译后的图直接作为节点添加
LangGraph 允许 add_node 接收一个已编译的图。假设你有一个现成的搜索子图:
from langgraph.graph import StateGraph
# 导入你已编译的子图
from my_agents.search_agent import graph as search_graph
builder = StateGraph(State)
builder.add_node("coordinator", coordinator_node)
builder.add_node("search_agent", search_graph) # 直接把图当节点!
builder.add_node("summarizer", summarize_node)
builder.set_entry_point("coordinator")
builder.add_edge("coordinator", "search_agent")
builder.add_edge("search_agent", "summarizer")
graph = builder.compile()
注意 builder.add_node("search_agent", search_graph) 这一行——不需要写任何包装函数,编译后的图直接就是一个节点。
第2步:对齐父图与子图的状态(State)
上图之所以能"即插即用",是因为父子图共享同一个 State 结构,消息列表可以无缝透传;每个节点返回的字段会自动合并进共享状态。如果子图使用不同的状态结构,就需要在中间加一个自定义节点函数做数据转换。
Aegra 自带的示例就是这么做的:examples/subgraph_agent/graph.py 仅用一行 builder.add_node("subgraph_agent", react_graph),就把完整的 ReAct Agent(模型调用 + 工具循环,见 examples/react_agent/graph.py)挂载到了父图上。
第3步:在 aegra.json 中注册
只有顶层图需要注册,子图无需单独注册:
{
"graphs": {
"orchestrator": "./src/orchestrator/graph.py:graph"
}
}
💡 参考仓库根目录的注册配置:aegra.json,其中
subgraph_agent、subgraph_hitl_agent都是真实的子图示例。
多Agent协作实战:Orchestrator协调者模式
子图最有价值的玩法是 orchestrator(协调者)模式:一个意图分类节点 + 条件路由,把任务动态分派给不同专家子图。
from agents.search_agent import graph as search_graph
from agents.code_agent import graph as code_graph
def router(state):
"""根据意图路由到对应的专家Agent。"""
intent = state["intent"]
if intent == "search":
return "search_agent"
elif intent == "code":
return "code_agent"
return "__end__"
builder = StateGraph(State)
builder.add_node("classify", classify_intent)
builder.add_node("search_agent", search_graph)
builder.add_node("code_agent", code_graph)
builder.set_entry_point("classify")
builder.add_conditional_edges("classify", router)
graph = builder.compile()
两个值得记住的特性:
- 边和条件路由对子图一视同仁——子图在父图眼里就是一个普通节点,
add_conditional_edges照常使用; - 嵌套深度不限——子图里可以再套子图,形成"图套图"的树状结构。每个层级都有独立的状态命名空间(namespace)和检查点,互不干扰。
流式输出子图事件:一个参数看清全局
默认情况下,流式输出(streaming)只包含顶层图的事件,子图内部是"黑盒"。想实时看到子图内部发生了什么,加一个参数即可:
async for chunk in client.runs.stream(
thread_id=thread_id,
assistant_id="orchestrator",
input={"messages": [{"type": "human", "content": "Research this topic"}]},
stream_subgraphs=True, # 关键:包含子图事件
):
print(chunk)
在 v2 流协议中,每个事件都携带 namespace 字段,标明它来自哪条子图路径,方便你在前端做分层展示。更多细节可查阅 docs/guides/streaming.mdx。
子图中的中断:人工审批无感穿透
这是子图组合中最"省心"的部分:interrupt() 可以穿透子图边界。
子图里调用 interrupt() 后,整个 run 自动暂停,客户端收到中断负载;恢复(resume)后执行会直接在子图内部继续。仓库中的示例 examples/subgraph_hitl_agent/graph.py 就演示了这一点:
def subgraph_node(state: State) -> State:
"""在子图内部中断,等待用户提供值。"""
value = interrupt("Provide value:")
return {"foo": state["foo"] + value}
客户端侧的处理流程和顶层图中断完全一致(详见 docs/guides/human-in-the-loop.mdx)。这意味着你可以把"下单前必须人工确认"这类审批逻辑封装进子图——父图无需知道审批细节,只管等它完成。
检查子图结构与状态:Aegra内置工具
组装完之后,怎么确认结构对不对?Aegra 的 assistant API 提供了开箱即用的内省能力(服务端实现见 libs/aegra-api/src/aegra_api/api/assistants.py):
# 列出某个assistant的全部子图
subgraphs = await client.assistants.get_subgraphs(assistant_id)
# 递归列出深层嵌套的子图
subgraphs = await client.assistants.get_subgraphs(assistant_id, recurse=True)
# Xray模式:把子图节点"展开"成可视化结构,可用深度整数控制展开层数
graph = await client.assistants.get_graph(assistant_id, xray=2)
状态检查同样简单——子图的检查点保存在父图 checkpoint 内,加一个参数即可看到:
# 获取线程状态,同时包含子图检查点
state = await client.threads.get_state(thread_id, subgraphs=True)
调试多 Agent 系统时,xray 展开 + 子图状态检查这两个组合拳非常实用。
子图组合最佳实践清单
最后送你一份落地清单 ✅:
| 实践 | 说明 |
|---|---|
| 状态结构对齐 | 父子图共享 State,避免频繁的中间转换层 |
| 按业务能力拆分 | 搜索、编码、审批各成一个子图,独立演进、多处复用 |
| 路由逻辑放父图 | add_conditional_edges 写在协调者里,子图保持"无脑执行" |
| 按需开启流式 | stream_subgraphs=True 在调试期全开,生产期按需裁剪 |
| 审批下沉子图 | 用子图内 interrupt() 封装审批细节,父图零感知 |
| 嵌套前先用 xray 验证 | get_graph(xray=2) 确认每一层连接符合预期 |
常见问题FAQ
Q1:子图必须和父图用同一个 State 吗? 不是必须的,但必须对齐。不同 schema 时加一个自定义节点函数做映射即可,代价是多一层胶水代码。
Q2:子图里的工具调用(tool call)事件会丢失吗?
不会。开启 stream_subgraphs=True 后,子图内部的事件都会按 namespace 路径流出来,包括工具调用。
Q3:嵌套多少层算"过深"?
技术上不限层数。但超过 2~3 层后调试成本会显著上升,建议用 get_subgraphs(recurse=True) 和 xray 展开提前审查结构。
Q4:崩溃后恢复,子图状态会丢吗? 不会。子图状态存储在父图检查点内,配合 Aegra 的租约(lease)崩溃恢复机制,run 可以从断点继续执行。
总结
Aegra 子图组合的核心就三句话:编译的图即节点、注册只写顶层图、事件与中断自动穿透。按本教程的 3 个步骤走完,你就能把手里的多个 Agent 组装成一个职责清晰、可复用、可观测的协作系统——这正是构建生产级多 Agent 应用的地基。
📖 延伸阅读:docs/guides/subgraphs.mdx、docs/guides/human-in-the-loop.mdx、docs/guides/streaming.mdx
