Stage 7 — 多 Agent 系统与稳定运作（Multi-Agent & Production）¶
⏱ 时间估算：2-4 周（约 15-30 小时）
💡 用语密度高（multi-agent / handoff / eval / observability / guardrails⋯）→ 翻
resources/glossary.md4 + 6。📋 本章组成：〔Multi-Agent · Production 化 是什么（先定位）+ 三层工程分工 + 何时用 multi-agent〕→ 学习目标 → 进入条件 → 必修阅读 → Harness Engineering（8 个核心元件含 Cost/Latency）→ 动手练习（含练习 6 Cost Optimization）→ Agent Benchmark Landscape：怎么看，不要只看排行榜 → 常用工具推荐 → 精选 Projects → 自我检查 🔑 关键名词：见
resources/glossary.md4 + 6（multi-agent / orchestration / handoff / eval / observability / harness（模型外围的执行与控制层））
最后一个阶段。你正从“我会做 agent”走向“我能让 agent 真的给人稳定用——多个 agent 协作、有 eval、有 observability、能部署到可用环境”。“Production 化” ≠ enterprise scale——只要 agent 能稳定产出 + 能让别人使用，就算进入这 stage 范围。
🎯 Multi-Agent · Production 化 是什么（先定位）¶
本 stage = 多 agent 怎么协作 + 把 agent 从 prototype 推到能稳定给人用的程度。三句话厘清范围：
- 不是只学 framework——Stage 4 已教 framework 怎么挑
- 不一定要 enterprise scale——只要 agent 能让别人用，就算 Production 化
- 核心是 harness engineering——8 个核心元件 + eval + observability + cost / latency 控制
跟前后 stage 的分工：
- Stage 4 = 单 agent framework 怎么挑、ReAct / Plan-Execute 等 pattern
- 本 stage = 多 agent 协作 + harness engineering（执行系统工程）+ 部署到可用环境 / observability / eval
三层工程分工：Prompt → Context → Harness¶
工程分工可以分成三层，对应 stack 的不同位置（不是 call 一次 vs 多次的差别）：
| 层级 | 概念 | 核心问题 | 关注单位 | 对应 stage |
|---|---|---|---|---|
| 1 | Prompt Engineering | 这一次要怎么问？ | 单次 LLM call | Stage 2 |
| 2 | Context Engineering | 这次该给模型哪些信息？ | 多次互动中的上下文 | Stage 6 |
| 3 | Harness Engineering （本 stage） |
整个流程怎么跑起来？ | 可执行的 LLM workflow / system | 本 stage |
白话差异： - Prompt = 设计一个好的问法，让模型这次回答准 - Context = 动态决定要放入哪些背景、记忆、文件、工具结果，让模型知道当前情境 - Harness = 把 prompt、context、tools、state、流程控制、错误处理串成一套真的能跑的系统
本 stage 三个核心问题：
- Multi-agent 协作 — debate / planner-executor / peer review / handoff / supervisor-worker pattern
- Harness Engineering — agent loop / tool registry（agent 可调用工具的清单 + 接口定义）/ context manager / safety / retry / telemetry / eval / cost（8 个核心元件、下面详述）
- Production 化 — eval harness / observability / cost & latency 优化 / 部署到可用环境
跟 Stage 5 的分工（避免混淆）：
| 跟谁比 | 那边讲什么 | 本 stage 讲什么 |
|---|---|---|
| Stage 5.5 Subagents | Claude Code 原生 subagent 机制（markdown-based、不写程序） | 通用 multi-agent framework（autogen / crewAI / langgraph、跨 vendor） |
| Stage 5.6 Claude Code source | Claude Code source 解剖（reference implementation case study） | Harness engineering 通则（不绑特定 vendor） |
⚠ 但你真的需要 multi-agent 吗？¶
Multi-agent 不是 default，而是任务真的需要时才上的设计。多数场景应先尝试 simple workflow 或 single agent；只有在任务天然可分解、需要平行探索、单一 context 不够、或需要明确角色分工时，multi-agent 才值得引入。硬上会付 3-10× token、debug 困难、context fragmentation（context 被切散在多个 agent、彼此看不到全貌）严重。
📌 决策框架的 canonical 在 Stage 4：完整的 Anthropic / Cognition 立场对照 + 4 个"该上 multi-agent"信号 + 每个信号对应的 pattern，见 Stage 4 §什么时候真的需要 multi-agent（设计阶段决策）。本节只做 production 前的最后回头检查——4 个信号一个都不在？ → single agent + 好 prompt + tool use 就够，别硬上 multi-agent。本 stage 的 harness engineering 部分（8 个元件 / eval / observability）即使你最后用 single agent 也都会用到——所以即使你决定不走 multi-agent，本 stage 仍是必修。
📌 学习目标¶
- 设计 multi-agent orchestration 模式（debate、planner-executor、peer review）
- 为 agent 架一套 evaluation harness
- 加上 observability（tracing、logging、cost tracking）
- 用 Anthropic SDK / OpenAI SDK 做 production deploy（进阶功能：streaming、prompt caching、batching）
- 把 agent deploy 到 production（Docker、serverless、monitoring）
🚪 进入条件¶
你应该已经： - 完成 Stage 4（用过至少一个 agent framework 跑 multi-agent demo） - 完成 Stage 5（懂 MCP / Skills / Plugins / Subagents 各自角色，并用 5.6 解剖过 harness 内部） - 完成 Stage 6（会基本 RAG，能讲出 memory pattern 差异） - 对 Docker / git / CI 基础熟悉（production deploy 会用到）
没到的话 → 补完前面几个 stage。本 stage 是“组合所有前面学到的东西 → 跑 production”，缺一块都会卡。
📚 必修阅读¶
- Anthropic — Building Effective Agents — 用 production 的角度再读一次
- Anthropic — Prompt Caching — 90% 成本下降的技巧
- Anthropic — Message Batches API — 异步 batch job
- anthropics/courses — Prompt Evaluations ⭐⭐⭐⭐⭐ ★ 21k+ — Anthropic 官方 5 course umbrella、module 4“Prompt Evaluations”对应本 stage eval / observability 部分。Jupyter notebook、教怎么系统化评估 prompt 跟 agent 行为。
- 任一 eval framework 的文件 — promptfoo 或 LangSmith 或 weave
- ai-boost/awesome-harness-engineering（★ 940）— agent harness 的工具 / pattern / eval / memory / MCP / observability 全集合
- ZhangHanDong/harness-engineering-from-cc-to-ai-coding（★ 1.3k+）— 从 Claude Code 源码学 harness 设计（中文）
🏗 Harness Engineering — production agent runtime 的工程设计 ⭐ 本 stage 核心概念¶
定位：模型外围的执行与控制层¶
要把 LLM 变成可用的 agent，通常会碰到三层工程问题。这三层对应的是不同工程位置，不是单纯用“一次 call”或“多次 call”来区分。
💡 Simon Willison 2025：“coding agent = LLM + harness”；harness = 所有不是 model 本身的代码。
💡 OpenAI 2026 也使用 "Harness Engineering" 这个说法（见 OpenAI Harness Engineering article、2026-02 发布）。
| 层级 | 工程的对象 | 在哪学 |
|---|---|---|
| 1. Prompt Engineering | 送进 LLM 的字符串（system prompt / few-shot / 格式） | Stage 2 |
| 2. Context Engineering | 窗口里装的信息（RAG / memory / tool defs / history 组装） | Stage 6 |
| 3. Harness Engineering （本节） |
模型外围的执行与控制层（loop / retry / sandbox / observability / 部署） | 本 stage |
怎么分辨自己在做哪一层？问：
- 我改的是字符串本身吗？→ Prompt engineering
- 我改的是塞进窗口的信息吗？→ Context engineering
- 我改的是调用模型的外围程序吗？→ Harness engineering
→ 三层正交：1 次 call 的 RAG app 也在做 context engineering（重点是怎么组窗口）；50 次 call 但没做 retrieval 的 chatbot，仍然只是在做 prompt engineering。
Harness 的 8 个核心元件¶
Harness Engineering（Agent 执行系统设计）= 把 LLM、tools、memory、state、workflow control、错误处理、eval、observability 与 deployment 串成一套可执行、可观测、可维护的 agent 系统。
→ 所有不属于 model weights、也不只是 prompt string 本身的工程元件都算 harness 范围。一个 production-grade agent runtime 包含这 8 个核心元件（前 6 个是 runtime 内建、第 7 个 eval 是外挂工具、第 8 个 cost / latency 是跨层议题）：
| 元件 | 做什么 | 对应本 stage 练习 |
|---|---|---|
| Agent loop | “LLM → tool → result → LLM”循环、稳定处理多轮 | 练习 1 multi-agent 辩论 |
| Tool registry | 动态 tool dispatch、permission gate、sandboxing | （在每个 framework / SDK 都有） |
| Context manager | message history 管理、context window 控制、auto-compact | Stage 6 + 本 stage 练习 4 SDK |
| Safety layer | permission prompts、sandboxed exec、destructive op 拦截 | （Claude Code 内建、SDK 可自定义） |
| Retry / recovery | tool fail 怎么处理（exception vs LLM 自己看 error 反思） | 练习 4 SDK 进阶 |
| Telemetry / Observability | metrics、logging、token counting、trace export | 练习 3 Observability |
| Eval harness | regression test、quality gate、A/B test | 练习 2 Eval |
| Cost / Latency optimization ⭐ 2024-2026 必修 | prompt caching、model routing、thinking budget、batching、semantic cache | 练习 6 Cost optimization（新加） |
Framework vs Harness 关键差别： - Framework（Stage 4）规范 API — 你调用的接口长什么样 - Harness（本节）规范 runtime — 怎么跑、怎么 recovery、怎么观测
参考实现¶
想看 production-grade harness 长什么样？两个 reference：
- Claude Code 整个 runtime — 是 reference harness 实现。读 source 练习见 Stage 5.6（clone
claude-agent-sdk-python解剖 main loop + 上表前 6 个 runtime 元件位置；第 7 个 Eval harness 是外挂、第 8 个 Cost / Latency 是 cross-cutting、见下方深入段） anthropics/claude-agent-sdk-pythonsource — 上面练习用的具体 repo
→ 本 stage 剩下的 6 个练习（multi-agent / eval / observability / SDK / deploy / cost）每个都是 harness 的一个面向。学完整 stage = 拼出完整的 harness engineering mental model。
第 8 个核心元件深入 — Cost / Latency Optimization（2024-2026 Production 化必修）¶
Production agent 跑久了，cost / latency 两条线会吃掉你大半预算与用户体验。2024-2026 前沿模型都把这当 first-class API feature——会用 = 省 50-90% cost / latency。
| 技巧 | 怎么省 | 2026 状态 |
|---|---|---|
| Prompt caching | 重复 prefix（system prompt、long context）一次计费、后续 cache hit 折扣 ~90% | Anthropic / OpenAI / Gemini 全支持、自动或手动标记 |
| Model routing / cascade | 简单 query → 小 model、难 query → frontier model | RouteLLM / OpenRouter production 内建 |
| Thinking budget | reasoning model 可控 thinking token 上限、trade latency / quality | Claude / Gemini API 参数、o-series 默认高 |
| Speculative decoding | 小 model 预测 N token、大 model 一次验证、单 model 速度 ×2-3 | vLLM / TGI 内建、推理层自动 |
| Batching | 多 query 并行处理、GPU 利用率高 | vLLM、production inference layer |
| Semantic caching | 相似 query 共享回答（不只 exact match） | GPTCache / Helicone 内建 |
Track A 怎么用（用 CLI agent 的人）：
- 在 Claude Code / Cursor 设置 prompt caching，daily session 省 50-90% cost
- 用 RouteLLM / OpenRouter 动态切换 model（简单问题用 Haiku / Flash，困难问题用 Opus / Pro）
- Claude API 用 thinking_budget 参数控 reasoning model 的 token 上限
Track B 怎么 build（自己写 agent 的人）： - 自架 cascade router，把 query embedding → classifier → model 对应起来 - 在 agent loop 内监控 token cost，超 budget 自动降级 - 在部署到可用环境时整合 semantic cache 层 - Helicone / langfuse 等 observability 平台都已内建这些能力，不用自己写
🛠 动手练习（基础 illustrative 练习）¶
练习 1：Multi-Agent 辩论¶
两个 agent 辩论一个题目（例如“该用 Python 还是 Rust 写 backend”），第三个 agent 当裁判。观察辩论收敛或分歧的 pattern。
练习 2：Eval¶
替你前面的 agent 写一份 eval，跑 N 次量成功率。把“我用眼睛看一下”的习惯换掉。
练习 3：Observability¶
把 LangSmith、Helicone、或 weave 接上一个 agent，看完整 trace。理解“没 observability 的 agent debug = 黑盒”。
练习 4：SDK 进阶¶
在同一次调用里用 streaming + prompt caching + tool use。看成本怎么降下来。
练习 5：Deploy¶
把一个 agent 包进 Docker，deploy 到云端（任何 provider 都行）。学会把 prototype 变成可以给别人跑的东西。
练习 6：Cost Optimization（新加）⭐¶
量你前面任一个练习 agent 的 token cost、加上 prompt caching、再量一次。观察 cache hit rate 跟 cost 下降的对应关系。Bonus：接 RouteLLM 或 OpenRouter、做 cascade routing（简单 query → Haiku / 难 query → Opus），量平均 cost。
📊 Agent Benchmark Landscape：怎么看，不要只看排行榜 + ⚠ Reward-Hacking 警告¶
挑 model / build agent 之前，你会想看 benchmark 数字——但 2026-04 UC Berkeley 发现 8 个主流 agent benchmark 全部可被 reward-hack 到 ~100%。下面是 2026 leaderboard 现况 + 怎么看不被骗。
主流 Agent Benchmark 2026-05 SOTA¶
| Benchmark | 领域 | 2026-05 SOTA | 领先 Model |
|---|---|---|---|
| SWE-bench Verified | 软工 / code agent | 87.6% | Claude Opus 4.7 |
| Terminal-Bench | terminal 任务 | 领先 | Claude Opus 4.5 / 4.7 |
| GAIA | general assistant | 74.6% | Claude Sonnet 4.5（Princeton HAL） |
| WebArena | web 导航 | 68.7% | Claude Mythos Preview |
| OSWorld | OS-level 桌面控制 | 76.26%（SOTA、superhuman vs human 72.36%） | OpenAI CUA 38%、多数 frontier 仍卡 50% 以下 |
| τ-bench | tool use 多轮对话 | （较难 hack） | Anthropic / OpenAI 领先 |
| RE-bench | research engineering | （较难 hack、接近人类 baseline） | Frontier model |
→ 详细排行 + 即时更新：Agent Benchmark Leaderboard 2026、Rapid Claw AI Agent Framework Scorecard 2026
⚠ Berkeley 2026-04 Reward-Hacking 警告¶
UC Berkeley RDI 2026-04-12 报告：用 automated scanning agent 系统性 audit 8 个主流 benchmark（SWE-bench / WebArena / OSWorld / GAIA / Terminal-Bench / FieldWorkArena / CAR-bench 等）、每个都能 reward-hack 到接近 100%、agent 一个 task 都不用真正解。
意思：leaderboard 上“Claude 87.6% / GPT 85.0%”这种数字、可能其中 X% 是 hack 出来的、不是真的解 task。
怎么看 benchmark 不被骗¶
| 看数字方式 | 推荐 |
|---|---|
| 只看 leaderboard top | ❌ 上面 8 个都被证实可 hack |
| 看 task-level success rate breakdown | ✅ 多数 hack 集中少数 task |
| 跑你自己的 hold-out test set | ✅✅ 最可靠、production agent 必做 |
| 看 trajectory / log 是否真的解 task | ✅ 区分 reward hacking vs genuine solve |
| 看多个 benchmark + 自己 use case | ✅ 不依赖单一指标 |
哪些 benchmark 较难 hack（2026-05）： - τ-bench — 多轮对话 + tool use、reward function 较密集 - RE-bench — research engineering 真实任务 - 你自己的 production eval set ⭐ 永远是最可靠的
💡 production agent 的 eval 纪律： - 不要把外部 benchmark 数字当 ground truth、它告诉你“上限”不是“真实表现” - 你自己的 eval set（内部 hold-out test）才是上线决策的依据 - 每次 model upgrade → 跑内部 eval set 验证、不只看厂商公布的 benchmark 提升 - 接 langfuse / promptfoo 把 eval 自动化、每次 deploy 都跑
🎯 常用 Multi-Agent / Production 工具推荐（按用途分类）¶
不知道从哪挑工具？下面是 2025-2026 业界常用搭配——挑入口看“场景”、想深入点链接看 repo：
| 场景 | 推荐工具 | 为什么 |
|---|---|---|
| 第一次写 multi-agent（最快上手） | crewAI | role-based、几行 code 跑起来、production pattern 直接 |
| 想要 group debate / brainstorm pattern | AutoGen | GroupChat 自由辩论、Microsoft 出品 |
| production 要 audit trail / checkpoint / human-in-loop | LangGraph | state machine、控制最完整 |
| eval 标准化（CI / regression 必装） | promptfoo ⭐ | YAML config、跨模型比较、★ 20k+ |
| eval + observability 同平台 | langfuse ⭐ | OSS、tracing + eval + prompt mgmt、★ 26k+ |
| 不改程序、快速 instrumentation | Helicone | proxy 中介、不绑 framework |
| 全 stack 在 LangChain | LangSmith（商业） | LangChain 官方 observability |
| 打造 Claude agent（programmatic） | claude-agent-sdk-python ⭐ | Anthropic 官方 agent SDK、跟 Claude Code 同 runtime |
| Deploy agent 成 API service | BentoML | 最完整、Docker + serving |
| 自架开源 LLM（取代付费 API） | vLLM | 高吞吐量、★ 79k+ |
| Fine-tune 开源 LLM | LLaMA-Factory | 100+ 模型统一 SFT/DPO/PPO/GRPO、Web UI 零 code、中文社群最广、★ 70k+ |
建议入手顺序： 1. 第一个 multi-agent：crewAI（role-based、最简单） 2. 加 eval：promptfoo（YAML、CI 整合） 3. 加 observability：langfuse（OSS、完整） 4. Production 升级：换 LangGraph（control 强）+ BentoML（deploy） 5. 进阶：自架 LLM 接 vLLM、fine-tune 用 LLaMA-Factory
🎯 精选 Projects（范本 / SDK / 工具 collection）¶
按用途分类、22 个项目一张表搞定。挑入口看“适合谁”、想深入点链接看 repo。
| 分类 | Project | ⭐ | 适合谁 | 为什么推荐 / 备注 |
|---|---|---|---|---|
| Multi-Agent Orchestration | microsoft/autogen | ⭐⭐⭐⭐⭐ | 想要 GroupChat 自由 debate pattern | Stage 4 介绍过、production 场景再回头看 multi-agent 辩论 / brainstorming 模式 |
| crewAIInc/crewAI | ⭐⭐⭐⭐⭐ | 想要 role-based 流水线 | 角色式 multi-agent（research → writer → reviewer），最简单 production pattern | |
| langchain-ai/langgraph | ⭐⭐⭐⭐⭐ | 需要 audit trail / checkpoint / human-in-the-loop | state machine 路线、production 控制最强 | |
| Eval Frameworks | promptfoo ⭐ | ⭐⭐⭐⭐⭐ | 把 eval 流程标准化、CI 整合 | YAML config、跨模型比较。★ 20k+、MIT |
| lm-evaluation-harness | ⭐⭐⭐⭐ | 学术 benchmark 主张（MMLU / HellaSwag / GSM8K） | 学术等级。★ 12k+、MIT | |
| openai/evals | ⭐⭐⭐⭐ | OpenAI 专属 eval / 想回馈上游 | ★ 18k+ | |
| Observability | langfuse ⭐ | ⭐⭐⭐⭐⭐ | 自架 production observability | OSS LangSmith 替代、traces + sessions + evals + prompt mgmt。★ 26k+、MIT |
| LangSmith（商业） | ⭐⭐⭐⭐ | 全 stack 在 LangChain / LangGraph 上 | LangChain 官方、只有 hosted 版 | |
| Helicone | ⭐⭐⭐⭐ | 不想改程序、快速上 instrumentation | proxy 中介、顺便拿到 logging + caching。★ 5.7k+、Apache 2.0 | |
| weave (W&B) | ⭐⭐⭐⭐ | 团队已在用 W&B 做 ML 实验追踪 | W&B tracing + eval、跟 wandb 整合 | |
| Anthropic SDK 进阶 | anthropic-sdk-python | ⭐⭐⭐⭐⭐ | 直接基于 Claude API 做应用 | 官方 Python SDK：streaming / async / tool use / prompt caching / batches / files |
| anthropic-sdk-typescript | ⭐⭐⭐⭐ | TypeScript / Node / web app | Python SDK 的 TS 版 | |
| claude-agent-sdk-python ⭐ | ⭐⭐⭐⭐⭐ | 打造 Claude-based agent 而非只 API | 内建 tool use loop / file access / sandbox / subagent 编排；跟 Claude Code 同 runtime、想看内部运作直接读 source。★ 6.9k+、MIT | |
| claude-agent-sdk-typescript | ⭐⭐⭐⭐ | Node / web app 环境 Claude agent | Claude Agent SDK TS 版。★ 1.4k+ | |
| Anthropic Cookbook（进阶） | ⭐⭐⭐⭐ | 想看官方进阶 SDK pattern | 特别是 prompt_caching.ipynb / tool_use/ / multimodal/ 三个 notebook |
|
| Deployment | BentoML | ⭐⭐⭐⭐ | 把 agent 包成 production API service | Docker + serving framework。★ 8k+、Apache 2.0 |
| LangServe | ⭐⭐⭐⭐ | LangChain agent 快速 deploy | 底层 FastAPI | |
| vLLM | ⭐⭐⭐⭐ | 自架开源 LLM 取代付费 API | 高吞吐量 LLM serving、Llama / Qwen 等。★ 79k+、Apache 2.0 | |
| 中文 deploy / fine-tune | datawhalechina/self-llm | ⭐⭐⭐⭐ | 中文团队要自架开源 LLM | training-to-deployment 完整中文指南、Qwen / Llama / GLM / 多模态。★ 30k+、Apache 2.0 |
| hiyouga/LLaMA-Factory | ⭐⭐⭐⭐⭐ | 要 fine-tune 开源 LLM（不只 prompt eng） | 100+ 模型统一 SFT/DPO/PPO/GRPO、Web UI 零 code、中文社群最广。★ 70k+、Apache 2.0 | |
| Multi-Agent 案例研究 | geekan/MetaGPT | ⭐⭐⭐⭐⭐ | 想看角色分工 + artifact 交接 pattern | SOP-based PM / Architect / Engineer multi-agent team、PRD → 设计 → code 一路产出。★ 67k+、MIT |
| OpenBMB/ChatDev | ⭐⭐⭐⭐ | 想看 agent debate / peer-review pattern | 对话式软件开发、agents 在 design / code / test 互相辩论。★ 33k+、Apache 2.0、有 zh README | |
| princeton-nlp/SWE-agent | ⭐⭐⭐⭐ | 理解为什么 tool 设计 > prompt tuning | Agent-Computer Interface (ACI) 设计思路、Princeton paper-backed、SWE-Bench 领先方法。★ 19k+、MIT |
🌳 Claude 原生 subagent 机制（不用 framework 也能 multi-agent）见 Stage 5.5。本 stage 重 framework / production；Stage 5.5 重 markdown-based subagent 编排。
✅ Stage 7 之后的自我检查¶
你能不能： - [ ] 设计一个 multi-agent 系统，协作协定讲得清楚 - [ ] 在 CI 跑自动 eval pipeline - [ ] 把 observability（tracing）接到 production agent - [ ] 在真实 workload 上量测 prompt caching 前后的成本差异 - [ ] 把 agent deploy 到云端（任何 provider）
如果都可以 → 先进 Stage 7.5 — 进阶 Agentic 概念地图（1 周、不写 code、建立 frontier 概念地图、定位业界还在讨论哪些进阶概念），再进 Stage 8 — Agent Interfaces（两 track 共用 hub）学 agent 怎么跟非 API 世界互动（Computer Use / Browser Use / Sandbox）。或挑一个特化分支、或回头来贡献这份 repo。
💡 接下来¶
你已经有基础能力了。接下来 6-12 个月应该专注在： 1. 挑一个 production 系统 从 prototype 推到 production 2. 回馈上游（LangGraph、AutoGen、MCP servers、Anthropic cookbook） 3. 读论文——agent 研究进展很快 4. 做出看得到的东西——开源一个真的工具，不要再写教学了