智能体工程 · 16
这个业务值得上Agent,还是先改流程?
读完能做的判断:结合场景、验证、成本和运维约束比较价值,不只看演示效果。
📑 本页目录(点开跳转)
16 · 企业落地与生产化
⏱ 阅读参考约 29 分钟 · 动手实践另计;可分段完成
🎯 一句话
Demo 到生产之间隔着五件事:选对场景、算清成本、架构解耦、组织接受、合规过关。 这一章全是从公开的生产实践里抠出来的数字和教训。
🗺️ 一、选场景:什么任务值得上 Agent
四条筛选标准
| 标准 | 好例子 | 坏例子 |
|---|---|---|
| 工作可并行 | 迁移数千个独立文件 | 单体强耦合的重构 |
| 规格明确 | 原代码库就是参考规格 | 「把产品做得更好用」 |
| 验证客观 ⭐ | 测试套件给出通过/失败 | 靠人主观评审 |
| 失败可恢复 | 单文件失败重跑即可 | 一步错全盘崩 |
🔑 最佳落地场景的共同点:工作队列能自动生成。 编译错误、测试失败、bug 单自动变成待办——人不再挑活儿,只管修「失败的模式」。
🎯 一个实用的筛选打分表
给候选场景打分(下面五项各 0–2 分,合计 0–10;≥6 只是本教程讨论起点,不是上线门槛,安全与合规缺口不能靠其他分数抵消):
算一算
□ 可并行度 0=完全串行 1=部分 2=天然可并行
□ 规格明确度 0=靠感觉 1=有文档 2=有可执行的规格(测试/原代码)
□ 验证客观性 0=人主观 1=半自动 2=全自动通过/失败
□ 失败可恢复 0=全盘崩 1=手动回滚 2=自动重试
□ 价值密度 0=省几分钟 1=省几小时 2=省几人周
💰 二、算清成本:真实世界的量级感
来自公开披露的真实数字(当量级参考,不是报价):
| 案例 | 规模 | 成本 |
|---|---|---|
| 百万行代码语言迁移 | 59 亿输入 token,两周 | 约 165,000 美元 |
| 16 个并行 Agent 写 C 编译器 | 2000 会话,10 万行代码 | 略低于 20,000 美元 |
| 三 Agent harness 做完整 App | 6 小时 | 约 200 美元(单 Agent 9 美元 但产物不可用) |
| 多 Agent 研究系统 | 相对单 Agent | 该案例多 Agent 约耗聊天交互 15× token;内部评估另报告相对单 Agent 的提升,两个参照不能混用 |
🧮 算账的三条口诀
结果对照
💡 最容易被低估的成本:人。 搭建、调试、维护 Agent 系统的工程师时间,往往远超 API 账单。 算 ROI 时把它算进去。
🏗️ 三、架构:大脑与双手解耦
- ↕ 状态外置 → harness 挂了也能恢复
- Harness(控制循环)
- ↕ 可整体替换升级
- Sandbox(执行环境)
- ↕ 容器从"宠物"变"牲畜":挂了就换
为什么要这么拆 —— 第 12 章的命题在架构层的回响: harness 会编码过时的假设,所以架构必须能容纳「尚未被发明的 harness」。
实际收益(公开数据):
| 收益 | 说明 |
|---|---|
| 会话状态外置 | harness 可重启恢复,状态错误不再复利 |
| 凭据不进沙箱 ⭐ | 降低沙箱直接读取凭据的机会;代理可执行的动作和数据出口仍须受限(第 15 章的硬边界) |
| 容器按需配置 | 首 token 延迟 p50 降约 60%、p95 降超 90% |
两个 Agent 的部署边界
想象一条文档处理流水线。Agent A 给文档分类,Agent B 汇总已入库的分类结果。升级 A 时,用户还能让 B 生成汇总吗?先看两条请求最终交给哪个进程(process)。进程是操作系统运行程序的实例,路由是把请求交给处理逻辑的入口,例如 /A 和 /B。
同进程 · 两条路由
调用方 → 同一进程〔/A 分类 · /B 汇总〕
- 部署与扩容:一起发布。增加一个进程副本时,两条路由一起复制。
- 状态:两条路由 → 进程外的 SQLite 文件。
- 凭据与消息:进程内代码可能访问同一份进程凭据;内部可直接调用或经同一队列传消息。
- 故障:停一次该进程,两个入口同时失去监听。
独立进程 · 两个运行单元
调用方 → 进程 A〔/A 分类〕
调用方 → 进程 B〔/B 汇总〕
- 部署与扩容:若版本、配置和部署流程允许,A 可以独立发布和增加副本。
- 状态:A 和 B → 同一个 SQLite 文件,仍是共同依赖。实际拆服务时可由各服务拥有自己的数据,通过接口或事件共享结果。
- 凭据与消息:可分别发放最小权限的身份与凭据;跨进程用 HTTP 接口或消息系统,按契约约定格式、超时和重试。
- 故障:只停 A,B 仍可处理自己能完成的请求。如果 B 同步等待 A,该操作也会受影响。
进程边界决定这次重启的影响范围。部署单元还包括版本、配置与发布流程,实验用两个进程模拟可独立启停的部分。第 13 章的发布/订阅和共享持久化可以同时用于两种拓扑。共享数据库、消息系统、网络入口或主机中断时,两条路由仍可能一起失效;这些共同故障在本实验中没有注入。
本机实验。把代码保存为 agent_topology.py,在 Python 3.9+ 的终端运行 python agent_topology.py。A、B 的业务逻辑简化为在 SQLite 写一条请求回执。每种拓扑依次在正常、停机、重启后三个阶段各发一次 A 和 B 请求,共六次,无重试。每次成功须同时收到 HTTP 200 和对应的追踪 ID。追踪 ID(trace ID)是用来把请求、响应和持久记录关联起来的标记,本例依次使用 A1、B1、A2、B2、A3、B3。
serve绑定本机环回地址127.0.0.1。端口填 0 由操作系统分配,子进程开始监听后才打印端口,父进程最多等 5 秒。request真实发出 HTTP 请求。建立连接时被拒绝或超时记为不可达;连接成功后的其他错误直接暴露。服务端先提交 SQLite 回执,再回传追踪 ID;snapshot每次从文件重读记录。experiment在第一次请求完成后停一次目标子进程,等它退出再探测原端口,最后启动替代进程并使用新分配的地址。请求、数据库等待和退出等待均有上限;finally回收子进程,临时目录随后清理。
import json
import sqlite3
import subprocess
import sys
from contextlib import closing
from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, HTTPServer
from pathlib import Path
from queue import Queue
from tempfile import TemporaryDirectory
from threading import Thread
def serve(routes, db_path):
class Handler(BaseHTTPRequestHandler):
def do_POST(self):
route = self.path.removeprefix("/")
if route not in routes:
self.send_error(404)
return
trace = self.headers["X-Trace-Id"]
with closing(sqlite3.connect(db_path, timeout=2)) as db:
with db:
db.execute("INSERT INTO receipts VALUES (?, ?)", (route, trace))
self.send_response(200)
self.send_header("X-Trace-Id", trace)
self.end_headers()
def log_message(self, *_args):
pass
with HTTPServer(("127.0.0.1", 0), Handler) as server:
print(server.server_port, flush=True)
server.serve_forever()
def start(routes, db_path, children):
process = subprocess.Popen(
[sys.executable, str(Path(__file__).resolve()), "--serve", routes, str(db_path)],
stdout=subprocess.PIPE,
text=True,
)
children.append(process)
ready = Queue()
# 读一行端口通知,主线程在规定时间内等候。
Thread(target=lambda: ready.put(process.stdout.readline()), daemon=True).start()
return process, int(ready.get(timeout=5))
def stop(process):
if process.poll() is None:
process.terminate()
try:
process.wait(timeout=3)
except subprocess.TimeoutExpired:
process.kill()
process.wait(timeout=3)
process.stdout.close()
def request(port, route, trace):
with closing(HTTPConnection("127.0.0.1", port, timeout=2)) as client:
try:
client.connect()
except (ConnectionRefusedError, TimeoutError):
return None
client.request("POST", "/" + route, headers={"X-Trace-Id": trace})
with client.getresponse() as response:
if response.status != 200 or response.getheader("X-Trace-Id") != trace:
raise RuntimeError("Unexpected response for " + trace)
return trace
def snapshot(db_path):
with closing(sqlite3.connect(db_path, timeout=2)) as db:
rows = db.execute("SELECT route, trace FROM receipts ORDER BY rowid").fetchall()
return {route: [trace for r, trace in rows if r == route] for route in ("A", "B")}
def experiment(mode, db_path):
with closing(sqlite3.connect(db_path, timeout=2)) as db:
db.execute("CREATE TABLE receipts(route TEXT, trace TEXT PRIMARY KEY)")
children = []
try:
process, a_port = start("AB" if mode == "shared" else "A", db_path, children)
b_port = a_port
if mode == "split":
_, b_port = start("B", db_path, children)
totals = {"A": 0, "B": 0}
for step, phase in enumerate(("before", "during", "after"), 1):
if phase == "during":
stop(process) # 共享模式只停 AB 一次,拆分模式只停 A。
if phase == "after":
_, a_port = start("AB" if mode == "shared" else "A", db_path, children)
if mode == "shared":
b_port = a_port
a = request(a_port, "A", f"A{step}")
b = request(b_port, "B", f"B{step}")
totals["A"] += int(a is not None)
totals["B"] += int(b is not None)
print(mode, phase, json.dumps({"A": a, "B": b, "rows": snapshot(db_path)}))
print(mode, "success/attempts", f"A={totals['A']}/3", f"B={totals['B']}/3")
finally:
for child in reversed(children):
stop(child)
if __name__ == "__main__":
if len(sys.argv) == 4 and sys.argv[1] == "--serve":
serve(sys.argv[2], Path(sys.argv[3]))
else:
with TemporaryDirectory(prefix="agent-topology-") as directory:
for mode in ("shared", "split"):
experiment(mode, Path(directory) / (mode + ".sqlite"))
怎么读结果。表中“—”表示这次连接不可达。每格先写收到的 B 追踪 ID,再写该阶段结束时数据库中 B 的回执列表。
| 拓扑 | 停前 | 停机中 | 重启后 |
|---|---|---|---|
| 同进程 | B1 / [B1] | — / [B1] | B3 / [B1, B3] |
| 独立进程 | B1 / [B1] | B2 / [B1, B2] | B3 / [B1, B2, B3] |
同进程模式下,停掉同时服务 A、B 的唯一进程后,两条路由各成功 2/3。独立进程模式下,只停 A,A 仍为 2/3,B 则为 3/3。两种模式的 A 回执都从 [A1] 保持为 [A1],重启后成为 [A1, A3]。独立进程的 B 在停机窗口实际回传了 B2,磁盘中的 B1 也仍在,说明这次请求成功与旧状态延续分别得到了观察。
回到文档例子:A 暂停分类时,B 可以汇总停机前已经提交的文档;刚来的文档还等着 A 分类。即使 B 返回成功,汇总的时效性也要用文档的入库时间另行判断。
练习。设想 B 每次汇总前必须同步请求 A,且 A 不可达时 B 返回失败。拆分进程后,重做同样的三次 B 探测,预测成功数、停机阶段会看到的 B 记录,以及什么情况仍会让两边一起失败。
查看练习答案
B 的进程在停机阶段仍运行,但这条汇总操作需要 A,因此只有停前和重启后成功,合计 2/3。如果约定成功后才写回执,停机阶段只能查到 B1。若两条路由都需要同一个数据库并且该库不可用,两边即使仍在监听也可能都无法完成请求。
证据范围。观察的是单机环回、顺序请求、受控进程重启及已提交的 SQLite 记录。真实容器、云发布、身份与凭据、消息系统故障、主机或网络故障和容量均未测试。生产验收见本章的部署证据分层。
机制参考:Azure 架构中心的微服务架构、服务数据所有权、Python 的 HTTPServer、subprocess 和 sqlite3。
🚀 四、生产运维三件套
| 问题 | 解法 |
|---|---|
| 状态错误会复利(小故障级联成大异常) | 从出错点恢复而非从头重跑;把工具失败明确告知 Agent 让它自适应 |
| 非确定性没法调试(同提示词每次路径不同) | 全量追踪 + 高层可观测性(只监控决策模式不看对话内容,兼顾隐私) |
| Agent 持续运行,没有发布窗口 | 彩虹部署:新旧版本并存,流量渐进切换 |
📊 必须监控的六个指标
操作步骤
- 每任务 token 消耗(分位数,不是平均值)⭐ 长尾是成本黑洞
- 任务完成率 / 中途放弃率
- 平均轮数(突然上升 = 模型在打转)
- 工具调用失败率(按工具分)
- 人工介入率(该降但降不下去 = 系统不成熟)
- 端到端延迟 p50/p95
💡 平均值与分位数一起看:Agent 的成本分布是重尾的—— 90% 的任务花 0.05 美元,10% 的任务花 5 美元,平均值 0.545 美元 用于总成本估算,p95 接近 5 美元 用于观察尾部;两者回答不同问题。
🏢 五、组织级实践参考
来自一个约 80% 合入代码由 AI 撰写、工程师季度发布量 8 倍的组织:
| 做法 | 说明 |
|---|---|
| 多 Agent 分域审查 | 每个审查 Agent 只盯一个窄面(安全/性能/风格)。分离防共享盲区 |
| 人工审查改为风险加权抽样 ⭐ | 不再全面把关,人力留给杠杆最高的节点。效果:收到实质性审查意见的 PR 从 16% → 54% |
| 权限分离 | 事故响应 Agent 能读日志、能发报告,不能自主部署修复(写代码的能力与部署的权限分开) |
| 把 Agent 当内部威胁对待 | 所有动作过 SIEM 审计,偏离预期即告警 |
| 影子模式 | 新 Agent 先只观察不生效,攒够信任再上 |
| 循环工程 ⭐ | 修产出代码的那个流程,不是逐个修产出 |
🔁 循环工程(值得单独理解)
结果对照
🔑 这是大规模 Agent 落地和小打小闹的分水岭。
⚖️ 六、合规与风险(To B 必须过的关)
| 议题 | 最低要求 |
|---|---|
| 数据去向 | 搞清供应商是否用你的数据训练、存哪个地域、存多久 |
| PII 脱敏 ⭐ | 发送前自动识别替换身份证/手机/银行卡。最常见事故是整条数据库记录拼进提示词 |
| 告知义务 | 按部署法域、行业和交互形式核对告知义务,并在产品中提供清楚说明 |
| 高风险决策 | 招聘、信贷、医疗等高风险场景应单独评估适用法律、人工监督与责任要求,由相应专业人员确认上线条件 |
| 可追溯 | 保留审计日志,能回答「这个决策是怎么来的」 |
| 内容责任 | 商用生成内容做相似度检查;代码生成注意开源许可证 |
⚠️ 这些不会让你的 Agent 更聪明,但会决定它能不能上线、能不能签单。
📋 七、上生产检查单
要点
【场景】
☐ 过了四条筛选标准,打分 ≥ 6
☐ 工作队列能自动生成
【架构】
☐ 做过降级测试,有数据证明复杂度必要(第 6 章)
☐ 多 Agent 的实测额外成本对得起价值(第 13 章)
☐ 状态外置,可从出错点恢复
【质量】
☐ 有评测套件,读过转录(第 14 章)
☐ 有环境层硬边界,做过威胁建模(第 15 章)
☐ 高危动作权限分离(能写≠能部署)
【运维】
☐ 六个指标都在监控,且看分位数
☐ 有降级方案(模型挂了怎么办)
☐ 部署不打断运行中的 Agent
【合规】
☐ 数据去向清楚,PII 已脱敏
☐ 用户知道在和 AI 交互
☐ 高风险决策有人工介入
【长期】
☐ 日历上有「模型升级后重审 harness」的提醒
☐ 定期问:我可以停止做什么?
🕳️ 八、五个常见坑
| 坑 | 症状 | 修 |
|---|---|---|
| 只算 API 成本 | ROI 算错,项目中途叫停 | 把工程师时间算进去 |
| 看平均 token 不看分位数 | 长尾任务偷偷烧钱 | 监控 p95/p99 |
| 逐个修产出 | 永远修不完 | 循环工程:修流程 |
| 人工审查想全覆盖 | 人力瓶颈,反而没人认真看 | 风险加权抽样 |
| 合规最后才想 | 做完了上不了线 | 立项时就把合规要求写进需求 |
📚 延伸阅读
本地故障与恢复验收
一句话带走:重启恢复的是持久化状态;审批仍是执行副作用的必要条件,超时也不能证明远端没有成功。
先分清教学夹具与真实部署
这里用脚本故障注入和业务 SQLite 子进程检查重试与恢复,不代表真实网络、图 checkpoint 或容器重建。执行范围与环境明细保留在本地故障恢复归档中。
示例分工:test_deployment.py 组织故障测试,deployment_lab.py 提供重试夹具。
先决定能不能重试
夹具最多3次调用,只重试429、503和 TimeoutError。401立即失败。每次仅记录request/operation/run ID、阶段、单次耗时、错误类型与重试次数,不保存异常中的原始私密文本。它是教学夹具,不是模型调用层补丁;真实适配器仍要处理 Retry-After、退避抖动、总截止时间与传输异常分类。副作用必须依赖下游幂等/查询契约;不能因为“可重试”就重复创建工单。
救援:远端已写入却丢了响应时,先按关联操作号查询、对账,再考虑重试。若下游既不能按操作号幂等也不能查询,停在人工对账,不能许诺恰好一次。
恢复不提供授权
“图恢复成功,但业务仍待审批”应拆开检查:checkpoint 是否载入,由框架记录证明;业务 run 若仍为 pending,执行仍应返回 approval_required、工单数为 0。载入状态不能替代授权。
救援:保留原DB,核对tenant、subject、fingerprint、审批时限和operation_id;不要通过删DB或补造审批来让恢复变绿。取消只能阻止下一次尝试,不能撤销已经开始的传输或已经提交的远端副作用。
部署证据分层
| 层次 | 验收时应保存的证据 |
|---|---|
| 单机教学契约 | 故障注入、拒绝与恢复前后的业务状态;注明模拟了哪一层 |
| 干净容器/挂载权限/镜像摘要 | 干净构建记录、镜像摘要、非root写入及重建后数据保留 |
| 云CI | 实际触发的运行记录、环境和结果;配置文件存在不算通过 |
| 协议互通/图checkpoint | 对应协议或框架的独立验收记录 |
| 真实身份/TLS/公网权限 | 真实身份、传输与权限负例的执行记录 |
| GPU容量/QPS/SLO | 固定请求分布与并发下的延迟、吞吐、错误率和资源记录 |
| 备份恢复/机器掉电/磁盘故障 | 备份还原、掉电及磁盘故障后的业务一致性记录 |
这组故障恢复记录只覆盖单机教学契约;容器、云 CI、真实身份与网络、生产容量及机器故障恢复仍未验收。先核对 Docker 与 daemon,再检查业务 DB、checkpoint 分别持久化、非 root 可写及重建后的状态;这些步骤须有实际记录才算完成。
机制参考:Docker Bind mounts、Docker Volumes、Python 3.12 sqlite3。
把发布内容与验证记录对应起来
16g · 模型版本清单与回滚预检 用实际文件清单与同题检索结果演示完整性核对及回滚预检。哈希不是签名;预检通过也没有启动模型或切换服务流量。
窗口告警先核对样本与数据质量
17h · 监控窗口与告警复核 在完整请求归并后选择窗口,分别检查失败率与成功请求P95。低样本与坏事件保留为无法判断,不据此自动扩容或回滚。
先把重试预算与调用分母说清楚
17i · 重试预算与熔断恢复 用合成时钟比较按次数重试和预算控制,核对下游调用放大、等待与熔断恢复。这是策略重放,不代表网络或生产容量验收。
✅ 检查点
- 选场景的四条标准是什么?共同点是什么?
- 算成本时最容易被低估的是什么?
- 「大脑与双手解耦」拆的是哪三样?为什么要拆?
- 为什么监控 token 要平均值与分位数一起看?
- 「循环工程」是什么意思?它为什么是分水岭?
- 「能写代码但不能部署」体现了什么原则?
- 人工审查为什么要改成"风险加权抽样"?效果如何?
👀 答案
- 可并行、规格明确、验证客观、失败可恢复。共同点:工作队列能自动生成(错误/失败自动变待办)。
- 人力成本——搭建、调试、维护 Agent 系统的工程师时间往往远超 API 账单。
- Session(事件日志)/ Harness(控制循环)/ Sandbox(执行环境)。因为 harness 编码的假设会过时,架构要能整体替换 harness 而不丢状态;且凭据不进沙箱可防注入窃取。
- Agent 成本分布是重尾的——90% 任务花 0.05 美元,10% 花 5 美元,平均值 0.545 美元 有助估算总账;p95 接近 5 美元 暴露尾部,两者一起报告。
- 修产出代码的那个流程,而不是逐个修产出。发现模式→更新规则→重跑队列,200 个问题一起消失。它是大规模落地和小打小闹的分水岭。
- 权限分离/最小权限——能力与权限解耦,被攻陷的 Agent 也造不成最大伤害。
- 想全面把关会造成人力瓶颈,结果反而没人认真看。抽样后人力集中在高杠杆节点,效果:收到实质性审查意见的 PR 从 16% 升到 54%。
本节回顾
⚡ 走神救援
回来时接住这四点
- 先选有明确价值、规格、验证与恢复路径的任务,评分表只是讨论工具。
- 总成本包括 token、缓存、工具、基础设施和人力;平均与尾部分位数一起看。
- 状态外置帮助恢复,权限与审批仍在每次业务执行时验证。
- 交付检查覆盖质量、受控发布、监控、回滚和适用的合规要求,未实跑项保留待验收。
下一节 👉 16b-框架这层皮.md