知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# Agent 编排引擎设计:自研 vs 框架 > 导读:本文从"第一版 Agent 用某个框架拼起来了,第二版要加并行分支、人工审批、断点续跑和失败补偿,结果越改越乱,最后要不要推倒自研"这个具体痛点出发,把"编排到底编排什么"、框架与自研的选型依据、自研引擎的核心抽象、控制流实现要点、状态与持久化接口、错误重试与并发调度、可扩展点,以及一个最小可用引擎的执行链路逐项讲透,最后给出工程实践与踩坑清单。适合正在做 Agent 平台或复杂工作流的架构师与资深后端同学。 ## 一、先建立全局认知 ### Q:所谓"编排"(orchestration),到底编排的是什么? A:结论先行——**编排管的是"多个执行单元之间怎么串起来、状态放在哪、出错怎么办、能不能被打断再续上"这四件事;它不是"调用模型",而是"调度一堆会调用模型的步骤"。** 把这句话拆成七个可落地的关注点,就是引擎的全部职责面: | 关注点 | 编排要解决的问题 | 典型机制 | | --- | --- | --- | | 节点/步骤(Node / Step) | 一次执行由哪些单元组成,每个单元做什么 | 节点定义、入参出参契约 | | 控制流(Control Flow) | 步骤之间按什么顺序走:串行/并行/条件/循环/子图 | 边(Edge)、条件路由、循环上限 | | 状态(State) | 多次步骤之间要共享哪些数据,如何读写 | 共享状态对象、读写约定(reducer) | | 并发(Concurrency) | 哪些步骤能同时跑,并发度谁限制 | 并行分支、并发上限、调度器 | | 错误与重试(Error & Retry) | 哪类错误可重试、重试几次、失败如何补偿 | 重试策略、幂等、补偿动作 | | 中断恢复(Interrupt & Resume) | 执行到一半能否暂停、重启后能否续跑 | 检查点(Checkpoint)、持久化 | | 人工介入(Human-in-the-loop) | 关键节点如何暂停等人工确认/编辑 | 中断点、审批、恢复注入 | 一个关键认知:**"编排"和"推理"是两层。** 推理层回答"这一步该做什么"(模型 + 工具),编排层回答"这一步做完之后,下一步走哪、状态怎么变、失败了怎么办"。很多人把两者混在一起,导致代码里模型调用和控制流纠缠,改一处动全身。**能把这两层切开,是引擎设计的第一个分水岭。** 用一张结构图把层次摆清楚:  *图:编排层——调度器、共享状态、钩子与两类节点* ```text ┌─────────────────────────── 编排层 Orchestration ───────────────────────────┐ │ Scheduler 调度器 │ │ ├─ 决定"下一个该跑哪个节点"(控制流求值) │ │ ├─ 决定"这些节点能不能并行"(并发) │ │ ├─ 决定"失败后要不要重试/补偿"(错误策略) │ │ └─ 决定"要不要在此处持久化/等人工"(检查点 / 中断) │ │ State 共享状态 ◀─────────────────────────────────▶ Checkpoint 持久化 │ │ Hook 前后置钩子(日志/埋点/鉴权/限流) │ └───────────────▲───────────────────────────────────────────▲──────────────┘ │ 调用 │ 调用 ┌───────┴────────┐ ┌────────┴────────┐ │ Node: LLM 调用 │ │ Node: 工具调用 │ │ (推理层) │ │ (推理层) │ └────────────────┘ └─────────────────┘ ``` ### Q:自研、LangGraph 类框架、通用工作流引擎,怎么选? A:结论先行——**选型不看"框架好不好",而看"你的控制流复杂度、状态复杂度、团队维护能力"三者的组合。轻量线性流程直接手写;图状/有状态/需断点续跑优先用 LangGraph 这类 Agent 原生框架;需要与既有 BPM/审批体系对齐才考虑通用工作流引擎;只有当框架的表达力或运维边界卡死你时,才自研。** 选型决策表(**各框架的具体能力随版本变化,落地前需结合所用版本确认**): | 维度 | 手写循环 | Agent 原生框架(如 LangGraph 类) | 通用工作流引擎(如 BPM/状态机引擎) | 自研引擎 | | --- | --- | --- | --- | --- | | 控制流表达力 | 弱(硬编码 if/for) | 强(图/条件/循环/子图) | 强(流程定义 + 网关) | 取决于投入 | | 状态管理 | 自己维护 | 内置共享状态 + reducer | 流程变量 | 自己设计 | | 断点续跑 | 基本没有 | 内置检查点机制 | 内置 | 自己实现 | | 人工介入 | 自己写 | 有中断/恢复原语 | 任务分配/审批成熟 | 自己实现 | | 可观测性 | 自己埋 | 框架层可挂 | 成熟 | 自己埋 | | 学习/迁移成本 | 低(但复杂度迁移到你的代码) | 中(需理解其抽象与版本变更) | 中高(流程定义 DSL) | 高 | | 定制自由度 | 高(但重复造轮子) | 中(受框架抽象约束) | 中 | 最高 | | 版本升级风险 | 无 | **框架大版本变更可能带来迁移成本** | 版本兼容是重点 | 无 | | 适用场景 | 单 Agent、线性、步骤少 | 多节点、有状态、需续跑/HITL | 与组织流程/审批强绑定 | 平台化、多业务复用、框架卡死 | 判断依据可以浓缩成三个问题: 1. **控制流是"线"还是"图"?** 线性 2~3 步,手写更划算;一旦出现条件分支 + 并行 + 循环 + 子流程,就该上图层抽象,否则你的 `if/else` 会变成不可维护的意大利面。 2. **是否必须"断点续跑 / 人工介入"?** 只要业务要求"任务可暂停、可审批、可重启续跑",就别手写——这需要状态持久化 + 幂等 + 恢复语义,成本很高。 3. **框架的抽象边界会不会卡死你?** 如果框架不支持你需要的并发模型、持久化后端或观测埋点,且无法通过扩展点绕过,那就到了自研的临界点。**自研的触发条件应该是"框架明确不满足",而不是"框架我不熟"。** ## 二、理解核心机制:自研引擎的核心抽象 ### Q:一个编排引擎需要哪些核心抽象? A:结论先行——**最小可用集合是六个:Node(节点/任务)、State(共享状态)、Edge(边/条件路由)、Context(执行上下文)、Hook(前后置钩子)、Scheduler(调度器)。其中 Node 定义"做什么",Edge + Scheduler 定义"下一步走哪",State + Context 定义"数据放哪",Hook 定义"横切逻辑挂哪"。** 逐个说清职责与接口: **1. Node(节点 / 任务,Task)——执行单元。** 它是引擎的最小可执行粒度,通常有四种形态:LLM 节点(调模型)、工具节点(调外部)、逻辑节点(纯计算/分支)、子图节点(引用另一张图)。 ```python # 节点的最小契约(伪代码):输入不读全局,输出不写全局,靠返回值合并进 State class Node: name: str def run(self, ctx: "Context") -> dict: """返回一个 dict,表示本节点对 State 的增量贡献(delta)。 引擎负责把 delta 按 reducer 合并进 State,节点本身不直接改 State。 """ raise NotImplementedError ``` **为什么节点不直接改 State?** 因为并行分支会同时写 State,直接改会产生竞态与不可预测的覆盖。让节点只产出 delta、由引擎串行合并,是并行安全的关键设计。 **2. State(共享状态)——跨步骤数据总线。** 它承载"上一次步骤的产出"和"全局上下文"。核心设计问题是**合并语义(reducer)**:同名 key 是多节点并发写时是覆盖、追加还是合并? | 合并语义 | 行为 | 适用 | | --- | --- | --- | | replace(覆盖) | 后写覆盖先写 | 单值配置、最新状态 | | append(追加) | 拼成列表 | 消息历史、日志、候选集 | | merge(合并) | 浅/深合并 dict | 结构化中间结果 | | 自定义 reducer | 用户函数 | 去重、求和、取最优 | **3. Edge / 条件路由(Conditional Routing)——控制流的边。** 两种边:静态边(A 之后固定走 B)和条件边(根据 State 求值决定走 B 还是 C)。条件边本质上是一个纯函数 `State -> 下一个/下一组节点名`。 ```python # 条件路由:给定当前 State,返回下一批要执行的节点名 def route_after_review(state: dict) -> list[str]: if state.get("review_passed"): return ["finalize"] if state.get("retry_count", 0) >= 3: return ["escalate"] # 转人工/升级 return ["revise"] # 回到修订节点(形成循环) ``` **4. Context(执行上下文)——单次执行的控制面。** 它区别于 State:State 是"业务数据",Context 是"这次执行的元信息与能力",例如 `run_id`、当前步数、剩余步数预算、超时预算、追踪 ID、取消信号、并发信号量、日志器。**节点通过 Context 拿能力,而不是通过全局单例。** **5. Hook(前后置钩子)——横切关注点。** 在节点执行前后、图开始/结束、边选择时插入逻辑:埋点、日志、鉴权、限流、脱敏、成本统计。它是"不侵入业务节点"的扩展点。 **6. Scheduler(调度器)——引擎心脏。** 它反复做四件事:取就绪节点 → 按并发约束执行 → 合并 State → 求值边得到下一步;直到满足终止条件(到达 END / 超过步数上限 / 取消)。 ### Q:控制流(串行 / 并行 / 条件 / 循环 / 子图)怎么实现? A:结论先行——**把这五种控制流都归约成"调度器在每一轮根据 State 计算出一组就绪节点、并行执行、合并结果"这一个循环,是引擎实现最省心的做法;区别只在于"下一组节点"是怎么算出来的,以及"循环要有步数上限"。** 五种控制流与实现方式: | 控制流 | 语义 | 实现要点 | | --- | --- | --- | | 串行 | A 完再 B | 静态边 A→B,每轮就绪集只有 1 个 | | 并行 | A、B 同时跑 | 同一轮就绪集含多个节点,受并发上限约束 | | 条件 | 按 State 选一条路 | 条件边求值返回下一组节点 | | 循环 | 回到之前的节点 | 条件边指回上游节点,**必须设步数/循环上限** | | 子图 | 复用一张图 | 节点内部持有一个子引擎,子图结束把结果作为 delta 合并 | 一个把五者统一的执行循环(伪代码,解决"如何用单一机制表达所有控制流"): ```python def execute(graph, initial_state, ctx): state = initial_state frontier = [graph.entry] # 就绪节点集合 while frontier and ctx.steps < ctx.max_steps: # 1) 取本轮就绪节点(串行=1个,并行/条件分支=多个) batch = schedule(frontier, ctx) # scheduler 决定真正并发执行的子集 # 2) 前置钩子 + 并发执行 + 后置钩子 for node_name in batch: hook.before(node_name, state, ctx) deltas = run_parallel(batch, state, ctx) # 受并发上限约束 for node_name in batch: hook.after(node_name, state, ctx) # 3) 按 reducer 合并所有 delta 进 state(串行合并,避免竞态) state = merge_state(state, deltas, graph.reducers) # 4) 求值边,算出下一轮就绪节点(条件/循环/子图都在这里体现) frontier = eval_edges(graph, batch, state) ctx.steps += 1 if ctx.steps >= ctx.max_steps: ctx.mark_step_limit_reached() # 步数上限:必须显式记录而非静默结束 return state ``` **死循环与步数上限是这里的头号风险。** 循环控制流 + 条件路由写错,很容易出现"A→B→A"永不终止;更隐蔽的是"看似有收敛条件,但模型每次都给同一个错误判断"。所以: - 引擎层必须有**硬性步数上限**和**单图最大访问同一节点次数上限**,二者独立设置,作为最后防线。 - 到达上限时**必须产出可观测事件**(`step_limit_reached`)而不是静默返回半成品,否则线上表现为"偶发任务无结果",排查极难。 - 上限值应可配、可按租户/场景覆盖(不同复杂度任务需求不同)。 ## 三、状态与持久化接口 ### Q:状态(State)与检查点(Checkpoint)是什么关系?接口该怎么设计? A:结论先行——**State 是"当前这一轮执行需要读写的数据",Checkpoint 是"把 State(加执行位置)在某个时刻落盘的一份快照"。引擎要做的不是实现存储,而是定义好"读—改—写"的接口,把存储后端留给可替换的实现(内存/Redis/关系库/对象存储)。** 职责边界(**只讲接口设计,不展开持久化细节**): ```text State : 业务数据,执行期间高频读写,驻留内存 Checkpoint : 某个步骤边界上的 State + 游标(当前节点/就绪集) + 元信息 的快照 Checkpointer : 负责 save / load / list 的接口,实现可替换 ``` 一个最小接口设计(伪代码): ```python from abc import ABC, abstractmethod class Checkpointer(ABC): @abstractmethod def save(self, run_id: str, step: int, snapshot: dict) -> None: """在步骤边界写入一份快照。snapshot 需包含 state + cursor + meta。""" @abstractmethod def load_latest(self, run_id: str) -> dict | None: """恢复时取最新快照;返回 None 表示无历史(从头开始)。""" @abstractmethod def list_checkpoints(self, run_id: str) -> list[int]: """列出该 run 的所有步骤号,用于回溯/时间旅行调试。""" ``` 设计要点与边界: - **快照应在"步骤边界"写,不要在节点执行中写。** 因为执行中的 State 可能是中间态,恢复后语义不完整。 - **快照内容要自包含**:至少包含 `state`、`cursor`(下一步该跑哪些节点)、`step`、以及幂等所需的 `idempotency_key` 信息。否则恢复后不知道"从哪继续"。 - **接口要支持"从任意历史步骤恢复"**(时间旅行),这在调试复杂 Agent 时价值极高,但会增加存储成本,**是否保留全量历史需按业务与版本策略决定**。 - **存储后端的选型由接口隔离**:开发期内存/文件,生产期需要共享存储以支持多实例恢复。**具体后端能力与一致性保证需结合所用组件版本确认。** - **不要把 Checkpoint 当成"日志"。** 日志可以丢,Checkpoint 丢了就无法续跑;两者的保留策略和持久化级别不同。 ## 四、错误处理、重试与并发调度 ### Q:错误处理与重试策略怎么设计才不"帮倒忙"? A:结论先行——**先给错误分类(可重试 / 不可重试 / 需补偿),再决定策略:可重试的做"带退避的有限重试",且要求操作幂等;不可重试的直接失败并触发补偿;涉及外部副作用的必须做幂等键或补偿动作。无脑重试是最常见的"帮倒忙"。** 错误分类表: | 错误类型 | 例子 | 是否可重试 | 处理策略 | | --- | --- | --- | --- | | 瞬时/可恢复 | 网络抖动、下游 5xx、限流 429 | 是 | 退避重试,有上限 | | 永久/参数错 | 参数校验失败、模型拒答、权限不足 | 否 | 直接失败,不重试 | | 副作用不明 | 超时但下游可能已执行 | **谨慎** | 需先查询状态再决定,或幂等重试 | | 需补偿 | 已下单/已扣款后续步骤失败 | — | 执行补偿动作(回滚/冲正) | 三条工程铁律: 1. **可重试的前提是幂等(idempotent)。** 幂等指"同一操作执行多次,效果与执行一次相同"。对一个下单工具重试,如果不带幂等键,用户会被下两次单。**幂等键应贯穿"模型请求 → 工具调用 → 下游"整条链路**,通常由 `run_id + node_name + step + 业务键` 组合生成。 2. **重试要带指数退避 + 抖动(jitter)。** 固定间隔重试会在下游恢复瞬间形成"重试风暴"。抖动是防止多个客户端同步重试的关键。 3. **重试预算要与整体 SLA 对齐。** 单节点重试 3 次、每次 30s,本身就可能吃掉整个任务的延迟预算。**总重试时间必须纳入任务超时预算统一分配。** ```python import random, time def retry_call(fn, max_attempts=3, base_delay=0.5, idempotency_key=None): """带退避与抖动的有限重试。仅用于幂等操作。 注意:不可重试错误应在 fn 内抛出特定异常直接穿透,不做重试。 """ for attempt in range(1, max_attempts + 1): try: return fn() except RetryableError as e: if attempt == max_attempts: raise # 指数退避 + 抖动:避免同步重试风暴 delay = base_delay * (2 ** (attempt - 1)) delay = delay * (0.5 + random.random()) # jitter time.sleep(delay) ``` **适用边界**:这段重试只解决"调用层的瞬时失败"。它**不能**替代补偿机制——如果下游已经产生了副作用,重试只会放大副作用,此时应该走补偿路径。 ### Q:并发与资源调度该怎么做? A:结论先行——**并行分支的并发模型要在设计阶段就定:I/O 密集(模型/工具调用都是等待)用协程或虚拟线程更省资源,CPU 密集用有界线程池;无论用哪种,都必须有显式并发上限,否则并行分支会把下游和模型配额一起打爆。** 并发模型对照: | 模型 | 适用场景 | 关键约束 | | --- | --- | --- | | 协程 / 异步(async-await) | 大量 I/O 等待(模型、工具调用) | 需要下游客户端支持异步;同步阻塞会拖垮事件循环 | | 虚拟线程 | 同步 I/O 风格但想要高并发 | **需确认运行时版本是否支持,并注意下游连接池仍是瓶颈** | | 有界线程池 | 混合负载、有 CPU 计算 | 池大小与队列必须有界且可观测 | | 结构化并发 | 希望"分支同生共死"、统一取消 | 需运行时代码级支持 | ```java // 并行分支的并发上限:用有界信号量限制"同时在跑的节点数" import java.util.concurrent.*; public class ParallelExecutor { private final Semaphore permits; // 并发上限,显式设置 private final ExecutorService pool; public ParallelExecutor(int maxConcurrent) { this.permits = new Semaphore(maxConcurrent); this.pool = Executors.newFixedThreadPool(maxConcurrent); } public Object runWithLimit(Callable<Object> node) throws Exception { permits.acquire(); // 拿不到许可就排队,形成背压 try { return pool.submit(node).get(); } finally { permits.release(); } } } ``` 要点与边界: - **并发上限必须贯穿全链路对齐**:引擎并行度、模型客户端连接池、工具连接池、下游承受能力,取最小者才是真实并发。**只调大其中一层不会提升吞吐,只会把压力转移成排队。** - **并行分支要能"统一取消"。** 一个分支失败时,其它分支若继续跑,会浪费资源甚至产生半成品副作用;因此需要取消传播(cancellation propagation)。 - **并发不等于更快。** 无上限的并行会把下游打到限流,整体反而更慢;**并发上限是一种保护,不是性能旋钮。** ## 五、可扩展点与最小可用引擎 ### Q:引擎应该留出哪些可扩展点? A:结论先行——**至少留四类:中间件/插件(横切逻辑)、埋点(观测)、限流(保护)、以及存储/模型/工具的可替换实现(依赖倒置)。扩展点的设计目标是"新增能力不改引擎核心"。** | 扩展点 | 挂载位置 | 典型用途 | | --- | --- | --- | | 中间件 / 插件 | 节点执行前后(Hook 链) | 鉴权、脱敏、成本统计、重试包装 | | 埋点 | 节点/边/图开始结束 | trace、span、指标上报 | | 限流 | 节点入口、模型调用前、工具调用前 | 保护配额与下游 | | 可替换实现 | 存储、模型客户端、工具注册中心 | 换后端/换供应商不改业务 | ```yaml # 扩展点声明式配置(示例,字段为设计示意,非某框架真实 schema) engine: hooks: - name: authz # 鉴权 point: before_node - name: cost-meter # 成本统计 point: after_node - name: trace # 埋点 point: graph_start | node_start | node_end | graph_end limits: model_concurrency: 20 # 模型侧并发上限 tool_concurrency: 50 # 工具侧并发上限 max_steps: 25 # 步数硬上限 max_node_visits: 8 # 单节点最大访问次数 checkpointer: type: replaceable # 存储后端可替换 ``` 要点:**扩展点的"顺序"本身是语义。** 例如鉴权必须在执行前、成本统计必须在拿到 Token 用量之后、脱敏必须在落盘之前。**扩展点的执行顺序需要被明确定义并测试**,否则插件的相对顺序会让行为不可预测。 ### Q:一个"最小可用引擎"走完一次执行链路长什么样? A:结论先行——**一次执行的核心链路是:load 检查点(恢复)→ 循环(取就绪节点 → 钩子 → 执行 → 合并 State → 求值边)→ 每个步骤边界 save 检查点 → 命中人工中断则挂起 → 到 END 或步数上限终止。下面是这条链路的完整伪代码。** ```python def run_engine(graph, run_id, user_input, checkpointer, hooks, limits): # 1) 恢复:有历史检查点就从断点续跑,否则初始化 snap = checkpointer.load_latest(run_id) if snap: state, cursor, step = snap["state"], snap["cursor"], snap["step"] else: state, cursor, step = graph.init_state(user_input), [graph.entry], 0 ctx = Context(run_id=run_id, max_steps=limits["max_steps"], step=step) hooks.emit("graph_start", state, ctx) while cursor and ctx.step < limits["max_steps"]: batch = schedule(cursor, ctx) # 并发上限内确定真正执行子集 deltas = [] for node_name in batch: node = graph.nodes[node_name] hooks.emit("node_start", node_name, state, ctx) try: hooks.run_before(node_name, state, ctx) delta = node.run(ctx) # 节点只产出增量 hooks.run_after(node_name, state, ctx, delta) except RetryableError: delta = retry_call(lambda: node.run(ctx)) # 有限重试 except Exception as e: delta = handle_failure(node_name, e, state, ctx) # 补偿/标记 deltas.append(delta) hooks.emit("node_end", node_name, state, ctx, delta) state = merge_state(state, deltas, graph.reducers) # 串行合并,避免竞态 cursor = eval_edges(graph, batch, state) # 条件/循环/子图在此体现 # 2) 人工介入:命中中断点则持久化并挂起,等待外部恢复信号 if graph.is_interrupt_point(cursor): checkpointer.save(run_id, ctx.step, {"state": state, "cursor": cursor}) hooks.emit("interrupted", state, ctx) return {"status": "INTERRUPTED", "state": state} ctx.step += 1 checkpointer.save(run_id, ctx.step, {"state": state, "cursor": cursor}) status = "DONE" if not cursor else "STEP_LIMIT" hooks.emit("graph_end", state, ctx, status) return {"status": status, "state": state} ``` 关键点与适用边界: - **恢复(resume)与首次执行走同一段代码**,只是入口数据来源不同——这是"断点续跑"能可靠工作的前提。 - **检查点在步骤边界保存**,中断时也会保存,所以人工审批后可从同一点继续。 - **步数上限是硬闸门**,命中后返回 `STEP_LIMIT` 而非静默结束,便于观测与告警。 - **适用边界**:这是骨架,省略了分布式调度、多实例抢占、事件持久化、并发子图的生命周期管理。生产引擎还要解决"同一 run 被两个实例同时调度"的问题(需要租约/锁),**这部分与所选存储后端的原子能力相关,需结合版本确认**。 ## 六、工程实践与踩坑清单 ### Q:自研或引入编排引擎时,最常踩的坑有哪些? A:结论先行——**按"设计过度、状态、控制流、观测、迁移"五类记。** **设计过度类:** 1. **先自研,后发现框架已够用。** 为了"可控"从零造引擎,结果实现了一遍框架的抽象还更差。**对策**:先在框架里做成,遇到明确边界再自研。 2. **反过来:硬套框架,忽略表达力边界。** 需求有复杂并发/HITL,框架不满足却硬改。**对策**:用"控制流复杂度 + 状态复杂度 + 续跑需求"三问早期判断。 3. **把推理和控制流揉在一起。** 模型调用里写满 if/for,改一处动全身。**对策**:分层——推理层只做"这一步做什么",编排层只做"下一步走哪"。 **状态类:** 4. **状态膨胀。** State 里什么历史都往里塞,快照越来越大,序列化/存储/恢复越来越慢。**对策**:State 只放"后续步骤真正需要的",历史放外部存储,用引用代替全量。 5. **并发写 State 竞态。** 多分支同时改 State,结果随机。**对策**:节点只产出 delta,由引擎串行合并;明确 reducer 语义。 6. **快照不可序列化。** State 里放了连接、句柄、闭包,落盘直接失败。**对策**:State 必须是可序列化的纯数据,能力放 Context。 **控制流类:** 7. **隐式控制流。** 下一步走哪藏在节点内部(节点自己决定跳转),图上看不出来。**对策**:控制流必须在边/路由函数里显式表达,节点保持"纯执行"。 8. **死循环 / 无步数上限。** 循环收敛条件写错,任务永不结束。**对策**:步数上限 + 单节点访问次数上限双保险,命中必打观测事件。 9. **循环上限静默截断。** 到上限直接返回半成品,线上表现为"偶发无结果"。**对策**:截断必须产生明确状态与告警。 10. **并行分支无统一取消。** 一个分支失败其它继续跑,浪费并产生副作用。**对策**:取消传播 + 失败时的补偿。 **观测与错误类:** 11. **缺乏观测。** 不知道任务卡在哪一步、每步耗时/成本多少。**对策**:节点级埋点 + 步数/Token/延迟采集 + trace 贯穿。 12. **无脑重试。** 对非幂等操作重试,产生重复副作用。**对策**:错误分类 + 幂等键 + 退避抖动。 13. **只有重试没有补偿。** 下游已产生副作用,重试放大问题。**对策**:需补偿的场景设计补偿动作。 **迁移与运维类:** 14. **升级框架导致迁移成本。** 框架大版本变更,图定义/状态 API 变化,迁移工作量大。**对策**:**把业务控制流与框架 API 之间隔一层自己的 DSL/适配层**,降低耦合并记录所用版本。 15. **同一 run 被多实例重复调度。** 分布式下恢复机制缺租约,任务被跑两遍。**对策**:调度租约/幂等键,**具体需结合存储后端原子能力确认**。 16. **检查点存储与业务库强耦合。** 想换后端发现动不了。**对策**:Checkpointer 接口化,后端可替换。 17. **扩展点顺序未定义。** 插件先后顺序不确定,行为不可预测。**对策**:显式定义并测试扩展点执行序。 ## 小结 - 编排(orchestration)编排的是**节点、控制流、状态、并发、错误重试、中断恢复、人工介入**七件事;它与"推理"是两层,**分层是引擎设计的第一原则**。 - 选型看三问:**控制流是线还是图?是否必须断点续跑/人工介入?框架抽象会不会卡死你?** 手写适合线性小流程;Agent 原生框架适合图状有状态;通用工作流引擎适合与既有审批体系对齐;自研的正当理由是"框架明确不满足"。 - 自研引擎的六个核心抽象:**Node(只产出 delta)、State(含 reducer 合并语义)、Edge(静态/条件路由)、Context(元信息与能力)、Hook(横切逻辑)、Scheduler(调度心脏)**。 - 五种控制流可归约为**同一个"取就绪节点 → 执行 → 合并 → 求值边"的循环**;**步数上限与单节点访问上限是防死循环的最后防线,命中必须显式可观测**。 - State 是内存里的业务数据,Checkpoint 是步骤边界上的快照;引擎应定义**可替换的 Checkpointer 接口(save / load_latest / list)**,快照要自包含(state + cursor + step)。 - 错误处理先分类:**可重试(幂等 + 退避抖动)/ 不可重试 / 需补偿**;重试预算要纳入任务总超时,重试不能替代补偿。 - 并发模型按 I/O 或 CPU 密集选协程/虚拟线程/有界线程池,且**并发上限必须全链路对齐(取木桶最短板)**,并支持取消传播。 - 扩展点是**中间件/插件、埋点、限流、可替换实现**;扩展点的**执行顺序本身是语义,必须显式定义**。 - 让业务控制流与框架 API 之间隔一层适配/DSL,是降低框架升级迁移成本的关键手段;分布式下还需解决同一 run 的重复调度(租约/幂等)。 ## 思考题 1. 你现在的 Agent 代码里,模型调用和控制流是分开的吗?如果把它们强行分层,控制流那一层会剩下什么?哪些地方会暴露"其实控制流藏在节点里"? 2. 设计一个 State 的 reducer 体系:当两个并行分支同时写 `messages` 和 `result` 时,分别应该用哪种合并语义?如果两个分支写的是"打分结果",你希望是覆盖还是取最大值? 3. 循环控制流里,"收敛条件由模型判断"和"由代码规则判断"各有什么风险?你会如何组合两者,既保留灵活性又保证一定终止? 4. 如果团队已经在用一个 Agent 框架,但需要支持"任务暂停等人工审批三天后再继续",你会评估框架的哪些能力?如果框架不支持跨进程恢复,退路是什么? 5. 自研引擎时,如何设计"步骤边界检查点"才能保证恢复后不会重复执行已完成的副作用?幂等键应该由哪几个字段组成? 6. 并行分支中一个分支失败、另一个分支已经调用了有副作用的工具,你会怎么处理?补偿动作应该设计在哪一层? 7. 为什么"把业务控制流与框架 API 之间隔一层自己的 DSL"能降低升级迁移成本?这层抽象本身会带来什么代价,什么情况下不值得?
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入