企业官网建设流程全解析

上个月我们内部复盘一个 Agent 项目，结论很有意思：Demo 阶段每个功能都演示得挺好，接入真实业务流之后，调度混乱、状态丢失、工具调用重复，几乎每个模块都在救火。大家一致认为——模型不是瓶颈，Agent Runtime 才是。很多团队把精力花在调 Prompt、换模型上，却忽略了承载这些逻辑的运行时本身。真正好用的 Agent Runtime，关键不在堆功能，而在把编排的底层逻辑理清楚。

这篇文章我会把我这几年在不同项目里折腾 Agent 编排的经验完整拆一遍。从 Runtime 到底要解决什么问题开始，讲到执行模型、协作机制、状态管理，再到工程落地的持久化和可观测性，最后给出一套最小可运行的实现思路和生产环境里的常见坑。适合正在做 Agent 应用、想脱离"跑通 Demo"阶段、把系统真正推向生产的工程师，也适合想理解编排框架底层设计原理的读者。这里面的每一个决定我都见过有人踩过，希望能帮你绕开。

1. 先搞清楚 Runtime 到底在解决什么问题

1.1 Demo 与生产之间的断层在哪里

我第一次做 Agent 应用的时候，想法特别朴素：用户输入一句话，Agent 决定要不要调工具，调完工具把结果丢回模型，最后生成答案。这个循环写起来不到一百行，跑起来也确实能完成几个简单任务。问题出在任务量上来以后：几十个任务同时提交，有的 Agent 要调外部接口，单次调用要等十几秒，有的 Agent 会出现工具调用失败，需要重试，有的中间结果要传递给下一个模块。

一旦进入这种状态，原来的"输入 -> 循环 -> 输出"结构立刻失控。我见过最典型的场景是：某个子任务卡在一个慢接口上，整个进程被阻塞，其他完全不相关的 Agent 也在原地等待；再或者一个 Agent 出错之后直接让整个编排链路终止，前面跑完的步骤全部白费。这些都不是模型能力的问题，而是运行时缺少了调度、隔离、容错这些基本功。说得直白一点，你在 Demo 里写的是一个对话循环，生产环境需要的是一个能管理长生命周期任务的系统。

1.2 Runtime 的职责边界到底划在哪里

我后来把 Runtime 的职责收敛成五块，每一块都可以独立设计、独立演进，这样系统才不会变成一团乱麻。第一是调度，负责决定任务什么时候跑、由哪个执行体来跑、最多跑多久；第二是状态，负责记录每一次运行的进度、中间产物和最终结果；第三是上下文管理，负责决定模型每一轮能看到哪些内容，避免历史无限膨胀；第四是工具管理，负责注册、校验、调用和错误处理；第五是生命周期控制，负责启动、挂起、恢复、终止和清理。

这五块里最重要的是调度和状态。调度的核心是并发模型，状态的核心是持久化。很多团队在这两个问题上没想清楚就急着上线，结果就是每加一个功能都要重构一次。我的建议是，在动手写 Runtime 之前，先花半天时间把这两个问题用文档写清楚：你的系统里 Agent 是怎么被调起来的？任务中断之后能不能恢复？这两个问题答不上来，后面的代码再多也是负债。

2. 执行模型：从"手动编排"到"可控并发"

2.1 最朴素的单线程循环为什么不够用

单线程循环是大多数 Agent Demo 的起点。结构大概是：启动一个 Session，循环里先调模型，看看返回的是文本还是工具调用，是文本就结束，是工具调用就执行工具，把结果追加进消息列表，然后继续调模型。这个模型在任务少、步骤短、接口快的时候没问题，但放到真实生产环境，至少有三件事扛不住。

第一是慢操作阻塞。Agent 经常要调外部 API，单次可能几秒甚至几十秒。单线程下，一个慢操作会把所有任务的执行队列堵死。第二是任务之间没有隔离。一个任务抛异常，整个事件循环崩溃，其他所有运行中的 Agent 跟着遭殃。第三是无法应对扇出场景。真实业务经常要求一个主任务拆成多个子任务并行执行，单线程只能排队做。我见过有团队在单线程模型上硬加线程池，结果共享状态锁成一锅粥，还不如一开始就设计对模型。

2.2 事件驱动与任务窃取：并发模型怎么选

我最终在项目里采用的方案是事件驱动加协作式调度，基于异步事件循环，把 Agent 的每一步建模成一个可挂起的任务。具体来说，每个 Agent 运行实例是一个生成器或异步任务，它执行到某一步需要等待模型返回时，会把控制权交还给事件循环，而不是阻塞整个进程。这样几十个 Agent 可以同时处于"等待模型返回"的状态，事件循环在它们之间切换，像操作系统调度线程一样调度这些轻量级任务。

任务窃取是在多 worker 场景下用的优化手段。当多个执行 worker 共用同一个任务队列时，某个 worker 空闲了，可以从公共队列尾部拿任务；但 Agent 任务之间往往有依赖关系，比普通任务队列复杂。我处理的策略是，把 DAG 依赖检查放在调度器层，任务本身一旦被分发出去就只执行，执行完汇报结果，由调度器决定下一步分发谁。这个设计和数据流水线的思路很像，本质是把"决策"和"执行"分开。决策层保持单点，执行层可以横向扩展。

2.3 挂起与恢复：Agent 不是函数，是一次带状态的会话

这一点是 Agent Runtime 和普通函数调用最本质的区别。普通函数调用是瞬时的，栈帧用完就销毁，调用方的状态在内存里。但 Agent 运行可能持续几分钟甚至几小时，中间要经历多次模型调用、工具调用、人工审批。这中间进程完全可以被重启，容器可以被替换，网络可以断掉再恢复。如果你把 Agent 运行当成一个"从开头连续执行到结尾"的流程，那任何一点故障都会导致整个任务作废。

正确的心智模型是把 Agent 运行当成一次可以暂停和恢复的会话，类似游戏的存档机制。执行到任何一步，都可以把当前进度写进持久化存储；系统崩溃后，从存储里读回这个进度，接着执行，而不是从头开始。实现上我强烈建议做"按步骤持久化"而不是"按会话结束持久化"。每一步结束之后立刻保存一次，这样恢复时间最多损失一个步骤的开销。我见过太多系统只在最后保存一次结果，一旦中途挂了，前面所有 token 和调用费用全部白花。

3. 编排机制的核心：Agent 之间如何协作

3.1 五种协作模式各自的适用边界

Agent 编排不是只有一种形态。按我的经验，常见的协作模式有五种，它们对应不同的业务场景，设计取舍也完全不同。顺序链路是最简单的，Agent A 的输出直接作为 Agent B 的输入，适合处理流水线式任务，比如先做数据清洗再交给分析 Agent。编排器模式是最流行的，一个主 Agent 负责拆解任务、分发子任务、汇总结果，适合项目管理类的场景。

动态路由是在顺序链路上加了一个决策节点，每一步根据当前结果决定下一个处理器是谁，适合客服分流、知识问答这类有条件分支的场景。扇出汇聚是主 Agent 把事情拆成多个独立子任务并行执行，全部完成后再汇总，适合内容审核、批量分析这类高并发场景。最后是人机回环，Agent 执行到关键节点主动挂起，等待人工审批或补充信息后再继续，适合财务审批、发布确认这类需要人在回路里的场景。这五种模式不是互斥的，真正复杂的系统通常会把它们嵌套使用。

3.2 状态传递的两种范式：管道式和共享式

协作模式定了之后，紧接着要回答的问题就是：Agent 之间怎么传数据。管道式传递是把上一个 Agent 的输出显式塞给下一个 Agent，形式上是一个大的数据结构逐个传递。这种模式的优点是直观、依赖清晰，缺点是僵硬，一旦中间步骤要插入新逻辑，整个数据契约就要改。共享式传递则相反，所有 Agent 都读写一个共享存储，谁需要什么自行取用，灵活性非常高。

我现在的项目用的是共享存储加写权限控制的方案，类似带版本控制的黑板架构。每个 Agent 可以向黑板写入结构化数据，但写入必须是追加式的，不允许覆盖已有内容。读取时通过版本号对账，确保每个 Agent 读到的是它该看到的那个版本。这套设计的核心思路是：读写分离，读可以任意，写必须受限。这样既保留了共享存储的灵活，又不会出现多个 Agent 同时改一个字段导致的数据混乱。如果你是小团队快速迭代，这是我目前最推荐的状态传递方案。

3.3 冲突解决与优先级判断

共享存储必然会带来冲突问题。两个子任务都可能更新同一个实体，比如一个更新用户资料，一个更新订单状态，互不相干还好，但如果它们都想修改全局配置，冲突就来了。我的处理原则是：资源按职责切分，状态按领域隔离。每个 Agent 只能写入它被授权的领域，跨领域读可以，跨领域写必须走主 Agent 审批。这套规则相当于给黑板加了权限层，比事后检测冲突更有效，因为它在源头就杜绝了大部分冲突。

优先级判断也很容易被忽略。几十个子任务争抢同一个工具限流配额，到底谁先跑？我建议在任务模型上直接挂优先级字段，调度器按优先级加超时因素统一排序。比如说，用户直接等待的任务优先级最高，后台预处理的次之，批量分析的最低。低优先级任务在高优先级任务等待的时候主动让出资源。实际编码上就是一个优先队列加条件判断，难点不在实现，在于产品层愿意把优先级规则定义清楚。

4. 工程落地的关键设计决策

4.1 持久化：给 Runtime 装上"记忆"

持久化这个决策，直接影响系统能做多重的任务。做持久化之前，进程崩溃是常态，恢复靠重跑；做持久化之后，进程崩溃只损失当前一步。我常用的方案是事件溯源加定期快照的组合。事件溯源指把每个步骤产生的事件，比如"模型调用完成""工具返回结果""人工审批通过"，以不可变日志的形式追加到存储里。恢复运行时，只需要从快照恢复大致的中间状态，然后重放缺少的事件日志，就能精确还原现场。

落到实现上，我建议存储层先保持简单，一个带版本号的结构化表就够用。字段包括：运行实例 ID、步骤序号、事件类型、事件详情、时间戳、父事件 ID。这个表既充当审计日志，又充当恢复来源。不要一开始就上复杂的图数据库，除非你明确知道你的编排拓扑复杂到关系型表无法表达。大多数场景下，一张结构良好的事件表加上一个 JSON 字段存负载，完全撑得住。

4.2 可观测性：没有跟踪就没有编排

Agent Runtime 的可观测性比传统后端服务更重要，因为它是多步骤、多分支、多模型的异步执行系统，任何一个环节出问题，排查成本都非常高。我最开始做这个项目的时候没有埋点，生产上一个任务走到一半结果不符合预期，我完全不知道是哪一步出了问题：模型理解错了？工具参数拼错了？还是上游数据传丢了？靠日志翻半天也定位不出来。

后来我引入了一套以"步骤执行单元"为核心的追踪模型。每个 Agent 步骤都会创建一个追踪片段，记录模型调用前后的上下文摘要、工具调用的入参出参、耗时和 token 消耗。所有片段共享同一个运行实例 ID，聚合之后就能还原出一条完整的执行链路。这个方案的侵入性不大，只需要在 Runtime 的调度层统一埋点，Agent 业务代码可以完全无感。上线之后，线上问题的定位时间从小时级降到了分钟级，这个投入是我觉得整个 Runtime 里性价比最高的一个。

4.3 超时与重试：控制面必须回答的三个问题

任何编排系统都要回答三个问题：最多等多久、最多试几次、失败之后怎么办。第一个问题针对模型调用和工具调用，分别设置超时上限。模型调用超时通常比工具调用长，因为生成耗时长；工具调用超时则要根据接口实际响应速度来定，宁可短一点也不要让整个编排被拖死。第二个问题针对重试策略，我推荐指数退避加随机抖动，避免多个任务同时重试把下游再次打爆。

第三个问题是最关键的：失败之后怎么办。我的经验是区分三种情况分别处理。可重试错误，比如网络超时、服务端 5xx，走自动重试；不可重试错误，比如参数校验失败、认证失败，直接标记为失败状态并触发告警；需要人工介入的错误，比如业务规则不满足，挂起等待人工处理。这三种情况在代码里要用异常类型区分开，不能让所有异常都走同一个重试逻辑，不然后果就是系统对着一个必失败的请求反复重试，浪费资源和时间。

5. 从零实现一个最小可用的 Runtime

5.1 核心数据结构怎么设计

不看花哨的架构图，直接看数据结构。一个最小 Runtime 需要三类核心数据结构：运行实例、步骤定义、任务队列。运行实例保存整体状态，包括实例 ID、当前状态、上下文引用、所有已执行步骤的摘要。步骤定义描述一个具体动作，包括类型、依赖的输入、要调用的 Agent 或工具标识、期望的产出。任务队列则是调度器的输入，队列里的每个条目都指向一个待执行的步骤。

用 Python 伪代码表达大概是下面这样。这不是一个工业化实现，而是一个承载核心设计思路的最小骨架，你完全可以在这个基础上加东西。

from dataclasses import dataclass, field from typing import Any, Optional from enum import Enum import uuid class RunStatus(Enum): PENDING = "pending" RUNNING = "running" SUSPENDED = "suspended" COMPLETED = "completed" FAILED = "failed" @dataclass class Step: step_id: str = field(default_factory=lambda: uuid.uuid4().hex) agent_name: str = "" input_ref: dict = field(default_factory=dict) output_ref: Optional[dict] = None depends_on: list = field(default_factory=list) retry_count: int = 0 status: str = "pending" @dataclass class RunInstance: run_id: str = field(default_factory=lambda: uuid.uuid4().hex) status: RunStatus = RunStatus.PENDING context: dict = field(default_factory=dict) steps: dict = field(default_factory=dict) start_time: Optional[float] = None end_time: Optional[float] = None

这套数据模型的关键在input_ref和depends_on。input_ref声明这个步骤要读哪些共享数据，调度器可以根据它来做冲突检测；depends_on声明步骤依赖哪些前置步骤，调度器根据它来构建执行顺序。只要这两个字段设计清楚，后面加并发、加恢复都比较顺。

5.2 调度循环：最核心的执行逻辑

调度循环是整个 Runtime 的心脏。它做的事情拆开看就四步：从待执行集合里找出所有依赖已满足且未执行的步骤；按优先级排序后分发到执行器；收集执行结果并更新运行实例状态；检查是否触发了运行结束或挂起的条件。这个循环可以同步跑，也可以放进异步事件循环里跑。

import asyncio from collections import deque class MinimalRuntime: def __init__(self, executor, store): self.executor = executor self.store = store async def run(self, run: RunInstance, entrypoint: str): while True: ready_steps = [ s for s in run.steps.values() if s.status == "pending" and self._deps_met(s, run) ] if not ready_steps: break for step in sorted(ready_steps, key=lambda s: s.retry_count): await self._dispatch(run, step) if run.status == RunStatus.SUSPENDED: break return run def _deps_met(self, step: Step, run: RunInstance): return all( run.steps[d].status == "completed" for d in step.depends_on ) async def _dispatch(self, run: RunInstance, step: Step): try: step.status = "running" result = await self.executor.execute(run.context, step) step.output_ref = result step.status = "completed" await self.store.save_step(run.run_id, step) except Exception: step.retry_count += 1 if step.retry_count > 3: step.status = "failed" run.status = RunStatus.FAILED else: step.status = "pending"

这里有几个细节要强调。第一，run循环里每次都重新扫描所有步骤来找就绪步骤，而不是用一个即时的就绪队列，看似低效，但好处是天然支持动态编排：某个步骤完成后，它的下游步骤自动变得可执行。第二，store.save_step在每一步执行完成后立刻调用，这是前面说的"按步骤持久化"。第三步，异常处理区分了可重试和不可重试，这里最小实现先用重试次数兜底，生产环境应该按异常类型细分策略。

5.3 接入模型与工具的边界

调度循环不直接关心模型和工具的具体实现，这是 Runtime 设计里一个非常关键的边界。模型调用应该被抽象成一个统一接口：输入是消息列表加参数，输出是文本或者结构化动作请求。工具调用也应该抽象成统一接口：输入是工具名加参数，输出是结构化结果。Runtime 只负责调度、重试、记录日志，不关心这个工具是调外部 REST API 还是本地 Python 函数。

这个抽象看起来简单，实际意义很大。它让 Runtime 和具体的模型供应商、工具实现解耦，你在不影响调度层的情况下可以随时更换模型。我们项目里甚至做了一个小实验：同一套编排逻辑，底层模型从通用大模型换成垂直领域模型，除了个别 Prompt 需要微调之外，Runtime 代码一行没改。这就是边界设计的好处。另一个收益是可测试性，把模型和工具 mock 掉后，可以纯测调度逻辑的时序和异常处理，后面测试策略那一节会细讲。

6. 生产环境中的坑与优化

6.1 并行失控与限流策略

实时运行一段时间后，我遇到的第一个生产事故就是并行失控。某个主任务需要生成一批子任务，代码里用了扇出汇聚模式，一个循环把所有子步骤一次性提交进队列。本地测试数据量小，没发现问题；生产环境数据量大了之后，一次性冒出上百个并发请求，直接触发了模型供应商的限流，下游工具的数据库连接池也被瞬间打满，整个系统进入雪崩状态。

修复方案是在调度器层加一个全局并发上限，本质上就是一个带计数器的信号量。每次分发步骤前检查当前并发数，达到上限就暂时不派发，等已有步骤完成释放额度之后再继续。同时给每个任务类型设置各自的并发配额，比如外部 API 调用类的并发上限调低，本地计算类的调高。这个坑的教训是：任何扇出汇聚模式都必须配上并发控制，永远不要假设下游系统的吞吐是无限的。

6.2 上下文被历史淹没：怎么管住模型视野

第二个高频问题是上下文管理。Agent 执行步骤越多，消息列表就越长，再加上工具返回值，很容易把模型上下文窗口撑爆。简单的做法是不停地全量追加历史，但这就带来两个严重后果：输入 token 成本线性上涨，而且远距离的早期信息会被新内容稀释，模型反而容易忽略关键约束。

我最后的方案是分层管理上下文。第一层是固定的系统指令，包含全局任务约束，始终保留。第二层是最近 N 轮的完整记录，保证模型能感知当前的执行连续性。第三层是历史摘要，把更早的对话和工具结果用摘要形式沉淀下来，只有当需要追溯某个细节时，才按需从事件存储里检索原始记录。这个结构和人看长文档的方式类似：长期记忆存摘要，短期记忆留原文。这个改造之后，长任务的 token 消耗明显下降，而且任务完成率反而更高了。

6.3 测试策略：如何给编排逻辑建立信心

最后说一下测试。Agent 应用难测试，难在模型的输出不确定。我们换了一个思路：测试对象不是模型，而是编排逻辑。具体做法是，把所有模型调用 mock 成预先录制好的脚本，比如模拟模型第一次返回工具调用请求，第二次返回最终文本。这样调度、重试、挂起、恢复这些逻辑就变成了确定性测试，能枚举所有分支结构。

我维护了一套"剧本测试"的用例集，每个剧本模拟一类典型交互：单轮问答、多轮工具调用、工具失败重试、人工审批挂起、超时恢复。每次改动 Runtime 的调度代码，跑一遍剧本测试，几个小时就能确认调度层没有回归。另一个有用的技巧是故障注入测试，故意让某个工具调用随机抛异常，验证重试策略和失败处理逻辑是否符合预期。这套测试体系建立之后，我才敢在生产环境放量部署，不然真的不敢拍板。

如果让我给一个最关键的实践建议，那就是：先把状态持久化和调度逻辑写对，再去追求花哨的编排模式。多 Agent 协作、动态路由、人机回环这些上层能力，全部依赖一个稳定的运行时底座。底座不稳，上面堆得越高塌得越快。我自己在这个方向上也还在不断迭代，每次在线上看到新的边界情况，就回来补一层逻辑。这套思路如果你也在用，欢迎交流。