← Back
aliyun

aliyun/ai-agent-handbook

A practical guide to building enterprise AI agents across their full lifecycle.

View on GitHub ↗
Stars
1.1K
Forks
157
Watchers
1.1K
Open issues
2
Contributors
5
Language
—
License
Apache License 2.0
Default branch
main
Created Sep 11, 2026Updated Sep 30, 2026

Star growth

Today—
This week—
This month—

Star history will appear here once this repo has been tracked for a couple of days.

README

README

中文 | English

AI Agent HandBook

按照 Agent 的架构、构建、运行、治理和调优应用生命周期,总结了我们在企业级 Agent 落地过程中的实践经验和体会,若白皮书能对个人学习和企业落地 Agent 起到一点点的促进作用,将是我们莫大的荣幸。

谨以此项目,献给参与 AI 建设的所有同行者们。


1. 白皮书架构与写作背景

2025年9月,我们发布了《AI 原生应用架构白皮书》,围绕 AI 原生应用的 DevOps 全生命周期,从架构设计、技术选型、工程实践到运维优化,对概念和重难点进行体系化的拆解,并尝试提供一些解题思路。但随着模型和智能体技术的快速发展,我们发现,市场的关注度已经从快速构建智能体,转向以下三大新挑战:

  • 工程化挑战:从概率智能到可靠生产力,Agent 能够承担关键任务。

  • 规模化挑战:稳定、安全、性能、成本,从单点试验到智能基础设施,Agent 能够被大规模部署。

  • 组织化挑战:从 Agent 孤岛到智能组织,Agent 能够进入核心业务流程。

去年的那本白皮书,显然难以应对这些新的诉求。

因此,我们重新梳理了白皮书的架构,希望通过更与时俱进的内容,更高的实践篇幅占比,以及更社区化的协作,为企业选型和内部立项提供参考,并通过开源的方式长期维护该白皮书,持续呈现 AI 原生应用架构的前沿思考和落地实践。

2. 目标读者与收获

本白皮书主要面向企业级 Agent 构建与落地场景。它既适合关注 Agent 开发的工程人员,也适合用于企业内部的技术选型、架构评审、项目立项和跨团队共识建设。

读者 建议关注 你将获得
Agent / AI 应用开发者 构建篇、运行篇、调优篇 掌握 Harness、上下文、状态、工具、沙箱、轨迹与评估闭环等核心工程方法。
架构师与平台工程师 架构篇、运行篇、治理篇 建立从组件、平台责任到生命周期的完整架构视图,形成可扩展的 Agent 基础设施设计。
技术负责人和研发管理者 架构篇、治理篇、实践篇 判断应用形态、成熟度、投入边界与生产风险,支撑选型、立项和组织协同。
产品与业务负责人 调研报告、架构篇、实践篇 理解适合 Agent 的任务、人与 Agent 的责任边界,以及从试点走向核心流程的条件。
安全、质量与运维人员 运行篇、治理篇、调优篇 建立可观测、审计、安全授权、上线验证、持续评估和故障归因机制。
研究者与生态贡献者 全书与实践篇 了解企业一线问题、工程抽象和开放议题,并参与共同完善行业知识体系。

完整阅读后,你将能够:

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

3. 阅读导引

目录结构

篇章 目录 章节范围 阅读重点
2026 Agent 开发者调研报告 根目录 — 企业 Agent 开发、生产化、架构选型、工具链、治理与评估现状。
前言 00-preface/ — 白皮书结构和背景。
架构篇 01-architecture/ 第 1–2 章 定义对象、判断形态、选择成熟度并建立参考架构。
构建篇 02-build/ 第 3–6 章 以 Harness 为核心,组织任务、信息和行动。
运行篇 03-run/ 第 7–12 章 从单 Agent 稳定运行扩展到异步、多 Agent 与分布式通信。
治理篇 04-governance/ 第 13–16 章 让运行可见、行为有边界、资产可管理、上线前可验证。
调优篇 05-optimization/ 第 17–24 章 从模型与 Agent 两条主线构建持续优化闭环。
实践篇 06-case-study/ 第 25–29 章 企业实践、垂直场景与 Agent Infra 前沿探索。
总结与展望篇 07-conclusion/ 第 30 章 从 Agentic Application 走向 Agentic OS。

章节导航

篇章 章节 核心内容
架构篇 第 1 章 AI 原生应用的新阶段 应用形态演进、Agentic Application 的定义与边界、企业成熟度判断。
架构篇 第 2 章 Agentic Application 参考架构 组件视图、平台责任与生命周期视图,以及从决策到运行和改进的架构落位。
构建篇 第 3 章 范式:Harness 的主流构建方式和责任边界 高代码框架、产品化 Harness、Managed Agents、Agent 云产品与平台责任。
构建篇 第 4 章 任务:编排、长程推进与协作流转 Agent Loop、任务状态机、计划、阶段门禁、委派、异步续行与完成证据。
构建篇 第 5 章 信息:上下文、状态与可复用能力资产 Context Builder、压缩与卸载、Session、Task State、Workspace、Memory、Knowledge 与 Skill。
构建篇 第 6 章 行动:受控执行、验证反馈与交付准备 Action Plane、Function Calling、MCP、A2A、环境契约、权限、HITL 与验证闭环。
运行篇 第 7 章 Agent 运行时与沙箱 沙箱、Agent Runtime、工作空间、环境生命周期与生产运行条件。
运行篇 第 8 章 Agent 状态存储与语义资产 Event Log、Checkpoint、工作区快照、Artifact、长期记忆、RAG 与业务语义。
运行篇 第 9 章 AI 网关与统一流量治理 LLM、MCP、Agent 三类流量的身份、权限、预算、路由、审计与审批。
运行篇 第 10 章 Agent 异步任务与自动化流程 同步与异步边界、任务完成语义、定时任务、长时任务与自动化工作流。
运行篇 第 11 章 Multi-Agent 协作与编排 异构 Agent 接入、团队拓扑、任务分派、结果聚合与编排职责。
运行篇 第 12 章 Agent 分布式通信 能力面、协作面、内构面和人机面的通信协议与消息治理。
治理篇 第 13 章 Agent 的可观测性 指标、日志、Trace、事件、成本归因与审计。
治理篇 第 14 章 Agent 安全 Prompt Injection、身份鉴权、逐次校验、高危授权与数据出域防护。
治理篇 第 15 章 AI 资产的发现与管理 Prompt、Skill、MCP 与 Agent 的注册、版本、发现、依赖和发布管理。
治理篇 第 16 章 Agent 行为生成与质量验证 用户模拟、环境模拟、场景配置与上线前的 Agent Simulation。
调优篇 第 17 章 模型调优 模型问题的归因判据、SFT、Agentic RL、模型蒸馏与上线验收。
调优篇 第 18 章 Agent 调优总览 Agent 调优对象、方法边界与数据飞轮全景。
调优篇 第 19 章 Agent 轨迹数据 从 Trace 到 Trajectory,组织可复用的行为与决策证据。
调优篇 第 20 章 Agent 运行时数据处理 运行数据采集、清洗、加工与声明式数据 Pipeline。
调优篇 第 21 章 Agent 黄金数据集 构建带输入、轨迹、结果与判据的高质量评估数据资产。
调优篇 第 22 章 Agent 优化:Badcase Badcase 发现、归因、修复、回归与实验验证。
调优篇 第 23 章 受控自进化 把有效经验转化为 Memory、Skill、工具和运行机制,并控制自进化风险。
调优篇 第 24 章 Agent 边缘运行时与全球优化 边缘运行时、边缘评估、性能成本、内容分发、安全与仿真。
实践篇 第 25 章 研发效能 代码审查、缺陷检测、补丁交付、研发协作与端到端交付实践。
实践篇 第 26 章 设计工程 Vibe Designing 与 GenUI 的设计范式和工程实践。
实践篇 第 27 章 运维、安全与企业 IT 汽车、连锁零售和企业软件的大规模智能运维实践。
实践篇 第 28 章 客户、销售与运营 长周期记忆、内容洞察、办公提效和 Data Agent 实践。
实践篇 第 29 章 GOAI Agent Infra 赛道:多 Agent 协同的前沿实践探索 世界人工智能开源大赛优秀作品与多领域 Agent Infra 探索。
总结与展望篇 第 30 章 从 Agentic Application 到 Agentic OS 从单个应用走向可协作、可治理、可持续演进的智能系统。

实践案例导航

章节 案例
第 25 章 研发效能 ABACI 内核补丁定向测试与缺陷检测智能体
第 25 章 研发效能 Kitta:领域专用 Code Review Agent
第 25 章 研发效能 PatchPilot Agents:让内核补丁交付成为可编排、可验证的工程闭环
第 25 章 研发效能 从报警到自动修复,PolarDB-X 的 Loop 工程实践
第 25 章 研发效能 从编码提效到端到端交付,云通信的人机协作实践
第 25 章 研发效能 从评测驱动到端到端交付:AI Agent 安全产品研发提效实践
第 25 章 研发效能 多 Agent 组成研发小队:AI 研发如何从写代码走向端到端交付
第 26 章 设计工程 GenUI:让 Agent 从给出答案走向交付结果
第 26 章 设计工程 Vibe Designing:意图驱动的AI设计范式进化
第 27 章 运维、安全与企业 IT 吉利汽车智能运维的落地实践
第 27 章 运维、安全与企业 IT 塔斯汀万店连锁的智能运维闭环实践
第 27 章 运维、安全与企业 IT 畅捷通的可观测与智能运维实践
第 28 章 客户、销售与运营 MiniMax 构建海量长周期记忆数据底座的实践
第 28 章 客户、销售与运营 会计师事务所信永中和的办公提效探索
第 28 章 客户、销售与运营 哔哩哔哩构建全域内容洞察的实践
第 28 章 客户、销售与运营 运营分析 Data Agent 实践

推荐阅读路径

  • 第一次系统了解企业 Agent:调研报告 → 第 1–2 章 → 第 3–6 章 → 第 13–16 章。
  • 正在把 Agent 接入生产:第 7–9 章 → 第 13–14 章 → 第 18–23 章。
  • 正在建设多 Agent 系统:第 4–6 章 → 第 10–12 章 → 第 13、16 章。
  • 负责评估与持续优化:第 13 章 → 第 18–23 章 → 对应领域实践案例。
  • 负责选型或项目立项:调研报告 → 第 1–3 章 → 实践篇 → 第 30 章。

4. 下一步规划

白皮书将以开放项目的方式持续维护,而不是在首次发布后封存。接下来的重点包括:

  • 扩展企业实践案例:增加更多来自研发、运营、客服、数据、安全、财务和行业场景的一线案例,补充成功路径、架构取舍与真实失败模式。
  • 增加云资源线上体验:围绕沙箱、Runtime、AI 网关、状态存储、可观测和评估等关键能力,设计可复现的云上体验流程,让读者从阅读进一步走向动手验证。
  • 持续完善治理内容:跟进身份权限、Prompt Injection 防护、数据出域、审计、资产注册、版本治理和上线前仿真等企业核心议题。
  • 持续完善评估体系:补充任务成功率、轨迹评估、LLM-as-Judge、黄金数据集、Badcase 回归、线上实验和成本质量权衡等方法与案例。
  • 跟进技术演进:持续吸收模型、Harness、协议、Runtime、多 Agent 和 Agentic OS 的新进展,并及时修正已经不再适用的判断。
  • 建设社区协作机制:逐步完善内容规范、案例模板、术语表、校对流程和版本发布方式,降低高质量贡献的门槛。

欢迎贡献

欢迎开发者、架构师、研究者、企业技术团队和产品实践者参与共建。你可以:

  • 提交 Issue,指出事实错误、概念歧义、链接失效或需要补充的主题;
  • 提交 Pull Request,完善章节、修正内容、优化图表或补充参考资料;
  • 分享经过脱敏的企业实践、故障复盘、评估方法与架构取舍;
  • 提供可复现的代码、云资源体验流程、数据集或实验方案;
  • 参与术语统一、技术审校、案例评审和内容翻译。

贡献内容应尊重原创与授权边界;涉及企业数据、客户信息、内部系统和安全细节时,请先完成必要的脱敏与许可确认。

5. 贡献者

感谢所有参与架构设计、章节写作、案例整理与内容审校的贡献者。

阿里云

贡献领域 贡献者
前言 麻芃
开发者调查报告 任娟、王晨
架构篇 王晨、刘军、沈林
构建篇 刘军、泮圣伟、王晨
运行篇 赵庆杰、李诗波、林清山、黄晓萌、张添翼、赵源筱、孙校、宋震、胡庆达、柳遵飞、朱桐、余华峰、罗鑫、孔可青
治理篇 肖长军、周洋、张磊、王方、张海彬、程书意、刘子明、饶子昊、任懿、杨永、王硕、马昕、刘宇轩、杨翊
调优篇 张寒萌、李盛荣、王亚宁、孙坚运、马云雷、王桢、郑前祎、刘航、陈新
实践篇 杨涛、朱颜、余艾琳、胡峻
总结与展望篇 林演

外部贡献者

项目持续开放社区贡献,欢迎开发者、架构师、研究者、企业技术团队和产品实践者通过 Issue 或 Pull Request 参与内容共建;贡献被采纳后,贡献者信息将补充到本模块。


如果这份白皮书可以帮助您更好地理解、构建、运行、治理和调优 Agent,欢迎分享、讨论并参与共建。