主题
第 3 章 · 范式：Harness 的主流构建方式和责任边界
核心观点 + 逻辑框架（构建篇总纲）
▍速览
一句话版（开场，约 20 秒）
构建 Agent 的核心，是决定 Harness 的通用行为由谁实现、Runtime 与 Sandbox 由谁提供、企业要补齐哪些责任。四类构建入口（高代码框架 / 产品化 Harness / Managed Agents / 云产品）不是成熟度阶梯、也不互斥，按任务结构、定制深度和数据边界选最低充分方案；多个 Agent 并存后，由 Agent Platform 统一创建、接入、交付与治理。
一段话版（展开，约 60–90 秒）
Agent 从哪里开始构建？起点不是选框架，而是先决定三件事：Harness 的通用行为由谁实现、运行环境由谁提供、企业要补哪些责任。先澄清 Harness 不是什么——它不是更长的 System Prompt，不是某个框架的代名词，也不是运行环境本身；它决定的是下一步给模型什么、允许什么行动、怎么推进任务。构建时用一张八个对象的检查表回答开发阶段要解决什么，它们归纳成三个能力域：执行与编排、上下文与状态、行动与反馈——正好对应第 4、5、6 章。这里有个关键判断要先做：路径控制方式。Workflow 是预设路径，Agent 是动态决策，Hybrid 是固定边界加局部判断——这是路径控制方式，不是应用形态，别混为一谈。再看构建入口，有四类：高代码框架自己写 Harness，产品化 Harness 复用现成的工作模式，Managed Agents 把约定范围内的 Harness 与运行资源托管出去，云产品直接落在平台治理里。它们不是成熟度阶梯，也不互斥，差异只在三问：通用行为谁实现、运行谁承载、企业补什么。等团队多了、Agent 种类多了，就需要 Agent Platform：统一公共对象，比如 Task、Session、Event、Trace、Artifact、Outcome；但它不抹平实现差异，也不替业务定义什么是正确。
- 一个定义：Harness≠Prompt、≠Framework、≠Runtime/Sandbox
- 一张检查表：8 构建对象 → 3 能力域（=第 4–6 章）
- 一个区分：路径控制（Workflow/Agent/Hybrid）≠ 应用形态
- 四类入口：高代码·产品化·Managed·云产品（非阶梯、非互斥）
- 一个平台：Agent Platform 统一对象、不抹平差异、不替业务定义正确性
一句话（收尾）
无论从哪类入口构建，都要区分 Task 与 Session、Event 与 Trace、Artifact 与 Outcome，把权限与验证落实为确定性机制，并让模型、Harness 配置、能力、环境、策略和评估基线共同受版本控制。
▍逻辑框架（记忆卡片）
① 命题：Harness 是什么 / 不是什么
Harness = 模型之外，围绕 Agent Loop 组织上下文、能力、状态、环境与控制机制，并将模型判断转化为可执行、可恢复、可验证任务过程的代码、配置和执行逻辑。
- ✕ 不是更长的 System Prompt（还包括状态机、工具注册、权限检查、错误恢复、完成验证）
- ✕ 不是某个 Framework 的同义词（Framework / CLI / SDK / Managed 都是载体，Harness 是系统层）
- ✕ 不是 Runtime 或 Sandbox（Harness 决定下一步给模型什么；Runtime 承载过程；Sandbox 限制影响范围）
② 五层责任：逻辑边界，不一定对应独立产品
- Model（能理解和推理到什么程度）
- Harness 编排（如何工作）
- Runtime（如何持续运行）
- Sandbox / Environment（在哪里行动、影响范围多大）
- Agent Platform（如何规模化交付和治理）
边界在架构中必须保留，否则无法判断故障归属、数据位置和最终责任。
③ 一张检查表：8 个构建对象 → 3 个能力域
Agent Contract：为谁工作 / 目标 / 允许禁止 · Execution：循环 / 状态机 / 预算 · Context & State：每轮看见什么 / 事实存哪Capability：Tool / MCP / Skill / Subagent · Environment：在哪运行 · Control：以谁身份 / 审批 · Interaction：如何看进度 / 干预Quality：如何证明完成
- 执行与编排（→ 第 4 章）
- 上下文与状态（→ 第 5 章）
- 行动与反馈（→ 第 6 章）
④ 先判路径控制，再选构建入口
- A Workflow（路径预设（确定性流程））
- B Agent 主导（路径动态决策）
- C Hybrid（Workflow 固定边界 + Agent 做局部判断）
这是路径控制方式，不是应用形态（与 Single / Long-Horizon / Multi 并列理解）。
⑤ 四类构建入口：差异在责任归属，不在模型 / 形态
左：高代码 Framework AgentScope · LangChain 代码级控制 Loop、Context、权限、验证；适合深度定制、数据环境企业自控
右：产品化 Harness Claude Agent SDK · OpenAI Agents SDK 复用现成工作区、规划、工具执行；嵌入现有应用或工作区；Qoder CLI / SDK 同属本路径（3.3.2）
左：Managed Agents Qoder Cloud Agents · Claude 约定范围内 Harness + 运行托管；适合异步、批量、快速生产化
右：云产品构建 AgentCore 预置模型 / 知识 / 工具 / 运行 + 平台治理；从创建即进入统一资源身份版本质量体系
不是由低到高的成熟度阶梯，也不必互斥。选择时分别判断：是否依赖修改 Loop / Context、数据与执行环境能否托管、团队是否愿意维护状态恢复与 Sandbox、交付对象是工作区 / 嵌入应用 / 异步服务 / 平台 Agent。
三问：通用行为谁实现 · 运行谁承载 · 企业补什么
⑥ Agent Platform：规模化交付多个 Agent
- 多团队多 Agent 若各建各的模型接入、Tool 目录、凭证、Sandbox、观测，会形成孤岛
- 平台统一公共对象：Agent Definition、Task、Session、Event、Identity、State、Checkpoint、Artifact、Trace、Outcome，以及接入契约
- 不抹平实现差异：自研 / 开源 / SaaS 各保留自己的 Harness
- 不替业务定义任务目的和正确性：平台汇聚证据，业务 Verifier 下结论
多源统一管理三条件：版本归属可追溯 · 事件关联 Task / Identity / Tenant · 远程 Agent 返回可验收 Artifact，而非只有自然语言
▍逻辑全景图 · 图 1 · Harness 三层含义与五层责任：8 个构建对象 → 3 个能力域
先定 Harness 边界，再看五层责任沿架构逐层下落，最后由一张检查表收敛出三个能力域
- Agent / 平台核心
- 执行 / 编排
- 定义边界与强调
- 中性组件
- 定义说明区
读法：① 左侧先定 Harness 边界——它不是 System Prompt、Framework 或 Runtime/Sandbox；② 中间五层责任沿 Model → Harness → Runtime → Sandbox → Agent Platform 逐层下落，逻辑边界不必对应独立产品；③ 右侧 8 个构建对象收敛为执行与编排、上下文与状态、行动与反馈三个能力域，对应第 4、5、6 章。面试一句话：构建起点不是选框架，而是先定 Harness 通用行为谁实现、运行环境谁提供、企业补哪些责任。
▍逻辑全景图 · 图 2 · 四类构建入口的责任归属对比：先判路径控制，再选入口
路径控制方式先行判断；矩阵三行按“通用行为谁实现 · 运行谁提供 · 企业补什么”横向对比四类入口
- 高代码（企业自控）
- 产品化复用
- 托管 / 服务方约定
- 云产品预置
- 企业保留责任
| 责任维度 | 高代码 Framework | 产品化 Harness | Managed Agents | 云产品构建 |
|---|---|---|---|---|
| 前置判断：路径控制方式（是控制方式，不是应用形态） | Workflow：路径预设（确定性流程） | Agent 主导：路径动态决策 | Hybrid：固定边界 + 局部判断 | 与 Single / Long-Horizon / Multi 并列理解 |
| 典型示例 | AgentScope · LangChain | Claude Agent SDK · OpenAI Agents SDK | Qoder Cloud · Claude | AgentCore |
| 责任一：通用 Harness 行为由谁实现 | 企业 · 代码级控制（Loop · Context · 权限 · 验证） | 产品 · 复用现成（工作区 · 规划 · 工具执行） | 服务方 · 约定范围（Harness 由服务方提供） | 云产品 · 预置（模型 · 知识 · 工具 · 运行） |
| 责任二：Runtime / Sandbox 由谁提供 | 企业为主 | 产品 / 企业混合 | 服务方托管 | 云产品 |
| 责任三：企业仍需承担（不随入口转移） | 行为组合 · 安全 · 恢复 · 评估 · 验收 | 多租户 · 业务 Task · 凭证 · Artifact · Outcome | 身份映射 · 审批 · 数据边界 · 验收 · 退出机制 | 业务 Task · 权限边界 · 扩展 · 评估 · 验收 |
| 选择原则 | 不是成熟度阶梯，也不必互斥 | 差异只在：通用行为谁实现 | 运行谁承载、企业补什么 | 同一企业可高代码建核心 Agent、产品化嵌入应用、云产品快速创建，再由统一 Agent Platform 纳管运营 |
读法：顶部先判路径控制（Workflow / Agent / Hybrid），这是控制方式不是应用形态；矩阵三行分别回答通用行为谁实现、运行谁提供、企业仍承担什么；四列示例从上到下责任逐步外包。表 3-2 产品化 Harness 示例为 Claude Agent SDK · OpenAI Agents SDK；Qoder CLI / SDK 同属 3.3 复用路径（见 3.3.2）。面试一句话：四类入口不是成熟度阶梯也不互斥，差异只在责任归属，不在模型或形态。
▍书中关键图（SVG 重绘版 · 示意）
图 1｜Agent 构成与承载关系（重绘自图 3-1）
边界：一次调用没有跨轮状态 · 上下文窗口有限 · 工具调用不等于授权 · 模型自述不等于完成证据
图 2｜四类构建入口的责任归属（重绘自表 3-2）
| 责任维度 | 高代码 Framework | 产品化 Harness | Managed Agents | 云产品构建 |
|---|---|---|---|---|
| 前置判断：路径控制方式（是控制方式，不是应用形态） | Workflow：路径预设（确定性流程） | Agent 主导：路径动态决策 | Hybrid：固定边界 + 局部判断 | 与 Single / Long-Horizon / Multi 并列理解 |
| 典型示例 | AgentScope · LangChain | Claude Agent SDK · OpenAI Agents SDK | Qoder Cloud · Claude | AgentCore |
| 责任一：通用 Harness 行为由谁实现 | 企业 · 代码级控制（Loop · Context · 权限 · 验证） | 产品 · 复用现成（工作区 · 规划 · 工具执行） | 服务方 · 约定范围（Harness 由服务方提供） | 云产品 · 预置（模型 · 知识 · 工具 · 运行） |
| 责任二：Runtime / Sandbox 由谁提供 | 企业为主 | 产品 / 企业混合 | 服务方托管 | 云产品 |
| 责任三：企业仍需承担（不随入口转移） | 行为组合 · 安全 · 恢复 · 评估 · 验收 | 多租户 · 业务 Task · 凭证 · Artifact · Outcome | 身份映射 · 审批 · 数据边界 · 验收 · 退出机制 | 业务 Task · 权限边界 · 扩展 · 评估 · 验收 |
| 选择原则 | 不是成熟度阶梯，也不必互斥 | 差异只在：通用行为谁实现 | 运行谁承载、企业补什么 | 同一企业可高代码建核心 Agent、产品化嵌入应用、云产品快速创建，再由统一 Agent Platform 纳管运营 |
图 3｜从单机到分布式执行（重绘自 3.2.2 / 3.3.2 架构）
要点：① 任务状态外置到共享存储，Worker 可替换；失效后从安全点恢复，不重放最后一次调用 ② Sandbox 按任务隔离；共享 Session 需租户隔离、幂等与并发控制 ③ 单机进程做不了多租户在线服务：身份、状态、权限、Artifact、Trace 必须外置
原书 Mermaid 图（可编辑）
以下图来自原书 Markdown，保留原始结构，便于修改和对照。