AI-Agent-Handbook · 手册逻辑全景图总览（知识索引）

34 个精读页的逻辑全景图 + 各章一句话版 · 每一幅图都是该章的引子，完整正文见各章精读页（目录见 README）

📂 前言

00 前言 · 智以致用

智以致用——智能已经造出来了，真正难的是把它"用"好：让 AI 从"会回答问题"，变成"能完成任务、能稳定完成任务"。这是 Agent 架构工作的出发点。

逻辑全景图 · 逻辑全景图 · 图 1 · 智以致用主线：智能商品化 → 两跨两线 → Harness 工程中心 → 三挑战 → Agent Native

调研报告 · 2026 Agent 开发者调研

Agent 投入已经成为共识，但生产化仍是少数派：近一半企业已开始开发，真正部署到生产的只有约五分之一，持续迭代的不到一成。卡点不是意愿、也不是模型能力，而是 Harness 层开箱即用的工程配套。

逻辑全景图 · 全景图 · 图 1 · 从投入到生产化：共识数据 → 卡点判断 → 三类瓶颈 → 运行底座 → 评估分水岭

📂 架构篇

第 1 章 · AI 原生应用的新阶段

AI 应用进入了一个新阶段：模型从被调用的引擎，变成主动的执行主体。但模型不等于 Agent——真正撑起 Agent 的，是模型外面那层工程系统 Harness。架构基石是 Agent = Model + Harness，企业据此为每类任务选择与风险匹配的最低充分架构。

逻辑全景图 · 逻辑全景图 · 图 1 · 位移与基石：从被调用的引擎到主动执行主体 + Agent = Model + Harness

第 2 章 · Agentic Application 参考架构

Agentic Application 的核心不是某个框架或模型，而是一组责任清晰、可独立演进、又通过生命周期闭环协作的系统能力。架构用三个视图理解（组件/平台/生命周期）、五个责任域承载、五阶段闭环演进——目的是对每一项被授予的自主性，建立对等的执行、观测、安全和评估能力。

逻辑全景图 · 逻辑全景图 · 图 1 · 五个能力责任域 × 三个平面（Security 横跨五层）

📂 构建篇

第 3 章 · Harness 主流构建方式与责任边界

构建 Agent 的核心，是决定 Harness 的通用行为由谁实现、Runtime 与 Sandbox 由谁提供、企业要补齐哪些责任。四类构建入口（高代码框架 / 产品化 Harness / Managed Agents / 云产品）不是成熟度阶梯、也不互斥，按任务结构、定制深度和数据边界选最低充分方案；多个 Agent 并存后，由 Agent Platform 统一创建、接入、交付与治理。

逻辑全景图 · 逻辑全景图 · 图 1 · Harness 三层含义与五层责任：8 个构建对象 → 3 个能力域

第 4 章 · 任务：编排长程推进与协作流转

任务不能靠一次模型调用完成。Harness 执行内核的职责，是把模型的离散判断组织成有状态、可控制、可恢复、可验证结束的任务过程：Agent Loop 驱动循环，权威状态与预算定边界，Planning 与阶段门禁外部化控制，Subagent 做受控委派，异步与 Continuation 跨连接续行——最后让完成由证据决定：模型只能申请完成，Harness 才提交完成。

逻辑全景图 · 逻辑全景图 · 图 1 · 执行内核主链路：Agent Loop（Prepare→Model→Act→Observe→Verify）+ 10 态状态机 + 多维预算边界

第 5 章 · 信息：上下文状态与可复用能力资产

模型窗口有限，任务世界持续增长，两者之间必须有一层独立的信息组织机制。Context 不是把更多文本喂给模型，而是按身份与可信度编译本轮视图、用 Manifest 保持可解释；历史靠压缩与卸载控制增长，关键事实先进权威状态再出窗口；Call/Session/Task 分而治之、Workspace 承载窗口外的工作记忆；Memory 存经验、Knowledge 供事实、Skill 按需渐进披露——一切资产都带作用域、版本与删除语义，纳入反退化闭环。

逻辑全景图 · 逻辑全景图 · 图 1 · Context 生命周期主链路：Builder 管线 → Manifest → Token 预算 → Commit→Compact→Rebuild→Validate

第 6 章 · 行动：受控执行验证反馈与交付准备

模型输出的工具调用只是一项行动意图，不等于身份、授权或结果。Harness 用统一 Action Plane 把意图变成受控的环境事实——Schema 校验、身份绑定、策略决策、审批、执行、Observation、Trace 一条链；Sandbox 防越界、Policy 定允许，双闸缺一不可；Trace 连因果，Evaluation 分层评测，失败聚成补丁、跑回归、过门禁，形成可运行的 Agent。

逻辑全景图 · 逻辑全景图 · 图 1 · Action Plane 统一行动链：Schema → 身份 → Policy → 审批 → 执行 → Observation（Sandbox 防越界 × Policy 定允许双闸）

📂 运行篇

第 7 章 · Agent 运行时与沙箱

Agent 在哪里执行？答案是把 Sandbox 做成可编程、受控的工作空间——模型发指令，沙箱承接实际动作并返回结果；工具执行、长时任务、训练评测三类负载各有运行机制，而 Harness、Runtime、Sandbox 的职责必须分开。

逻辑全景图 · 全景图 · 沙箱支撑执行与反馈闭环 + 三类负载 + 架构分工

第 8 章 · Agent 状态存储与语义资产

Agent 的状态由什么承载？任务事实、工作成果、记忆知识和业务语义四类对象，各有各的存储要求——运行时状态管可恢复，工作区产物管可交付，记忆知识管可复用，本体管可理解。分层承载，但身份、版本、权限与生命周期必须是同一套治理契约。

逻辑全景图 · 图 1 · 四类状态对象分层存储：运行时 / 工作区 / 记忆 / 本体 + Event Log·Checkpoint·租约

第 9 章 · AI 网关与统一流量治理

模型、工具、Agent 的流量怎么治理？AI Gateway 在三条访问路径上建立一致的策略执行点：LLM Gateway 管路由与预算（严格预算=原子预留+可证明上限）、MCP Gateway 管工具鉴权（发现≠授权）、Agent Gateway 管入口与任务关联。三种语义可组合，但都不拥有业务 Task 与 Outcome 的权威。

逻辑全景图 · 图 1 · 统一治理调用链：LLM / MCP / Agent 三层网关 × 身份 · 审批 · 证据三条横切治理线

第 10 章 · Agent 异步任务与自动化流程

长任务怎么可靠地接收、调度、等待与恢复？把执行生命周期与请求生命周期解耦：异步任务靠队列+调度器+状态机，定时与事件触发共享同一条执行链，工作流用 DAG 表达编排。完成语义分五层——执行状态、运维状态、候选证据、Evidence、业务 Outcome，各层权威不能越级。

逻辑全景图 · 总览 · 任务生命周期主链路：触发（时间/事件）→ 队列 → 调度 → 状态机 → Worker → 权威状态 → 完成语义五层

第 11 章 · Multi-Agent 协作与编排

多个 Agent 放在一起不会自然形成团队。编排层把共同目标组织成可执行可验收的任务：异构成员经适配接入并保留各自 Harness，三种组织拓扑决定协调与决策关系，Task Run 记录每次执行、结果聚合回到根 Task；共享的是上下文来源而非相同 Context，A2A / MCP / 内部消息分工协作，身份、委托与入站出站权限贯穿交接。团队价值以整体交付和协调成本共同衡量，最终验收由发起人或授权验收者确认。

逻辑全景图 · 图 1 · 团队协作全景：发起人 → 编排层 → 成员层 → 运行连接基础 → 验收归档，治理贯穿全程

第 12 章 · Agent 分布式通信

分布式通信要回答的不是该用哪个中间件，而是通信语义的选择及其后果：把业务标识、必要状态和结果获取从连接与执行实例中剥离出来，让人机、能力、协作、内构四个通信面在请求—响应、流式、任务句柄、持久通道四档语义里各取所需。

逻辑全景图 · 全景图 · 四通信面 × 四档语义 → 契约要素 → 选型决策

📂 治理篇

第 13 章 · Agent 可观测性

Agent 可观测性不是看请求成不成功，而是还原 Agent 实际执行了什么：Session 管关联范围、Trace 管一次活跃执行、Span 管具体操作；三层采集通道（应用埋点插桩、Coding Agent 的 Hook+Daemon、eBPF 无侵入），Trace·Metrics·Log 互补；之上再做审计——用可复核的证据链，把原始事实→候选信号→已确认事件分层。

逻辑全景图 · 全景图 · 从被观测对象到审计证据链

第 14 章 · Agent 安全

Agent 安全的两个动作：防护是盾、管控是缰绳。盾是全栈纵深防护——应用、模型、数据、身份、基础设施五层；缰绳是行为管控——身份鉴权、意图识别、逐次调用校验、高危二次授权、数据出域阻断。默认拒绝出站，Agent 权限不超过用户权限，全链路审计可追溯"谁通过哪个 Agent 拿了什么凭证"。

逻辑全景图 · 全景图 · 盾 + 缰绳双轨并进，身份是贯通关口

第 15 章 · AI 资产的发现与管理

Prompt、Skill、MCP Server、Agent、AgentSpec 五类能力资产，共用版本、生命周期、评审和权限，但不共用验证方法与消费协议。稳态 Agent 声明式解析出 Lock Manifest，动态 Agent 用 ARD 按意图发现、RAD 解析远程 Agent，Context Compiler 最终装配出可回放的 Context Manifest——从组织有哪些能力，到本次任务实际用了什么，形成连续关系。

逻辑全景图 · 全景图 · 从五类资源到两种获取路径

第 16 章 · Agent 行为生成与质量验证

Agent Simulation 用可控环境换可验证行为。角色外部标准、失败自然代价、身份连续三样制度前提都缺位时，模拟是唯一立刻能做的验证：边界是授权与后果，不是实现方式；Spec→Manifest→Run→Result 一条对象链，Harness 五项职责五项不做，交付证据材料而非质量结论——三道证据检查之后，才轮到 Evaluation 判定和治理门禁授权。

逻辑全景图 · 全景图 · 从制度缺位到治理门禁

📂 调优篇

第 17 章 · 模型调优

模型调优的第一动作不是训练，而是归因：先排除执行环境故障，再检查 Harness 的信息与运行控制，只有信息、动作接口和反馈都充分且稳定、同类决策错误仍跨任务反复出现，才把问题落到模型。落到模型之后再选方法——能稳定示范用 SFT，路径优劣需环境反馈用 Agentic RL，迁移降本用蒸馏——并在完整 Agent 里以质量、可靠性、成本、安全四维验收，灰度替换。

逻辑全景图 · 全景图 · 三层归因 → 方法三选 → 完整 Agent 验收 → 灰度反馈闭环

第 18 章 · Agent 调优总览

Agent 上线后要持续回答两组问题：任务有没有做好，以及做好花了多少代价。调优的本质是数据飞轮——把每次真实运行留下的事实整理成可复用样本，用评估找出问题，用实验检验修改，再把验证有效的变更带回运行环境，让下一轮真实任务提供新反馈。会做、做完和稳定交付是三个层次，必须在自己业务上建立评估。

逻辑全景图 · 全景图 · 数据飞轮三段闭环：生产 → 评估标注 → 实验反馈

第 19 章 · Agent 轨迹数据

轨迹把输入、行动、工具反馈与输出放在一起，让业务人员沿着实际过程找到改进方向。分析路径是：先找一条自己知道发生了什么的任务核对采集，按问题选检索方式缩小范围，读轨迹先看目标与结果再展开关键步骤，把工具失败、耗时偏高、业务质检三类问题落到具体行动，最后把有价值的记录留成候选样本、把规则交给 Pipeline 重复应用。

逻辑全景图 · 全景图 · 轨迹分析流：找任务 → 检索 → 读轨迹 → 三类诊断 → 沉淀样本

第 20 章 · Agent 运行时数据处理

质检人员需要的不是日志，而是一张可以直接使用的表：用户问了什么、Agent 如何回答、执行了哪些操作、记录来自哪里。Pipeline 把整理方法保存为数据处理任务，按约定持续生成 Dataset——选来源、定字段、看预览、跑任务，再加采样与 AI 标注，最后从一次整理变成按周期执行的日常质检。

逻辑全景图 · 全景图 · Pipeline：来源 → 处理模块链 → Dataset → 消费方 → 周期运行闭环

第 21 章 · Agent 黄金数据集

黄金数据集是一组经过业务确认的任务：既有题目，也有判断任务是否完成的依据。它把"临时找问题、凭印象判断"变成"同一批题检验每次修改"——改 Prompt、补 Skill、调知识库、换模型时都拿同一批题验证，再通过版本留档、校准评估器、回归检查让价值反复兑现。

逻辑全景图 · 全景图 · 黄金集建设闭环：候选集 → 标准 → 复核 → 使用 → 留档 → 回流

第 22 章 · Agent 优化 Badcase

评估检查已经发生的执行，实验让修改后的 Agent 重新回答并产生新的输出和轨迹。流程是：先选一个业务问题做出能用的评估器，用真实样本试评再跑第一批历史评估，从结果里选出值得修复的 Badcase，把确认的问题配成实验评估新答案，把企业自己的 Agent 接进来跑通，对比同一道题的前后差异决定是否采用，最后把评估沉淀成可重复的检查让下一轮修改继续使用。

逻辑全景图 · 全景图 · 评估发现问题 → 实验验证改进 → 发布回归闭环

第 23 章 · 受控自进化

受控自进化 = 让已经走通的方法被稳定采用。路径是：先选一类值得反复做好的任务，建经验库并检查挖掘质量，把经验接入 Agent 并亲自验证召回，用实验决定召回多少、什么时候用，把稳定方法整理成 Skill/SQL/Script/Workflow 资产，用失败样本推动 Skill 甚至 Harness 的改进，最后按成熟度从人工选择候选走向受控自动采用。

逻辑全景图 · 全景图 · 受控自进化闭环：经验库质量门禁 → 接入召回 → 实验定策略 → 资产化 → 受控采用

第 24 章 · Agent 边缘运行时与全球优化

全球化部署把调优带到了新的维度：延迟不对称、成本不透明、安全前置、内容适配。边缘优化的本质是把 Region 内成熟的调优能力延伸到离用户最近的边缘——评估扩展到全球交付质量，性能成本靠就近接入与语义缓存，边缘数据驱动持续优化，内容与安全在边缘分发拦截，生产验证用真实全球流量补充仿真，并沿三阶段渐进演进：基础设施增强 Agent → 能力部署到边缘 → Agent 原生部署在边缘。

逻辑全景图 · 全景图 · 从 Region 到 Edge：四维优化 → 评估 → 性能成本 → 数据驱动 → 分发安全 → 生产验证 → 三阶段演进

📂 实践与展望

25-29 · 实践篇：企业 Agent 落地案例

从内核补丁定向测试到万店连锁智能运维，从生成式 UI 到百亿对话记忆底座——16 个企业案例与 5 条高风险流程范式共同说明，Agent 的落地形态早已不是聊天框，而是嵌进研发、设计、运维、数据业务流的可治理、可审计、可闭环的数字员工体系。

逻辑全景图 · ① ABACI · 内核补丁定向测试与缺陷检测智能体

第 30 章 · 从 Agentic Application 到 Agentic OS

一家企业同时跑多个 Agent、用多种框架、服务多个租户时，前面每一篇提出的工程要求都会在每个应用里重复实现一遍、还互不一致——解法是把共性能力下沉成一个位于应用之下、被所有 Agent 共享的系统层：以任务、环境、能力、授权、证据为核心管理对象，按复用性、强制性、可验证性三条判据决定沉不沉，而任务语义始终留在应用侧。

逻辑全景图 · 全景图 · 总览：左列问题域 → 判据 → 系统层；右列标准化 → 解耦 → 自治

Personal Agent · 个人智能体案例

Personal Agent 的本质不是模型更会聊天，而是把运行内核、独立云电脑、工具生态和数字身份打包成围绕同一用户的持续委托——产品侧拆解十款产品的四条路线与六大技术挑战，工程侧用 AgentScope 的 Sandbox as Tool 架构把 Brain（推理）与 Hands（执行）分离，通过云端状态服务和执行权交接实现跨入口、跨设备的任务持续推进，最终从 C 端免费入口走向 B 端数字员工。

逻辑全景图 · 全景图 · 个人智能体：从观察信号到价值闭环的全链路

📂 认知总图

架构篇 · 认知总图

难在"用"（前言）→ 实证在 Harness 配套（调研）→ Agent 是什么（第 1 章：Model+Harness）→ 由什么组成、谁负责、怎么演进（第 2 章：责任域+闭环）→ 全书以此为坐标系展开。

逻辑全景图 · 递进链与全书坐标系（结构图）

架构篇 · 整合版

难在"用"（前言）→ 实证在 Harness 配套（调研）→ Agent 是什么（第 1 章：Model+Harness）→ 由什么组成、谁负责、怎么演进（第 2 章：责任域+闭环）→ 全书以此为坐标系展开。

概念澄清（两处容易绕的地方）

① 广义 Harness vs Harness 编排层

第 1 章的 Harness 是广义概念——模型之外的全部工程系统（含 Runtime、Sandbox、Observability、Governance）；第 2 章把其中直接组织任务循环的子域拆出来，称为 Harness 编排层。二者是同一概念在不同粒度上的表达，不是两个概念。

② 成熟度 L1–L4 与形态选型

形态选型看任务结构（Single / Long-Horizon / Multi 依任务而定），成熟度看运行与治理能力完备度（能否规模化运营）——两个

逻辑全景图 · ③ 形态演进（非替代链）

构建篇 · 认知总图

构建 Agent 的核心不是选框架，而是决定 Harness 由谁实现（第 3 章）；任务靠执行内核组织成可推进、可恢复、可验证的过程（第 4 章）；模型看见什么由上下文与状态系统编译和治理（第 5 章）；意图要变成受控的环境事实，并靠 Trace 与 Evaluation 闭环持续变好（第 6 章）——任务、信息、行动三类工程契约，构成可运行、可治理、可优化的 Agent。

逻辑全景图 · 三能力域 × 四章全景（构建篇骨架）

治理篇 · 认知总图

Agent 怎么被治理？四个维度：可观测性看见行为、安全约束行为、资产台账盘点行为、模拟在上线前验证行为。四件套互补，不是替代；验证之后的判断与发布授权，归 Evaluation 与治理门禁。

逻辑全景图 · 逻辑全景图（治理四件套：看见 · 约束 · 盘点 · 验证）

调优篇 · 认知总图

Agent 怎么持续调优？一条数据飞轮：模型层先把推理成本和延迟降下来（第 17 章），Agent 层用评估、数据、优化三件事闭环转起来（第 18 章）；运行过程沉淀成轨迹、运行时处理、黄金数据集三类数据资产（第 19/20/21 章）；评估发现问题、用 Badcase 和实验验证改进（第 22 章）；把验证过的方法受控采用、让走通的方法稳定复用（第 23 章）；最后扩展到全球边缘并让数据回流（第 24 章）。

逻辑全景图 · 逻辑全景图（调优篇主线：模型层 → 总览飞轮 → 数据三支柱 → 问题改进 → 全球延伸）

生成时间：2026-10-24 · 来源：AI-Agent-Handbook精读 34 页 · Mermaid 本地渲染