06 · 如何设计一个 Agent？ - Agent Design

所属知识库：Agent 全栈技术地图
所属领域：02 · Agent
所属章节：01 · Agent 是什么？它如何工作？ - Fundamentals
文档类型：技术原理与工程实践研究
版本：v1.1
更新日期：2026 年 10 月 28 日
核心问题：如何从可验证的任务需求出发，选择 Agent 或非 Agent 方案，确定模型决策与确定性程序的控制边界，设计任务契约、执行架构、工具与状态接口、权限、失败恢复和评估实验，并通过可运行的最小实现检验设计假设？

专题导读

设计 Agent 的核心工作，不是给大语言模型赋予一个角色并配置工具，而是把一个存在不确定性的真实任务转化为可以执行、可以控制、可以验证、可以迭代的技术系统。这一过程首先要回答“为什么需要 Agent”，然后才是“应该采用怎样的 Agent”。

本篇延续 Fundamentals 前五篇对 Agent 定义、组成、能力、执行机制和类型的研究，也吸收后续 Internal Architecture 对 Identity、Model、Instructions、Context、Memory、Knowledge、Tools、Skills、Planning 与 Permissions 的分析方法，但不重复各组件的百科式介绍。本篇研究的对象是架构设计决策本身：如何诊断任务结构、分配决策权、设计执行协议、证明架构选择合理，以及在测试结果不达标时怎样修改设计。

研究路径分为六层：任务与设计边界、方案选择原理、控制架构与关键数据契约、代表性技术路线、可运行的工程设计实验、评估与设计迭代。贯穿案例为“技术研究助理 Agent”，它必须检索材料、根据证据缺口动态决定下一步、生成可核验的研究报告，同时受预算、工具权限和完成条件约束。

本文提出的决策表、数据结构、状态与评分公式属于工程研究中的参考设计，不是所有 Agent 框架统一采用的标准。本文明确区分公开资料中的既有方法、基于方法的工程推导，以及经过本地代码测试的实现。

一、研究对象：Agent 设计到底设计什么？

1.1 从任务到运行系统的设计链

一个可用的 Agent 设计至少需要建立五层可追溯关系：业务需求 → 可验证的任务契约 → 控制架构 → 运行时接口与状态 → 测试证据。只在其中一层完成工作，不能代表 Agent 已经设计完成。例如，“生成高质量报告”是需求愿望；“报告必须回答三个研究问题，每条核心主张对应来源证据”才接近可验证的任务契约；“模型可追加检索，但不能绕过来源校验直接发布”是控制架构；search(query)、read(source_id)、submit(report) 与证据表是接口和状态；针对无结果、来源冲突、预算耗尽的测试才是验证依据。

可以用如下映射表达设计完整性：

业务目标 G
  └─ 可观察验收条件 A
      └─ 任务活动 T（确定性 / 语义判断 / 外部操作）
          └─ 控制主体 C（程序 / 模型 / 人）
              └─ 执行接口 I + 状态 S + 权限 P
                  └─ 测试用例 E + 运行轨迹 R

每个关键验收条件应能追溯到负责实现它的机制与测试；每个高风险行动应能追溯到授权主体与执行边界。这比“包含十个能力模块”更能判断设计是否合理。

1.2 设计的核心对象与职责

对象	设计阶段必须明确的内容	运行时由谁负责
Task Contract	输入、输出、约束、成功与停止条件	接纳器、验收器
Agent Definition	角色、指令、模型策略、允许能力	配置装载器
Decision Policy	模型可提出哪些候选行动、何时停止	模型与决策适配层
Tool Contract	参数、返回、错误、超时、风险与副作用	工具适配器
Execution State	已完成步骤、证据、预算、待处理动作	运行时状态管理器
Authorization Policy	谁可访问什么、哪些操作需审批	可信策略执行层
Evaluation Contract	成功率、证据质量、成本、失败边界	测试与评测系统

“模型决定下一步”与“模型直接执行下一步”必须分离。模型输出只是行动提议；执行器应验证其类型、参数、权限和预算后才实施。对无副作用的检索可赋予较高自主性，对写入、发布和外发则应保留明确授权路径。

1.3 本篇与后续专题的边界

本篇研究如何选择控制架构、定义接口和验收设计；A1-A10 深入研究每项能力的内部实现；07 · Lifecycle 研究发布版本、任务状态、检查点与恢复；Development & Practice 研究真实项目的代码组织、部署和调试；Agent System 研究执行引擎、调度与多 Agent 协作。设计阶段仍须提出持久化和恢复要求，但不必在这里重复整个分布式运行时实现。

二、先判断是否需要 Agent：建立可比较的基线

2.1 四种候选方案及其本质差异

方案	决策路径由谁确定	适用任务	主要代价
传统程序	开发者编写规则	结构化、可形式化、路径稳定	规则维护成本
固定工作流	预先设计的状态图或 DAG	步骤已知、存在有限分支	对未知情况适应不足
模型辅助工作流	程序固定流程，模型负责局部语义判断	抽取、分类、摘要、标准化审查	局部模型错误
动态 Agent	模型根据观察结果选择后续行动	未知路径、多轮探索、反馈驱动	不确定性、成本、复合错误

上述分类是设计上的连续谱，而非互斥产品。一个动态 Agent 可以包含固定工作流；固定工作流也可以在某一步调用模型。真正的判据是：行动路径是否需要在运行时依据环境反馈动态确定。

Anthropic 在 Building Effective Agents 中区分预定义代码路径的 workflows 与模型动态主导工具使用的 agents，并建议先尝试最简单的可行方案；OpenAI 的 Agent 设计指南也强调模型、工具、指令和护栏的组合及从实际用例出发的设计。[R1][R2] 这为方案选择提供了工程依据，但并不意味着所有开放式任务都必须采用动态 Agent。

2.2 任务不确定性的五个维度

任务是否适合 Agent，不能只凭“复杂”二字判断。应分析：

1. 路径不确定性：事前能否穷举下一步行动？
2. 信息不确定性：所需证据是否未知，是否需要迭代发现？
3. 反馈依赖性：下一步是否必须依赖工具或环境返回的结果？
4. 可验证性：行动与最终产物是否存在可靠的外部判据？
5. 失败代价：错误决策是否可能造成不可逆或高成本副作用？

例如，“将已知十份 PDF 按固定模板提取字段”可能很耗算力，但路径相对固定；“比较陌生技术方案并追查证据冲突”路径不确定性较高。反过来，“自动向陌生客户发出付款指令”即使路径不确定，也不适合直接赋予高自主执行权，因为失败代价过高。

2.3 不应把启发式评分误认为统计结论

可以用启发式矩阵做初筛，但评分不是模型性能的客观事实。示例：将路径不确定性 U、反馈依赖 F、信息探索 I、可验证性 V、副作用风险 R 分别按 0-3 评级。较高的 U/F/I 说明动态决策可能带来收益；较低 V 或较高 R 说明需要更强的外层控制。不能简单计算一个总分并据此自动决定部署 Agent，因为高风险维度具有否决效力，且不同业务的风险容忍度不同。

更严谨的做法是设定三种基线：B0 固定程序、B1 模型辅助工作流、B2 动态 Agent，在同一测试集上比较质量、完成率、费用、延迟和越权率。若 B2 没有带来可重复的净收益，就不应因为其“更智能”而优先采用。

2.4 方案选择的边际收益判据

对候选架构 a，可定义设计期效用：

$$U(a)=w_{q}Q(a)+w_{c}C(a)-w_{l}L(a)-w_{\mathrm{\$}}(a)-w_{r}R(a)$$

其中 Q 是质量、C 是覆盖率、L 是延迟、$ 是运行费用、R 是风险。权重由业务方给定；不同量纲必须先归一化。更重要的是施加硬约束，例如 P(unauthorized_write) = 0（在定义的测试与权限模型内），而不是允许高质量分数抵消安全违规。上述公式是工程设计的多目标分析工具，并非可直接通用的 Agent 性能定律。

三、任务契约：将模糊需求编译为可验证规格

3.1 需求编译的五步

以“做一个会研究技术方案的 Agent”为例，第一步识别使用者真正要做的决策：是否采用某技术方案。第二步确定输入边界：主题、研究问题、目标读者、时间范围、可用来源和截止时间。第三步定义可交付产物：报告、证据清单、未解决问题与研究轨迹。第四步定义失败与降级：无法验证时不得假装已证实；来源不足时可交付部分报告。第五步将质量要求转换为机器检查与人工检查的组合。

# 设计契约：说明性结构，不对应特定 SDK
contract_id: research_report.v1
input:
  topic: string
  questions: list[string]
  allowed_sources: [public_web, approved_documents]
output:
  report_markdown: required
  evidence_manifest: required
  unresolved_questions: required
acceptance:
  question_coverage: all_questions_addressed_or_explicitly_unresolved
  evidence_binding: every_key_claim_has_source_ids
  artifact_integrity: report_exists_and_parses
limits:
  max_actions: 24
  max_tool_calls: 18
  deadline_seconds: 900
forbidden:
  - external_publish_without_approval
  - private_document_access_without_grant

3.2 成功条件与停止条件是不同的契约

成功条件描述“何时交付合格”；停止条件描述“何时必须结束”。例如，all_questions_addressed 可以成为成功条件，而 max_actions=24 是停止条件。若预算耗尽，Agent 应返回 PARTIAL 或 BLOCKED，而不是因为循环结束就标记 COMPLETED。这两套条件必须由运行时执行，不能仅写在自然语言提示词中。

3.3 可验证性分层

验收标准至少分三层：结构性（文件存在、字段完整、引用 ID 格式合法）、语义性（回答是否相关、论证是否清楚）、事实性（来源是否真实且确实支持主张）。结构性可以通过确定性程序验证；语义性可用人工评审或模型辅助评分；事实性应尽可能回到原始证据核查。模型评审器可能与生成器共享偏差，不能把评审器的“通过”直接等同于事实正确。

3.4 将验收条件映射到测试

需求	实现机制	测试证据
每个研究问题得到处理	open_questions 与 resolved_questions	缺失问题测试
核心结论可追溯	claim → source_id → span	虚构来源与错误引用测试
不越权发布	工具执行前的权限门禁	未授权发布拒绝测试
不无限检索	最大步数、调用预算、重复检测	循环诱导测试
中断后状态不丢失	检查点/运行状态存储	崩溃恢复测试（后续 Lifecycle）

设计评审的一个硬要求：每条高优先级需求都要有实现责任人和至少一个验证方法；无法验证的需求应标记为待研究假设，而不是当作已经满足。

四、任务结构分析：把模型判断放在正确的位置

4.1 构造任务依赖图

将任务拆成活动节点 T={t1,...,tn} 和依赖边 E。每个节点记录输入、输出、失败语义、是否可并行、是否存在副作用，以及是否需要模型决策。研究任务可能包含：问题拆解、初始检索、来源阅读、证据提取、冲突分析、补充检索、报告编写、证据审查、交付。问题拆解和冲突分析具有较强语义性；来源 ID 校验和文件保存则适合确定性程序。

用户问题 ─► 任务规格校验 ─► 初始检索
                               │
                               ▼
                           来源筛选
                               │
                               ▼
                           证据抽取
                               │
                    ┌──────────┴──────────┐
                    ▼                     ▼
                 证据充分               证据不足
                    │                     │
                    ▼                     ▼
                 生成报告             追加检索 ──┐
                    │                           │
                    ▼                           └──► 来源筛选
                 证据校验
                    │
               合格/修订/停止

这张图显示混合控制：图的关键状态和验证门禁由程序定义，而“证据不足时搜什么、优先读哪篇”由模型或策略决定。无需让模型控制所有节点。

4.2 用“可预测性 × 反馈需求”选择节点实现

节点特征	推荐实现
输入输出固定、规则可表达	普通函数或规则引擎
语义任务明确、无需动态行动	单次模型调用，结构化输出
固定多阶段依赖	工作流 / DAG
下一步依赖未知外部反馈	有边界的 Agent Loop
高风险外部副作用	确定性执行器 + 独立审批

模型不应作为数据库事务管理器、授权机构或唯一事实来源。相反，模型最适合承担难以预先穷举的语义选择：生成检索假设、判断证据缺口、选择阅读顺序、解释冲突与提出下一步候选行动。

4.3 不确定性如何传播

若一个流程包含多个有误差的语义判断节点，局部错误可能影响后续所有步骤。假设每个节点独立正确的概率为 p，连续 n 个必须全对的节点成功概率近似 p^n；例如 p=0.95、n=10，结果约为 0.599。独立同分布假设在真实 Agent 中通常不成立，此处仅说明长链路存在错误累积风险，而非对真实模型成功率的估计。

设计上的回应不是盲目增加反思轮次，而是在高影响节点设置可观察的验证点，并允许针对具体失败局部重做。例如，发现来源不支持某条主张，应返回证据收集节点，而不是重新执行整个研究任务。

五、控制架构：分配选择权、执行权与批准权

5.1 三种权力的分离

选择权：谁提出下一步行动？可以是模型、规则或用户。执行权：谁真正调用工具并改变外部世界？应由受控执行器掌握。批准权：谁有权授权高风险操作？应由用户、组织策略或其他可信主体决定。一个 Agent 可以拥有较高的只读选择权，但只有极低的外部写入执行权。

形式化地，模型返回候选行动 a，运行时执行条件可以写成：

$$execute(a)⟺schema\mathrm{\_}valid(a)\wedge authorized(a,u,r)\wedge budget\mathrm{\_}ok(a)\wedge policy\mathrm{\_}ok(a,s)$$

其中 u 是当前用户/服务身份，r 是资源范围，s 是权威运行状态。authorized 不应由模型自身的文字声明替代；审批令牌必须由可信系统签发并绑定具体操作。

5.2 四种控制拓扑及运行过程

A. 单次模型决策。 输入任务 → 模型返回结构化判断 → 程序校验 → 执行/交付。适合路由、分类和单次工具选择；优势是可预测、便于测试，限制是无法根据新观察多次调整。

B. 固定工作流。 程序定义步骤与条件分支，模型在特定节点执行语义处理。适合报告固定生产线；主要风险是未知分支处理能力不足。

C. 循环式 Agent。 运行时装配状态 → 模型提出下一步 → 校验 → 工具执行 → 写入观察 → 更新状态 → 再次调用模型，直到验收或停止。适合探索任务；必须防止循环、预算失控和不可信工具结果污染。

D. 计划-执行混合结构。 模型提出阶段性计划，运行时逐步执行；遇到新证据时局部重规划；关键验收与高风险操作由程序控制。适合研究、编程和复杂排障；额外代价是计划与现实可能不一致，需要维护计划状态。

这些拓扑不是按“先进程度”排序。实践中，常用的是外层确定性、内层局部自主的混合架构。

5.3 循环式 Agent 的运行契约

一次迭代应明确六个接口：observe(state)、decide(context)、validate(action)、execute(action)、commit(observation)、evaluate_stop(state)。这六个函数不一定对应六个独立软件服务，但其职责应可辨认。

while not terminal(state):
    observation = observe(state)
    proposal = model_decide(assemble_context(state, observation))
    action = parse_and_validate(proposal)
    decision = authorize(action, identity, state)
    if decision == DENY: record_denial(); continue_or_stop()
    result = execute_with_timeout(action)
    commit_state_and_trace(action, result)
    evaluate_progress_and_budget()

该伪代码省略了真实执行中的并发、持久化与副作用一致性；其中 commit 不能被理解为任意内存变量赋值。对不可逆操作，必须遵守独立的操作协议（详见 Lifecycle）。

5.4 何时采用多 Agent？

本篇以单 Agent 为研究对象。只有在任务存在清晰的独立工作域、可并行的不同能力、明确的交接接口，而且实验证明单 Agent 在质量或吞吐上不足时，才考虑多 Agent。增加 Agent 数量会引入额外的协调、状态共享、错误归因和成本。将“研究-分析-审核”拆成三个 Agent 并不自动比一个 Agent 加独立校验器更可靠；应以同一任务集的对照实验决定。

六、关键接口与数据结构：从架构图到可执行契约

6.1 Task、Action、Observation、State 四种基础结构

一个最小动态 Agent 至少需要把任务目标、候选行动、外部观察和权威状态区分开。以下是可移植的参考数据模型：

from dataclasses import dataclass, field
from typing import Literal

ActionType = Literal['search', 'read', 'finish']

@dataclass(frozen=True)
class Action:
    kind: ActionType
    target: str = ''
    rationale: str = ''   # 可解释的行动理由，不是模型私有推理

@dataclass(frozen=True)
class Observation:
    action: Action
    ok: bool
    data: dict
    error_code: str | None = None

@dataclass
class TaskState:
    task_id: str
    questions: list[str]
    sources: dict[str, dict] = field(default_factory=dict)
    claims: list[dict] = field(default_factory=list)
    actions_used: int = 0
    status: str = 'RUNNING'

Action 是候选指令，不是执行事实；Observation 应来自工具适配器；TaskState 是权威执行状态，不应只保存在模型对话中。模型可看到状态的受控投影，而不应直接修改数据库中的状态。

6.2 工具接口设计：输入输出之外还需要什么

工具定义至少包含：name、purpose、input_schema、output_schema、resource_scope、timeout、retry_policy、side_effect_class、authorization、error_codes。例如：

{
  "name": "read_source",
  "input_schema": {"source_id": "string"},
  "output_schema": {
    "source_id": "string",
    "content": "string",
    "retrieved_at": "ISO-8601",
    "source_version": "string|null"
  },
  "side_effect_class": "read_only",
  "permission": "read:approved_sources",
  "timeout_seconds": 15,
  "errors": ["NOT_FOUND", "ACCESS_DENIED", "TIMEOUT"]
}

工具描述不仅要告诉模型“能做什么”，还要让模型理解何时不该使用、参数边界和结果可信度。Anthropic 的工程资料将 Agent 与工具的接口设计（Agent-Computer Interface, ACI）视为重要设计工作。[R1] 但具体工具模式与协议应以选定 SDK 的实际接口为准。

6.3 来源证据的数据契约

研究 Agent 的核心不是“搜到网页”，而是从来源形成可审计主张。建议至少建立以下关系：

Source(source_id, uri, title, retrieved_at, version, access_scope)
Evidence(evidence_id, source_id, locator, excerpt_hash, text)
Claim(claim_id, statement, evidence_ids[], status)
Question(question_id, requirement, status, claim_ids[])

Claim.status 可以为 SUPPORTED、CONTESTED、UNVERIFIED，但状态必须依据验证流程更新，而不是模型自我声明。若只保存 URL 而不保存证据定位，来源内容变化后可能无法复核；若只保存摘录而不保留来源标识，则无法追溯原文。

6.4 Context、State、Memory、Knowledge 的边界

State 是任务执行事实；Context 是本次模型调用可见的信息；Memory 是可跨步骤或任务复用的持久信息；Knowledge 是可检索的外部知识资源。它们可以共享存储基础设施，但服务不同目的。设计时应先确定权威状态放在哪里，再决定哪些状态投影进入 Context。不能把“模型记住了上一轮”当作持久化保证。

例如，研究 Agent 读取十份文档后，模型上下文不必始终包含十份全文；权威证据存储保留原文与定位，Context 只装配当前问题所需证据、进度摘要和引用索引。这样可以降低上下文成本并避免证据来源丢失。

七、规划、行动选择与停止：可解释的决策协议

7.1 决策空间先于 Prompt 设计

设计动态 Agent 时，先定义合法动作集合 A(s)，再要求模型从集合中选择。研究任务中可以定义 SEARCH(query)、READ(source_id)、FINISH(report)、ASK_USER(question)。如果某动作当前不可用（例如没有读取权限或达到检索预算），运行时应从合法集合中移除，或在执行前拒绝；不能只在 Prompt 中提醒模型不要调用。

7.2 行动评分是设计工具，不是模型内部真实算法

可以用工程启发式对候选行动评分：

$$Score(a)=\alpha IG(a)+\beta Coverage(a)-\gamma Cost(a)-\delta Risk(a)-\eta Repeat(a)$$

IG 是预计信息增益，Coverage 是对未解决问题的预计覆盖，Cost 是调用成本，Risk 是权限与副作用风险，Repeat 是与已执行行动的重复程度。实际估计可能来自模型、规则或统计模型；公式不是 ReAct 或任何主流 SDK 的固定实现。其价值在于迫使设计者明确为什么要继续检索，以及何时停止。

7.3 证据充分性不是“已经搜索三次”

一个问题是否可以结束，至少取决于：关键子问题是否得到回答、来源是否独立、证据是否直接支持主张、是否存在未处理冲突，以及新增检索的预期收益。固定搜索次数可以作为硬预算，但不应成为唯一的质量判断。

可以将完成判断拆成两个门禁：candidate_complete（模型认为足够）与 verified_complete（确定性检查和必要的事实核验通过）。若前者为真、后者为假，应返回明确缺口，允许有预算的定向补充；若预算已耗尽，应交付 PARTIAL 并列出不足。

7.4 循环检测与失败恢复

重复检索同一查询、反复读取同一文档、连续产生无效工具参数是典型失控信号。运行时可为标准化后的 (action_kind, target) 维护计数，超过阈值时拒绝重复动作并返回结构化反馈；但简单去重也可能误伤合法的版本更新查询，因此应将来源版本和时间条件纳入键。工具超时需要区分可重试的只读操作与可能已产生副作用的写操作。

八、代表性研究与工程路线：从原始方法提炼设计原则

8.1 ReAct：交替推理与行动

Yao 等人在 ReAct 中研究将语言推理与外部行动交替组织，使模型能够通过工具观察修正后续决策。[R3] 对设计工作的启发是：开放式任务不能只依赖一次性规划，必须允许根据环境反馈调整行动。需要注意，ReAct 的示例轨迹不等于生产系统中的权限检查、工具执行器或持久化协议；这些机制必须由工程系统补充。也不应把模型不可见的内部推理当作审计记录。

8.2 Reflexion：利用反馈改善后续尝试

Shinn 等人的 Reflexion 探索将任务反馈转化为语言形式的反思记忆，用于改善后续尝试。[R4] 对 Agent 设计的启发是区分“行动执行失败”与“策略需要调整”：失败后若只是重复原参数，通常无法带来新信息。设计中可增加结构化失败摘要、重试预算与策略更新，但 Reflexion 的研究设置和效果不能直接外推为所有生产 Agent 的保证。

8.3 Anthropic：从简单可组合模式逐步增加自主性

Anthropic 的 Building Effective Agents 明确介绍 prompt chaining、routing、parallelization、orchestrator-workers、evaluator-optimizer 及 agents 等模式，并建议仅在复杂度带来可测量收益时增加架构层次。[R1] 这些模式的价值不在于提供唯一正确的流程图，而在于帮助设计者识别：某个需求究竟需要固定分解、并行、质量反馈循环，还是动态工具选择。其 2024 年文章自身也提示部分工具生态已变化，因此框架清单不应被当作 2026 年的稳定事实。

8.4 OpenAI：模型、工具、指令与护栏的组合

OpenAI 的 A Practical Guide to Building Agents 将模型、工具、指令作为核心构件，并讨论工具、编排、护栏及单/多 Agent 拆分。[R2] 对本篇设计方法的意义是：能力必须转化为明确的工具和指令接口，护栏不能仅是“模型应该小心”的口号。官方指南给出的是工程建议，不是证明某种架构在所有任务上最优的实验定律。

8.5 四条路线如何共同指导架构设计

技术/资料	主要研究问题	对本篇的可操作启发	不能直接推导的结论
ReAct	推理与外部行动如何交替	使用观察反馈驱动下一步	所有任务都需长循环
Reflexion	失败反馈如何影响后续尝试	保留失败原因并改变策略	反思一定提高成功率
Anthropic 模式	如何组织工作流与 Agent	先建立简单基线，再加复杂度	某模式天然适合全部行业
OpenAI 指南	如何组织模型、工具、指令和护栏	明确控制权与接口边界	提示词可以替代执行时鉴权

本节讨论的是资料明确支持的研究方向与本文的工程归纳；并未对相关论文进行重新复现实验，也未逐行审计 SDK 源代码。

九、贯穿案例：从需求到研究 Agent 的完整设计

9.1 任务与基线

用户要求：“比较三种 Agent 框架的长任务恢复机制，给出有证据的选型建议；如证据不足，主动追加检索。”首先建立 B1：固定检索三组关键词、读取每组前两条来源、汇总报告；再建立 B2：Agent 根据证据缺口动态追加检索。两者使用相同的来源读取器、证据检查器和报告输出规范，以减少评测混杂因素。

9.2 最小架构

用户输入
   │
   ▼
Task Contract Validator ───────► 拒绝无效任务
   │
   ▼
Runtime State Store ◄─────────────────────┐
   │                                     │
   ▼                                     │
Context Assembler                        │
   │                                     │
   ▼                                     │
Model / Decision Policy                  │
   │  候选 Action                         │
   ▼                                     │
Schema + Budget + Permission Gate        │
   │                                     │
   ▼                                     │
Tool Adapter (search/read)               │
   │                                     │
   ▼                                     │
Evidence Store + Observation Log ────────┘
   │
   ▼
Completion / Evidence Validator
   │
   ├── 不充分：回到决策（预算允许）
   ├── 预算耗尽：部分交付
   └── 验证通过：交付报告

这里不需要把每个矩形都做成一个 Agent。模型负责提出行动，程序负责执行与验证；证据库保存来源与主张关系；状态存储是事实来源；上下文是当前任务的受控投影。

9.3 一次设计层面的执行轨迹

任务开始时，Agent 识别三个比较维度：状态持久化、恢复语义和外部副作用。首次检索得到两份官方文档与一篇博客。模型判断博客关于“恰好一次执行”的结论缺少直接依据，于是追加针对幂等与重试语义的检索。读取新的官方资料后，证据表更新对应主张；对仍无法证实的细节标记为 UNVERIFIED。模型提交报告草稿，验收器发现第二个框架缺少“恢复粒度”的来源支持，于是返回缺口；若预算足够，Agent 继续查证，否则交付部分结论并说明限制。

这条轨迹是设计案例，不是本次真实联网执行的 Agent 记录。其目的在于展示模型决策、工具执行和程序验收如何分工。

9.4 两个关键反例

反例一：把审核写成提示词。 如果仅要求模型“确保引用真实”，模型仍可能生成不存在或不支持主张的来源。改进方案是以 source_id 和 evidence_id 为键，独立检查来源是否存在，并抽样或逐条核对证据语义。

反例二：用多 Agent 代替设计。 把“检索”“分析”“写作”“审核”分别包装成四个 Agent，并不会自动解决引用错误。若它们共享同一份错误证据或缺乏来源定位，协作只会放大错误传播。应先证明单 Agent 加确定性验证器的基线不足，再评估多 Agent 的边际收益。

十、工程实现：一个可运行的最小设计实验

本节实现一个不依赖外部 SDK 的离线实验，重点验证设计中的控制权分离、工具白名单、预算、来源证据、动态追加检索和完成门禁。它不声称实现真实 LLM 推理；policy 是可替换的确定性策略桩，用于使测试可重复。完整代码另存为同名配套 .py 文件；此处给出关键接口及运行逻辑。

10.1 运行组件与约束

最小实验包含 MockEnvironment（模拟资料库）、FixedPolicy（固定路径基线）、AdaptivePolicy（根据未解决问题追加检索）、Runtime（执行器）、Gate（参数/预算/权限检查）和 Evaluator（验收）。为了测试动态决策价值，模拟环境设计为：一个问题的有效证据不会出现在初始通用查询中，需要根据缺口发起定向检索才能发现。

关键不变量：

• actions_used <= max_actions；
• 非白名单工具永不执行；
• COMPLETED 只能由验收器设定；
• 所有报告证据 ID 必须指向已读取的来源；
• 达到预算时必须终止并保留未解决问题；
• 固定基线和动态策略在同一环境下比较。

10.2 核心决策与执行伪代码

while state.status == 'RUNNING':
    if state.actions_used >= contract.max_actions:
        state.status = 'PARTIAL'
        break
    action = policy.propose(state)          # 仅提出候选
    gate.validate(action, state, contract) # 程序验证
    observation = environment.execute(action)
    state.actions_used += 1
    state.trace.append(observation)
    update_evidence(state, observation)    # 状态更新
    if evaluator.passes(state):            # 独立完成门禁
        state.status = 'COMPLETED'

真实模型接入时，可将 policy.propose 替换为模型调用和结构化解析，但不能删除执行器的验证、预算与完成门禁。

10.3 可运行代码与验证范围

配套文件 06-Agent-Design-v1.1-demo.py 使用 Python 3 标准库。它提供固定策略与动态策略的对照，并通过断言验证完成条件、预算耗尽、越权拒绝和无证据不得完成。本节不模拟持久化检查点、外部写入、真实检索质量或模型随机性，这些是后续实验的边界。

十一、评估设计：如何证明 Agent 比基线更值得采用？

11.1 三层指标

任务层：成功率、问题覆盖率、事实准确率、引用支持率、用户验收率。过程层：无效行动率、重复调用率、平均行动数、工具错误恢复率、预算触发率。风险与资源层：越权执行次数、外部副作用错误、Token/费用、端到端延迟。只评估最终文字会遗漏执行轨迹中的错误；只评估工具调用正确性又无法证明最终任务有价值。

11.2 对照实验的最小协议

在相同任务集、资料快照和预算下比较 B0/B1/B2；对随机模型使用多次重复运行，报告均值、离散程度和失败类型。将任务分层为固定路径、轻度不确定、强探索、证据冲突、来源缺失与恶意内容。模型、Prompt、工具和上下文预算应尽可能固定，避免把多个变量同时改变后无法归因。

实验	控制变量	观察问题
固定 vs 动态检索	同一资料库与预算	动态行动是否提高覆盖率？
去掉证据门禁	其他组件不变	引用错误是否增加？
限制工具次数	预算从高到低	质量与成本如何变化？
注入错误工具结果	固定任务与策略	能否识别并降级？
删除长期记忆	保留当前状态	一次性任务是否真的需要 Memory？
引入第二 Agent	保留任务集与质量标准	协作收益是否超过协调成本？

11.3 统计与评测偏差

对成功率 p 的估计应报告样本量与置信区间，而非仅报告“20 次中成功 18 次”。任务集过小、难度分布单一、人工评分标准不一致，都可能使评测结果失真。模型评审器应使用人工抽样校准，尤其针对引用忠实度、事实正确性和安全问题。在线部署后的任务分布可能变化，需要持续监测数据漂移和失败类型。

11.4 设计迭代的因果顺序

发现失败后先归因：是需求不清、检索覆盖不足、工具接口歧义、上下文遗漏、模型决策失误、权限拒绝、验收器误判，还是预算太低？不同原因对应不同修改。不要把所有问题都归结为“模型不够强”或“Prompt 需要更长”。例如，来源 ID 丢失属于数据契约缺陷；重复发信属于工具执行语义缺陷；引用看似真实却不支持结论属于证据验证缺陷。

十二、从设计原型到工程系统的升级路径

12.1 L1：设计可审查

交付任务契约、控制权矩阵、工具 Schema、状态模型、完成条件、风险边界和测试计划。此阶段可以没有真实模型，但必须能回答“谁决定、谁执行、谁验证”。

12.2 L2：核心机制可运行

用真实代码跑通行动提议、参数验证、工具调用、状态更新、验收与停止。对照实验必须展示某项设计选择的效果，不能只有“程序打印成功”。本篇配套的离线实验属于这一层的有限范围实现。

12.3 L3：运行系统可靠

进一步接入真实模型、真实工具、持久化状态、审批、可恢复执行、日志与追踪、版本固定、数据隔离和故障注入。此时应对真实工具副作用、权限变化、并发竞争、模型升级和外部服务故障进行集成验证。它属于 Development & Practice、Lifecycle 与 Agent System 的交叉工程任务。

12.4 何时需要改变架构

当固定工作流的失败主要来自未知分支且动态策略在对照实验中稳定提升质量时，引入 Agent Loop；当 Agent 因任务过长而丢失执行状态时，引入持久化与检查点；当工具调用存在不可逆副作用时，引入幂等、审批与操作记录；当单 Agent 的瓶颈可明确拆分且并行收益超过协调成本时，再考虑多 Agent。架构升级应有可观察的触发条件。

十三、失败模式与设计诊断

症状	更可能的设计原因	验证方式	设计修正
Agent 不断重复检索	缺少进度/重复检测	查看规范化行动键	增加去重与信息增益门槛
报告引用不存在	缺少来源主键与验收	注入虚构引用	建立 Claim-Evidence 映射
任务“完成”但无文件	以模型自述作为成功	删除输出文件后测试	独立产物完整性检查
调用了不允许的工具	模型选择权等于执行权	提交越权 Action	工具白名单与鉴权门禁
工具多导致误调用	描述重叠、参数模糊	混淆工具 A/B 测试	简化工具集、明确差异
增加反思仍无改进	没有新证据或反馈	对比反思前后行动	反馈必须指向可改变的策略
高质量但费用过高	每步都使用重模型	分层记录模型费用	路由、缓存、早停与基线比较
状态恢复后重复写入	缺少副作用记录	响应丢失故障注入	幂等键、查询核验与补偿
多 Agent 结果互相矛盾	交接契约与证据不统一	比较共享证据 ID	统一事实来源和交接 Schema

故障诊断应遵循“可观察事实 → 失效机制 → 最小修正 → 回归测试”的顺序，而不是不断增加 Prompt 约束。

十四、设计交付物：Agent Design Brief v1.1

完整设计不必冗长，但至少应包含以下内容，并能被代码和测试追溯：

设计板块	必须回答的问题	主要产物
问题与基线	为什么 Agent 优于简单方案？	方案对照与假设
任务契约	输入、输出、成功和停止是什么？	Contract Schema
控制架构	哪些判断由模型、程序和人负责？	控制权矩阵、执行图
工具与环境	每个操作的参数、权限、错误与副作用？	Tool Contract
信息与状态	哪些事实持久保存，哪些进入上下文？	State / Evidence Schema
决策与停止	行动空间、预算、完成门禁？	Policy + Stop Rules
风险与恢复	失败、重试、审批和副作用如何处理？	风险矩阵与恢复策略
验收与评估	如何证明质量、成本和安全？	任务集、指标、对照实验
演进与版本	如何复现、升级与回滚？	Release 约束、变更计划

可以使用以下设计评审的否决条件：无法说明为什么需要动态决策；没有可观察的完成判据；模型可以绕过程序直接执行高风险操作；缺少硬性预算；没有基线对照；示例声称可运行却未测试核心机制。任意一项成立，都不应直接认定设计达到生产可用标准。

十五、核心结论

Agent 设计是一项任务建模与控制系统设计工作。首先明确用户要完成什么、如何判断完成，再通过任务结构分析识别真正需要动态决策的环节。模型承担语义判断和候选行动生成，程序承担状态事实、参数校验、权限、预算与验收，人工承担必须保留的高风险批准权。设计应从最简单可行的基线开始，通过同一任务集的对照实验判断自主性是否创造了可测量的净收益。

高质量的 Agent 设计不仅有角色说明和架构图，还应具备任务契约、控制权矩阵、工具接口、状态与证据模型、失败恢复策略、停止条件和测试证据。它的目标不是最大化 Agent 的自主程度或组件数量，而是在可验证的边界内，以合理成本稳定地完成任务。

参考资料与延伸阅读

[R1] Anthropic, Building Effective Agents, 2024. 官方原文：https://www.anthropic.com/research/building-effective-agents 。本文参考其 workflows/agents 区分、可组合架构模式与从简单方案开始的工程原则；原文已提示部分工具生态发生变化。

[R2] OpenAI, A Practical Guide to Building Agents, 官方在线版本（页面显示 2026-01-15）：https://openai.com/business/guides-and-resources/a-practical-guide-to-building-ai-agents/ 。本文参考模型、工具、指令、护栏及编排的设计讨论。

[R3] Shunyu Yao et al., ReAct: Synergizing Reasoning and Acting in Language Models, ICLR 2023. https://arxiv.org/abs/2210.03629 。用于解释交替推理、行动与观察反馈的研究路线。

[R4] Noah Shinn et al., Reflexion: Language Agents with Verbal Reinforcement Learning, NeurIPS 2023. https://arxiv.org/abs/2303.11366 。用于解释任务反馈与后续尝试改进的研究思路。

[R5] Stuart Russell & Peter Norvig, Artificial Intelligence: A Modern Approach, 4th ed., Pearson, 2021。理性智能体、任务环境与行动选择的基础理论。

[R6] OWASP, Top 10 for LLM Applications, https://genai.owasp.org/ 。用于延伸阅读提示注入、工具误用及信任边界风险；具体风险分类应以当前版本为准。

[R7] Anthropic, Common workflow patterns for AI agents, 2026-03-05. https://claude.com/resources/articles/common-workflow-patterns-for-ai-agents-and-when-to-use-them 。用于补充顺序、并行与评估优化型工作流的工程取舍。

研究声明

资料与事实范围。 本次在线查阅了 Anthropic 与 OpenAI 的官方工程资料，正文标注的 [R1]、[R2]、[R7] 相关设计主张有对应公开来源。ReAct、Reflexion 与经典智能体理论的归纳属于基于原始研究的技术概述；未在本次修订中重新复现实验，也未逐行审计各研究实现的源代码。本文提出的任务契约、评分公式、控制权矩阵、数据结构与设计流程属于工程综合与原创参考设计，不应误认为相关论文或厂商的标准接口。

工程验证范围。 配套 Python 示例使用标准库、模拟资料和确定性策略；验证的是控制边界、工具调用、证据完整性、预算与动态补充检索的逻辑。它不包含真实模型 API、真实互联网检索、人工审批系统、持久化检查点、并发事务或生产级安全验证。测试通过只能证明相应示例断言成立，不能证明真实 Agent 的事实准确率、可靠性或生产安全性。

最新性与适用边界。 本文更新于 2026 年 10 月 28 日。官方产品、模型、SDK、价格和工具生态可能继续变化；实际开发须以实施时官方文档和项目测试为准。本篇重点是单 Agent 设计方法，跨 Agent 协作、分布式执行与平台治理另见 Agent System 与 Agent Platform 等后续专题。