Aegra子图组合教程:3步掌握嵌套LangGraph图,快速构建可复用的多Agent协作系统

原创2026-10-14 04:37:171,425 阅读
文章标签:人工智能AI Agent后端本地部署Agent 编排

Aegra子图组合教程:3步掌握嵌套LangGraph图,快速构建可复用的多Agent协作系统

Aegra 是一个开源、可自托管的 AI Agent 后端平台,被视为 LangGraph Platform 的免费替代品,基于 FastAPI 和 PostgreSQL 构建。本教程带你用 3 个步骤掌握 Aegra 子图(subgraph)组合技巧:将多个独立的 LangGraph 图嵌套为一个整体,构建可复用的多 Agent 协作系统,全程无需重复造轮子。

Aegra开源LangGraph平台替代方案:自托管AI Agent后端,子图组合的多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()

两个值得记住的特性:

  1. 边和条件路由对子图一视同仁——子图在父图眼里就是一个普通节点,add_conditional_edges 照常使用;
  2. 嵌套深度不限——子图里可以再套子图,形成"图套图"的树状结构。每个层级都有独立的状态命名空间(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

登录后查看全文
aegra