AI Agent Handbook

在线阅读 · theaiera.top/books/ai-agent-handbook

本书由阿里云官方开源，遵循 Apache License 2.0。

原创来源声明：本书全文整理自阿里云官方开源仓库 aliyun/ai-agent-handbook（Apache License 2.0），内容为原文转载，未作修改。谨以此项目献给参与 AI 建设的所有同行者。

关于本书

按照 Agent 的架构、构建、运行、治理和调优应用生命周期，总结了我们在企业级 Agent 落地过程中的实践经验和体会。本书主要面向企业级 Agent 构建与落地场景：既适合关注 Agent 开发的工程人员，也适合用于企业内部的技术选型、架构评审、项目立项和跨团队共识建设。

完整阅读后，你将能够：

• 从业务目标、任务确定性和风险出发，选择最低充分的 Agent 架构；
• 理解 Model 与 Harness 的责任边界，不把所有问题都归因于模型能力；
• 设计可持续推进、可中断恢复、可验证完成的 Agent 任务系统；
• 为 Agent 建立执行环境、状态、流量、权限、观测与成本治理底座；
• 用 Trace、Trajectory、黄金数据集和评估实验形成持续改进的数据飞轮；
• 将方法映射到研发效能、设计、运维、企业 IT、客户运营等实际场景。

版权

原书版权归阿里云及其贡献者所有，遵循 Apache License 2.0 开源许可。本站按许可转载全文。

目录

前言

• 前言：智以致用——从造出智能，到用好智能

调研

• 2026 Agent 开发者调研报告

篇导读

• 篇导读合集（架构/构建/运行/治理/调优/实践）

架构篇

• 第 1 章　AI 原生应用的新阶段
• 第 2 章　Agentic Application 参考架构

构建篇

• 第 3 章 范式：Harness 的主流构建方式和责任边界
• 第 4 章 任务：编排、长程推进与协作流转
• 第 5 章 信息：上下文、状态与可复用能力资产
• 第 6 章 行动：受控执行、验证反馈与交付准备

运行篇

• 第 7 章 Agent 运行时与沙箱
• 第 8 章 Agent 状态存储与语义资产
• 第 9 章 AI 网关与统一流量治理
• 第 10 章 Agent 异步任务与自动化流程
• 第 11章 Multi-Agent 协作与编排
• 第 12 章 Agent 分布式通信

治理篇

• 第 13 章　Agent 的可观测性
• 第 14 章　Agent 安全
• 第 15 章　AI 资产的发现与管理
• 第 16 章　Agent 行为生成与质量验证

调优篇

• 第 17 章　模型调优
• 第 18 章　Agent 调优总览
• 第 19 章　Agent 轨迹数据
• 第 20 章　Agent 运行时数据处理
• 第 21 章　Agent 黄金数据集
• 第 22 章　Agent 优化：Badcase
• 第 23 章　受控自进化
• 第 24 章　Agent 边缘运行时与全球优化

实践篇 · 研发效能

• ABACI 内核补丁定向测试与缺陷检测智能体
• Kitta：领域专用 Code Review Agent
• PatchPilot Agents：让内核补丁交付成为可编排、可验证的工程闭环
• 从报警到自动修复，PolarDB-X 的 Loop 工程实践
• 从编码提效到端到端交付，云通信的人机协作实践
• 从评测驱动到端到端交付：AI Agent 安全产品研发提效实践
• 多 Agent 组成研发小队：AI 研发如何从写代码走向端到端交付

实践篇 · 设计工程

• GenUI：让 Agent 从给出答案走向交付结果
• Vibe Designing：意图驱动的AI设计范式进化

实践篇 · 运维、安全与企业 IT

• 吉利汽车智能运维的落地实践
• 塔斯汀万店连锁的智能运维闭环实践
• 畅捷通的可观测与智能运维实践

实践篇 · 客户、销售与运营

• MiniMax 构建海量长周期记忆数据底座的实践
• 会计师事务所信永中和的办公提效探索
• 哔哩哔哩构建全域内容洞察的实践
• 运营分析 Data Agent 实践

实践篇 · GOAI Agent Infra

• 第 29 章 GOAI Agent Infra 赛道：多 Agent 协同的前沿实践探索

总结与展望

• 第 30 章 从 Agentic Application 到 Agentic OS

---

篇导读合集

以下六篇导读为各篇章的引言，原文收录于此。

架构篇导读

过去一年，AI 原生应用的构建起点发生了位移。模型不再只是被应用调用的生成引擎，而是能够维持任务状态、分解目标、调用工具并根据执行反馈调整行为的执行主体。Codex、Claude Code、Qoder 等 Coding Agent 率先在软件研发中验证了这种形态：它们不只给出代码建议，还读取代码仓库、维护任务计划、修改文件、运行终端与测试，并在长时间任务中持续接受人的引导。

模型获得更大的任务自主权，并不意味着模型本身即构成 Agent。任务越长、工具越多、环境影响越大，模型之外的工程系统就越关键。上下文组织、任务状态、工具控制、环境隔离、失败恢复、结果评估与风险约束共同构成 Harness，Agent 由 Model 与 Harness 共同构成。这一判断改变了架构对象：企业需要设计的不再是一次模型调用，而是一个跨越认知、状态、执行、控制与持续改进的完整系统。

架构篇处理生命周期五阶段中的第一个阶段。它给出判断与边界：采用什么应用形态、授予多大自主权、哪些能力自建、哪些由共享平台提供、什么结果构成完成。这些边界若推迟到构建阶段再确定，后续运行、治理与调优将出现混乱。

对应章节	主线	描述
第 1 章	应用构建范式	应用形态如何演进、Agentic Application 的定义与边界、企业成熟度如何判定。
第 2 章	建立架构	系统由什么组成、组件在哪里运行由谁负责、如何从决策走向运行并被改进。

第 1 章解决对象界定。应用形态不是一条简单的替代链，Workflow 与 Agent 将长期共存；Single-Agent 沿时间跨度扩展为 Long-Horizon Agent，沿协作结构扩展为 Multi-Agent，两者可独立采用，也可组合使用，但都不是所有应用必经的升级阶段。成熟度同样不由产品名称决定，判据是自主性能否与任务风险相匹配，并选择成本与风险可接受的最低充分架构。

第 2 章解决结构落位。三个视图互不推导：组件视图避免能力遗漏，平台视图避免责任混乱，生命周期视图避免把一次演示误判为可运营系统。同一个 State Store，在组件视图中是任务事实的持久化能力，在平台视图中属于数据与资源面，在生命周期视图中则是运行阶段产生、调优阶段被反复读取的证据来源。讨论任何能力时先确认其所处视图，是这套参考架构可用的前提。

两章构成前后依赖，建议顺序阅读。本篇需要带走的判断有两条：形态与成熟度不由产品名称决定；架构的目的不是把系统做大，而是为每一项被授予的自主性建立对等的执行、观测、安全与评估能力。

构建篇导读

上一篇确立了架构对象与责任划分，本篇进入生命周期的第二个阶段。构建阶段的核心工作有两项：决定 Harness 由谁实现，以及把模型的离散判断组织为可持续推进、可中断恢复、可验证结束的任务过程。

Coding Agent 为这项工作提供了一个可观察的工程样本。在代码、文件与测试构成的环境中，模型可以通过工具持续行动，系统也可以用编译、测试和文件差异验证结果。它说明模型能力只有经过上下文组织、任务循环、状态管理、工具执行、权限控制与结果验证，才可能稳定转化为任务结果。但编码场景不能替代全部企业任务：审批、交易、客服与运营具有不同的业务状态、权限边界与成功标准，企业应复用其中可泛化的 Harness 机制，而非照搬一套 Coding Agent 流程。

构建是本书五个持续责任域中的 Agent 构建与编排域。这里的构建不是一次性开发活动，被构建出的编排逻辑会在每次任务运行时持续工作，其质量直接决定运行篇要承载什么、治理篇要观测什么、调优篇能改什么。同时，本篇只描述并绑定可用能力，物理执行、状态落盘与环境隔离由运行篇承担，这条边界贯穿四章。

对应章节	主线	构建对象或问题	主要机制
第 3 章	范式：Harness 由谁实现	定制深度、数据边界、运行责任与交付方式的取舍。	四类构建入口：高代码框架、产品化 Harness（Coding Agent CLI / SDK 与工作区助手）、Managed Agents、Agent 云产品；Agent Platform 的规模化交付与多源纳管。
第 4 章	工程契约：任务	任务如何推进、中断如何恢复、完成如何判定。	Agent Loop 与任务状态机、Planning 与阶段门禁、Subagent 受控委派、异步续行、由证据决定完成。
第 5 章	工程契约：信息	有限模型窗口与持续增长的任务世界之间如何取舍。	Context 构建管线与 Manifest、压缩与卸载、Session / Task State / Workspace 的区分、Memory 与 Knowledge 的分工、Skill 的渐进式披露。
第 6 章	工程契约：行动	行动意图如何被授权、执行与验证。	统一 Action Plane、Function Calling / MCP / A2A 的职责分层、Environment Contract 与 Sandbox、Permission 与 HITL、Trace 与 Evaluation 闭环。

第一条主线是构建入口的选择。当前存在四类主要起点：高代码框架提供代码级控制；产品化 Harness 以 Coding Agent CLI、SDK 与工作区助手的形式复用成熟能力；Managed Agents 将约定范围内的 Harness 与运行基础服务化；Agent 云产品提供原生创建与共享资源入口。四类入口不构成成熟度阶梯，也不互斥，选择依据是任务结构、定制深度、数据边界、环境影响、团队能力与交付方式。当多团队、多来源 Agent 同时存在时，Agent Platform 负责统一创建、接入、规模化交付、运行、治理、协作、观测与优化，它不是第五类入口。

第二条主线把 Harness 拆为任务、信息、行动三类工程契约。任务契约解决推进与终止：Agent Loop 以 Prepare、Model、Act、Observe、Verify 推进，显式状态与多维预算提供确定性边界，完成由环境证据判定而非由模型停止判定。信息契约解决模型此刻应当看见什么：Context Builder 按身份、可信度、相关性与 Token 预算动态编译输入，压缩与卸载控制窗口增长，但任何关键事实必须先落入权威状态；Session 表达交互连续性，Task 表达可验收目标，Workspace 承载模型窗口之外的工作记忆。行动契约解决意图如何成为受控的环境事实：统一 Action Plane 按 Schema、身份、Policy、审批、执行、Observation 与 Trace 推进，Environment Contract 与 Sandbox 提供文件、进程、网络与 Secret 的真实隔离，Trace 与 Evaluation 把真实失败转化为有针对性的 Harness 改动。

三类契约存在内在顺序：任务定义流转，信息定义每一步的可见范围，行动定义副作用与验收依据。第 4 至 6 章共用同一贯穿案例，即生产服务漏洞修复与变更发布 Agent，跨章跟读同一任务比分别阅读更容易看清三类契约的咬合关系。

本篇构建出的 Agent 随后需要进入真实的执行环境、状态存储与流量通道，那是第三篇运行的主题。

运行篇导读

Agent 构建完，提供对外服务的时候，需要从稳定性、安全、性能、成本等角度去设计运行环境。

一个在开发环境里跑通的 Agent，与一个对外提供规模化服务的 Agent，要回答的问题并不相同。前者只需在一次会话内把逻辑走通；后者要回答它在什么环境里执行、状态存在哪里、流量怎么进出、任务跨越请求与进程之后如何持久化、多个 Agent 同时工作时如何协调与通信。

这些问题在开发阶段同样存在，区别在于规模掩盖了它们的代价：状态没有外置，单人调试时只是重来一次，生产并发下会变成任务丢失、重复执行与无法归因；一个人可访问的 Agent，与面向成千上万用户提供服务的 Agent，业务需求与工程复杂度完全不是一个量级。运行篇处理的正是企业运行环境和用户规模带来的复杂度，它在稳定性、安全、性能与成本四个维度上同时决定系统能否可靠运行。

运行篇的六章沿两条主线展开。第一条主线是运行的地基，解决 Agent 如何稳定运行；第二条主线是运行的秩序，解决多个 Agent 如何协同运行。

主线	对应章节	运行对象或问题	主要机制
运行的地基： Agent 稳定运行	第 7 章	执行环境与运行时	沙箱、Agent Runtime、环境生命周期、把工作空间纳入生产平台
	第 8 章	任务事实与语义资产的落地	Event Log、Checkpoint、工作区快照、Artifact、长期记忆、RAG 与本体
	第 9 章	流量的进出与治理	AI 网关的 LLM、MCP、Agent 三种治理语义；身份、权限、预算、审计与审批
运行的秩序：多个 Agent 协同运行	第 10 章	长时与异步任务	同步与异步的边界、完成语义的分层模型、定时任务与工作流
	第 11 章	多 Agent 团队协作与编排	异构接入、团队组织拓扑、任务分派与结果聚合、编排层与执行系统的职责边界
	第 12 章	跨 Agent 的分布式通信	能力面、协作面、内构面、人机面的选型地图；消息治理

第一条主线处理执行条件本身。第 7 章把工具调用扩展为可编程工作空间，让 Agent 在同一空间内持续工作，并为并行探索提供环境；第 8 章解决状态外置之后的承载问题，运行时状态、工作区与产物、记忆与知识、业务语义与治理四类对象具有不同的一致性要求，需要匹配的物理承载与统一的状态契约；第 9 章把流量入口收敛为统一治理点，区分 LLM、MCP 与 Agent 三种治理语义，避免把模型路由、工具协议代理与任务入口混为一层。

第二条主线处理协同秩序。第 10 章界定同步与异步的边界，并给出任务完成语义的分层模型，避免把进程结束当成任务完成；第 11 章讨论异构 Agent 如何进入同一个团队，以及编排层与执行系统的职责如何划分；第 12 章按能力面、协作面、内构面与人机面给出通信选型地图，把协议选择还原为面向交互语义的判断。

两条主线是递进关系：没有稳定运行的单个 Agent，多 Agent 协同只会放大不确定性。第 7 章的执行环境与第 8 章的状态存储是理解后续各章的共同基础，建议先读。若当前任务是把一个 Agent 接入生产并跑稳，重点在第一条主线；若已有稳定运行的 Agent，正在向异步、多 Agent 与跨系统形态扩展，重点在第二条主线。

治理篇导读

Agent 实际执行了什么，我们看不看得见；它会不会越过授权边界，或者被外部内容操纵；它依赖的 Prompt、Skill、MCP、Agent 散落在各处，有没有统一管理；它的行为在上线之前，能不能先验证一遍。治理篇让 Agent 的运行实现可观测、行为有边界、依赖的资产可管理、上线前的行为可验证，让一个自主运行的系统变得可信。

治理不是给运行额外附加约束的环节，而是让一个已经在运行的系统变得可信：可观测、有边界、资产可管理、行为可验证。治理沉淀的观测指标、审计证据、资产记录与验证结论，同时构成调优篇判断问题所依赖的可信事实。缺少这一层，改进只能依靠推测。

对应章节	维度	治理对象或问题	主要机制
第 13 章	让运行可见	Agent 实际执行了什么、问题出在哪一步、成本与异常如何归因。	指标、日志、Trace 与事件；任务、Agent 执行、基础设施三层观测对象；审计。
第 14 章	让行为有边界	Agent 既是被攻击的对象，也是自主行动的主体。	全栈纵深防护，配合身份鉴权、逐次校验、高危二次授权与数据出域阻断。
第 15 章	让资产可管理	Prompt、Skill、MCP 与 Agent 散落各处，版本、使用与变更影响不清。	统一的注册、版本、发现与发布；稳态 Agent 的声明式依赖与动态 Agent 的按任务发现。
第 16 章	让行为可验证	上线前如何在没有真实后果的前提下检验 Agent 行为。	Agent Simulation 的用户模拟与环境模拟，可反复启动、可配置场景与资产。

第 13 章是其余三章的共同基础。没有统一口径的 Trace 与指标，安全事件无法定位到具体步骤，资产变更的影响范围无法度量，验证结论也缺少可比较的基准。第 14 章的重点在于区分两种角色：Agent 既可能被 Prompt Injection 一类手段操纵，也可能因自主行动越过边界，防护需要同时覆盖攻击面与授权面。第 15 章解决的是规模问题：单个应用可以靠团队约定管理能力资产，多团队共用时必须有注册、版本与发布机制，否则一次 MCP 变更的影响范围无人能答。第 16 章补上时间维度，把验证从上线后观察前移到上线前演练，并与 Evaluation、Testing 保持清晰分工。

四章之间只有第 13 章构成硬依赖，其余三章可按当前关注点选择顺序：负责生产稳定性从第 13、14 章进入；整理团队共用的 Prompt、Skill 与 MCP 资产直接读第 15 章；为发布把质量关重点读第 16 章。读完本篇，系统从跑得起来变为管得住、查得清，它产出的可信事实正是下一篇调优所需要的输入。

调优篇导读

调优篇负责把运行与治理的证据转化为能力提升。它直接决定前四个责任域的投入能否持续转化为生产收益，也因此是智能体工程中持续投入最集中的环节之一。

本篇的组织方式由归因决定。真实系统中的缺口可能在模型权重里，也可能在 Agent 如何被组织、被供给信息与被约束执行上，两者需要不同的方法。因此本篇以两条面向优化对象的主线展开，并补充一章相对独立的专题。

对应章节	结构	优化对象或主题	主要方法
第 17 章	模型调优	模型的理解、决策、工具使用与失败恢复能力。	监督微调（Supervised Fine-Tuning，SFT）、Agentic RL、模型蒸馏，以及在完整 Agent 中的上线验收。
第 18–23 章	智能体调优	Harness、数据与评估闭环、经验与 Skill、运行反馈。	数据飞轮：Trajectory、声明式 Pipeline、黄金数据集、持续评估与实验、Badcase 修复、受控自进化。
第 24 章	专题延伸	全球交付与边缘优化。	边缘运行时、边缘评估、性能与成本优化、内容分发、边缘安全与边缘仿真。

第一条主线是模型调优。只有当一类错误在信息充分、动作接口清晰、执行环境正常的条件下仍跨任务反复出现，才有理由把它归因于模型能力。之所以先讨论模型，是因为模型既是最受关注、也是最容易被误判的优化对象：把本应由上下文、工具协议或运行控制解决的问题当成模型不行，往往是代价最高的一类误判。第 17 章因此先建立何时才应该改模型的判据，再展开 SFT、Agentic RL 与模型蒸馏的适用边界、训练组织与验收方式。

第二条主线是智能体调优。真实系统中的多数缺口并不在模型权重里，而在 Agent 如何被组织、被供给信息和被约束执行，以及团队能否把运行经验持续变成改进。这条主线以数据飞轮为核心：把 Trace 组织成可复用的行为轨迹（Trajectory），经声明式 Pipeline 加工成业务样本，沉淀为带判据的黄金数据集，用持续评估与实验发现并验证 Badcase，再通过经验库、Skill、工具与运行机制的优化，把验证有效的方法带回 Agent 的运行环境。第 18 至 23 章沿这条主线，从数据如何组织一路讲到受控自进化。

第 24 章是一章可按需阅读的专题。当 Agent 面向全球用户交付时，网络传输、就近接入、重复推理的缓存、边缘安全前置与内容适配构成 Region 内调优之外的优化维度，本章把运行与优化延伸到离用户最近的边缘。它与两条主线不互为前提，企业可按自身部署范围选择性采用。

两条主线不是先后依赖，也没有高下之分，进入哪一条由归因决定：先排除能够独立复现的执行环境故障，再检查 Harness 是否提供了充分信息与可靠控制，最后才判断是否属于模型能力缺口。把问题落到正确的对象上，是本篇所有方法生效的前提，也是避免用模型训练弥补系统工程问题、或用系统补丁掩盖真实能力短板的关键。

实践篇导读

覆盖研发效能、设计工程、运维安全与企业 IT 、客户、销售与运营等领域，同时我们把世界人工智能开源大赛中的优秀作品也纳入进来，既有企业实践，也有来自开发者的前沿探索。

其中，研发效能共计7个案例，覆盖了阿里云在代码审查、代码缺陷修复、研发协作等多个领域，同时包含了将 Agent 产品化过程中的一些思考。设计工程共计2个案例，全面介绍了阿里云在Vibe Designing、GenUI 方面的思考和实践。运维安全与企业 IT 共计3个案例，介绍了畅捷通、吉利汽车、塔斯汀的大规模生产业务在智能运维方面的实践。客户、销售与运营共计4个案例，介绍了MiniMax 和 B 站构建上下文和记忆的实践，会计师事务所信永中和办公提效方面的探索，以及阿里云在智能问数领域的实践。

此外，2026 年 GOAI 世界人工智能开源大赛 Agent Infra 新智基座赛道提供了9个作品，涉及能源电力、金融、建筑工程设计、零售连锁、数字内容（游戏 / XR / 电商）、企业运营与组织治理、财务与渠道佣金结算、软件工程与交付、IT 运维与故障恢复、网络安全运营、数据工程，多达11个领域，提供了更加垂直化的实践样本。