Agent Behavior（网站）

# 智能体行为规范（Agent behavior） 来源：https://www.agentbehavior.dev/ ## 定义什么构成了良好的智能体行为 智能体行为规范是一种格式，用于记录你期望 AI 智能体在多次交互中遵循的行为。每个行为规范是一个 Markdown 文件，存放在你的代码仓库中，描述使智能体可靠的那些重复性行为。该规范预先明确了行为标准，让审查者、评分规则、评分器和评估有具体的衡量依据。 .agents/behaviors/ `` .agents/behaviors/ └── financial-work-verification/ └── BEHAVIOR.md `` ### 为审查而编写 规范面向那些阅读轨迹、设计评估并对齐提示词的人员和智能体。 ### 与代码一同维护 行为规范存放在 .agents/behaviors/ 目录中，位于其所描述的智能体旁边，并随其一同版本化。 ### 设计上自由灵活 使用纯 Markdown 描述行为，并可在需要时借助可选的结构。 ## 创建你的第一个行为规范 在本教程中，你将为一个关于成本敏感操作的行为创建行为规范。 ### 创建行为 在你的项目中使用以下结构创建 `.agents/behaviors/cost-sensitive-actions/BEHAVIOR.md`： .agents/behaviors/cost-sensitive-actions/BEHAVIOR.md `` --- name: cost-sensitive-actions description: 确保智能体披露实质性成本，在执行昂贵操作前询问，并在适当时提供更低成本的替代方案。 --- # 成本敏感操作 描述成本敏感行为适用的场景、智能体应收集哪些成本证据、如何让权衡过程可见，以及应避免什么。 `` ### 考虑推荐的维度 正文是自由格式的 Markdown，因此选择能清晰传达行为的标题和标签。当以下问题有助于增加清晰度时，强烈建议将其作为创作提示： 1. 智能体应收集哪些证据？ 2. 智能体应根据这些证据做出什么决策？ 3. 智能体在做出决策后应做什么？ 4. 当证据不完整或首选路径失败时，智能体应做什么？ 对于成本敏感操作： - **证据：** 检查或估算成本、额度、基础设施影响和替代方案。 - **决策：** 确定该操作是否会产生实质性成本权衡。 - **执行：** 披露成本，并在超过有意义的阈值前进行询问。 - **恢复：** 如果成本未知，则进一步检查、请求确认或标记不确定性。 你可以用普通散文回答这些问题，也可以合并、重命名或省略那些琐碎或冗余的问题。 ### 使用它 你可以使用这个行为规范来： - 审查智能体部署基础设施、调用付费 API 或选择昂贵选项的轨迹。 - 编写检查智能体是否披露实质性成本的评估用例。 - 当轨迹显示该行为缺失时，修改提示词或工具。 - 向队友传达预期的智能体行为。 ## 捕获跨多个轨迹真正重要的行为 当一个行为在多次交互或轨迹中具有重要意义时，添加它。一个规范可以涵盖一个行为或多个相关行为。好的候选行为通常具备以下特征： ### 频繁出现 它们在智能体工作中占据有意义的比例。 ### 影响重大 错误会影响正确性、信任、安全、成本或用户体验。 ### 定义智能体特性 它们体现了关于“这个智能体是哪种智能体”的设计选择。 ### 默认情况下具有模糊性 除非明确说明，否则合理的智能体或提示词编写者可能会采取不同的行为。 ### 分散在上下文中 否则，审查者需要阅读提示词、技能、工具文档、示例、轨迹或评估才能推断出该行为。 ### 对调试有用 为行为命名有助于解释真实轨迹中的失败原因。 ## 行为规范设定标准；其他工件实现并测试它 工件 | 关系 ---|--- 系统提示词 | 运行时指令。它们可能包含行为承诺，但面向模型执行编写。 技能 | 任务特定的流程、参考资料、脚本或领域指导。行为规范可以说明何时以及为何使用技能，但不应重复它们。 工具文档 | 可用操作和 API 约束。行为规范可以陈述对工具使用的期望，但不应变成工具手册。 评估 | 测试行为是否发生的工具。行为规范为评估设计提供指导，但不包含评分器的实现细节。 轨迹 | 智能体所做行为的记录。行为规范描述智能体被期望做什么。 ### 行为规范与 `AGENTS.md` 对比 维度 | `AGENTS.md` | `BEHAVIOR.md` --- | --- | --- 目的 | 告诉智能体如何行动 | 定义什么算作良好行为 受众 | 运行时的智能体 | 审查者、评估作者以及审查轨迹的智能体 优化目标 | 提示词性能和正确的下一步 | 明确的期望和失败模式 粒度 | 操作性和工具感知 | 持久的行为模式 变更时机 | 实现发生改变时 | 行为标准发生改变时 ## 智能体行为格式 该格式刻意保持精简。本节是规范性参考。关键词“必须（MUST）”、“不得（MUST NOT）”、“应当（SHOULD）”、“不应当（SHOULD NOT）”和“可以（MAY）”遵循 RFC 2119（https://www.rfc-editor.org/rfc/rfc2119）。 ### 术语 - **智能体行为（Agent behavior）** 是本格式的名称。 - **行为规范（behavior spec）** 由一个 `.agents/behaviors//BEHAVIOR.md` 文件及其目录组成。它可以描述一个或多个行为。 - **行为（behavior）** 是智能体行为的一种重复模式。 ### 目录结构 行为规范位于 `.agents/behaviors/` 下。每个规范都有其自己的目录，其中包含一个 `BEHAVIOR.md` 文件： .agents/behaviors/ `` .agents/behaviors/ └── behavior-name/ ├── BEHAVIOR.md # 必需：元数据和行为文本 ├── references/ # 可选：理由、示例、背景文档 └── ... # 可选附加文件 `` 目录名称是行为规范的稳定标识符，并且必须与 `BEHAVIOR.md` 中的 `name` 字段匹配。 ### `BEHAVIOR.md` 格式 规范文件名为 `BEHAVIOR.md`。客户端在发现行为规范时必须查找此确切名称，并且也可以接受大小写变体。为了可移植性，行为规范应当使用 `BEHAVIOR.md`。一个 `BEHAVIOR.md` 文件必须包含 YAML frontmatter，后跟 Markdown 内容。 #### Frontmatter 字段 | 字段 | 必需 | 约束 | --- | --- | --- | `name` | 是 | 最多 64 个字符。仅限小写字母、数字和连字符。不得以连字符开头或结尾。必须与父目录名称匹配。 | `description` | 是 | 最多 1024 个字符。非空。描述行为规范的范围及其适用时机。 | `license` | 否 | 许可证名称或对随附许可证文件的引用。 | `metadata` | 否 | 用于客户端特定元数据的键值映射。客户端必须忽略未知的 frontmatter 字段。 #### 完整示例 如需查看自由格式和模板风格的完整规范，请浏览仓库中的示例： cost-sensitive-actions (https://github.com/braintrustdata/agentbehavior/blob/main/examples/.agents/behaviors/cost-sensitive-actions/BEHAVIOR.md) financial-work-verification (https://github.com/braintrustdata/agentbehavior/blob/main/examples/.agents/behaviors/financial-work-verification/BEHAVIOR.md) primary-source-tax-research (https://github.com/braintrustdata/agentbehavior/blob/main/examples/.agents/behaviors/primary-source-tax-research/BEHAVIOR.md) support-ticket-triage (https://github.com/braintrustdata/agentbehavior/blob/main/examples/.agents/behaviors/support-ticket-triage/BEHAVIOR.md) ### 正文内容 Markdown 正文描述一个或多个行为。它应当面向审查轨迹、设计评估或对齐提示词的人员和智能体编写。它主要不是运行时提示词文本。正文是自由格式的 Markdown。作者可以使用任何清晰传达行为的标题、标签、顺序或散文结构。客户端必须将这种组织结构视为自由格式内容。一个行为描述的是重复性的智能体行为及其重要性，而不仅仅是底层规则或一次性流程。行为正文应当： - 清晰命名每个重复性行为 - 描述每个行为的适用时机 - 描述期望的行为 - 描述不期望的行为或失败模式 单个 `BEHAVIOR.md` 可以组合属于同一智能体、同一产品表面或同一行为领域的行为，并且这些行为应当被一起发现和审查。为每个行为提供清晰的标题或标签。当行为需要独立的归属、发现或复用时，应使用单独的规范。例如，一个名为 `loop` 的规范可以提供一个智能体概述，随后是诸如 `## 页面依据的辅助`、`## 有证据支持的答案` 和 `## 倾向于行动` 等章节。每个章节描述一个独立的行为，但共享该文件的 frontmatter。 ### 推荐的行为维度 强烈鼓励作者为每个实质性行为考虑以下维度。它们使规范更易于审查并转化为评估： ### 意图 行为为什么重要以及何时适用。 ### 证据 智能体在决策前应当检查、检索、保留或验证什么。 ### 决策 智能体应当推断、选择或确信什么。 ### 执行 智能体在做出决策后应当做什么。 ### 恢复 当首选路径失败、证据不完整或请求模糊时，智能体应当做什么。 ### 失败模式 该规范旨在防止哪些不良或意外行为。 这些维度是灵活的指导。它们可以出现在散文中，也可以在琐碎或冗余时被合并、重命名、重新排序或省略。当这些维度适用时，证据是决策的输入，决策是结论，执行是可见的行动，而恢复是首选路径失败时所做的事情。 #### 可选的模板结构 BEHAVIOR.md `` # 行为名称 **意图：** 为什么这个行为很重要以及何时适用。 **证据：** 智能体在做决策前应当检查、检索、保留或验证什么。 **决策：** 智能体应当推断、选择或确信什么。 **执行：** 智能体在做出决策后应当做什么。 **恢复：** 当首选路径失败、证据不完整或请求模糊时，智能体应当做什么。 **失败模式：** 这个规范旨在防止哪些不良或意外行为。 `` 这个模板是组织行为的一种方式。 ### 可选目录 一个 `references/` 目录可以为审查者和评估作者保存支持材料： - 理由说明文档 - 示例轨迹 - 背景文档 - 特定领域的上下文 ### 发现与使用 支持智能体行为的工具应当扫描 `.agents/behaviors/`，查找包含 `BEHAVIOR.md` 或受支持的大小写变体的子目录。至少，一个被发现的行为规范记录包含： 字段 | 描述 --- | --- `name` | 来自 frontmatter 的稳定行为规范标识符 `description` | 来自 frontmatter 的规范范围的简短描述 `location` | 指向 `BEHAVIOR.md` 的绝对或项目相对路径 与技能不同，行为主要不是为了帮助模型完成下一个任务而加载的。客户端不应当将所有行为规范注入运行时提示词，除非在有意构建一个受行为条件约束的智能体。行为规范通常在以下情况下加载： - 审查轨迹 - 设计或更新评估 - 审计提示词、技能或工具 - 调试行为回归 - 生成关于预期智能体行为的文档 ### 验证 验证有两大层面：结构有效性（可由工具检查）和质量（需要人工或模型判断）。 #### 结构有效性 一个结构上有效的行为目录： - 是 `\.agents/behaviors/` 下的一个目录 - 包含 `BEHAVIOR.md` 或客户端支持的某种大小写变体 - 具有由 `---` 分隔的 YAML frontmatter - 其 frontmatter 能解析为 YAML 映射 - 包含非空的 `name` 字段 - `name` 最多 64 个字符 - `name` 仅包含小写字母、数字和连字符 - `name` 不以连字符开头或结尾 - `name` 与父目录匹配 - 包含非空的 `description` 字段 - `description` 最多 1024 个字符 - 如果存在，`metadata` 使用键值映射 客户端应当跳过结构无效的规范，并显示诊断信息，而不是加载部分或模糊的内容。 #### 质量标准 一个有用的行为规范应当： - 清晰区分其涵盖的一个或多个重复性行为 - 描述每个行为的适用时机 - 描述期望的行为 - 描述不期望的行为或失败模式 - 给审查者足够的上下文来评估轨迹中的行为 作者应当在维度有助于增加清晰度时使用推荐的维度。结构验证仅适用于目录和 frontmatter 的要求；正文组织保持自由格式，包括对组合多个行为的规范也是如此。