developing-agentforce

Agent Script 技能

此技能的用途

Agent Script 是 Salesforce 的脚本语言，用于在 Atlas Reasoning Engine 上编写新一代 AI Agent。该语言于 2025 年推出，任何 AI 模型都没有使用其训练数据。本技能的参考文件包含编写、修改、诊断或部署 Agent Script Agent 所需的一切内容。

⚠️关键： Agent Script 不是 AppleScript、JavaScript、Python 或任何其他语言。切勿将 Agent Script 的语法或语义与训练数据中接触过的任何其他语言混淆。

Agent Script Agent 由 AiAuthoringBundle 元数据定义——这是一个目录，其中包含一个 .agent 文件，里面是 Agent Script 源代码，用于描述操作、指令、子 Agent、流程控制和配置；还包含一个 bundle-meta.xml 文件，其中是捆绑包元数据。Agent 会将用户话语路由到各个子 Agent 进行处理，每个子 Agent 都有指令和操作，后者由 Apex、Flows、Prompt Templates 及其他类型的后端逻辑提供支持。

本技能涵盖 Agent Script 的完整生命周期：设计 Agent、编写 Agent Script 代码、验证和调试、部署和发布，以及测试。

如何使用此技能

本文件将用户意图映射到任务领域和 references/ 中的相关参考文件。详细内容包括语法规则、设计模式、CLI 命令、调试工作流等。

根据任务描述识别用户意图。开始工作前，务必先阅读指定的参考文件。

始终适用的规则

1. 始终使用 --json。 每条 sf CLI 命令都必须包含 --json。不要使用 jq 或 2>/dev/null 管道处理 CLI 输出。直接读取完整的 JSON 响应——大模型可以原生解析 JSON。

2. 确认目标 org。 与任何 org 交互之前，运行 sf config get target-org --json，确认已设置目标 org。如果未配置，请让用户使用 sf config set target-org <alias> 进行设置。

3. 先诊断，再修复。 验证或调试 Agent 行为时，务必使用 --use-live-actions 预览创作捆绑包。发送用户话语，然后阅读生成的会话跟踪记录，以了解 Agent 的行为。跟踪文件会展示子 Agent 的选择、操作的 I/O 以及大模型推理。未通过这些跟踪记录了解情况之前，切勿修改 .agent 文件或后端逻辑。有关跟踪文件位置和诊断模式，请参阅验证与调试。

4. 规范审批是硬性门槛。 未经用户明确批准，切勿在创建 Agent 规范后继续操作。

任务领域

以下每个任务领域都有必需步骤。请按原文顺序逐项遵循，不要替换为自己的计划，也不要跳过步骤。

创建 Agent

用户想从零开始构建新的 Agent。务必使用 Agent Script。使用通俗语言与用户沟通，了解 Agent 的用途、子 Agent 和操作，不要使用 Salesforce 专业术语。

必需步骤

阅读Agent CLI，了解准确的命令语法。

1. 设计 — 阅读 设计与 Agent 规范，起草 Agent 规范。始终询问是否要扫描现有的后端逻辑。除非另有指示，否则读取 sfdx-project.json 以识别包目录，然后在各目录中搜索 classes/ 下的 @InvocableMethod、flows/ 下的 AutoLaunchedFlow，以及 promptTemplates/ 下的模板元数据。将匹配项标记为 EXISTS；未匹配的操作标记为 NEEDS STUB。还要扫描 objects/ 中的 .object-meta.xml，以发现自定义对象——相关对象通常包含 Agent 应公开的数据，即使提示词中没有提及。始终将 Agent 规范保存为文件。
2. 暂停，等待用户批准 Agent 规范。 呈交给用户，并请求批准或反馈。未经批准，不得继续。 批准后，除非某个步骤失败，否则继续操作，不再暂停。
3. 验证环境先决条件 — 阅读 设计与 Agent 规范 第 3 节（环境先决条件）。根据设计中确定的 Agent 类型，验证组织环境：
   • 员工 Agent：确认配置块中不包含 default_agent_user、connection messaging: 或关联到 MessagingSession 的变量。如有，则移除。完整的员工 Agent 示例请参阅 示例。
   • 服务 Agent：查询组织是否存在 Einstein Agent User。如果存在，请与用户确认用户名。如果不存在，则引导用户创建。创建步骤请参阅 Agent CLI 第 12 节；所需权限请参阅 Agent 用户设置。 环境验证完成之前，不得继续生成代码。
4. 生成创作包 — sf agent generate authoring-bundle --json --no-spec --name "<Label>" --api-name <Developer_Name>
5. 编写代码 — 阅读 核心语言，了解语法、代码块结构和反模式。使用参考文件和模板编辑生成的 .agent 文件。不要手动创建 .agent 或 bundle-meta.xml 文件。
6. 验证编译 — sf agent validate authoring-bundle --json --api-name <Developer_Name> 如果验证失败，请阅读 验证与调试 以诊断并修复问题，然后重新验证。生成后端逻辑之前，务必先修复语法和结构错误。
7. 生成后端逻辑 — 对每个标记为 NEEDS STUB 的操作： sf template generate apex class --name <ClassName> --output-dir <PACKAGE_DIR>/main/default/classes 使用 设计与 Agent 规范 中的可调用模式替换类主体。务必部署： sf project deploy start --json --metadata ApexClass:<ClassName> 生成并部署下一个桩代码之前，务必先修复部署错误。
8. 验证行为 — 阅读 验证与调试，了解预览工作流和会话跟踪分析。 sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> 如果操作会查询数据，请使用以下命令，为测试话语提供依据： sf data query --json -q "SELECT <Relevant_Fields> FROM <SObject> LIMIT 100" 使用以下命令发送测试话语： sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>" 确认子 Agent 路由、门控和操作调用均符合 Agent 规范。如果行为不符，请切换到 诊断行为问题 工作流。修正问题后返回。 检查点 — 只有以下条件全部满足，才能继续发布：
   • validate authoring-bundle 验证通过且错误数为零
   • 已使用具有代表性的各子 Agent 话语测试实时预览（--use-live-actions）
   • 跟踪记录确认子 Agent 路由和操作调用正确
   • 用户明确批准部署
9. 发布 — 发布会验证元数据结构，而非 Agent 行为。每次发布都会生成永久版本号。 sf agent publish authoring-bundle --json --api-name <Developer_Name> 如果发布失败，请按照 元数据与生命周期 第 5 节中的故障排查清单处理，然后重试。
10. 激活 — 让新版本可供用户使用。 sf agent activate --json --api-name <Developer_Name>
11. 验证已发布的 Agent — 激活后，预览面向用户的行为： sf agent preview start --json --api-name <Developer_Name> 使用 --api-name，不要使用 --authoring-bundle。
12. 配置最终用户访问权限 — 仅适用于员工 Agent。 阅读 Agent 访问指南，配置权限并分配访问权限。

参考文件

1. 面向 Agent 的 CLI — generate、validate、deploy、publish、activate 的准确命令语法；Einstein Agent 用户创建请参阅第 12 节
2. 核心语言 — 执行模型、语法、代码块结构、反模式
3. 设计与 Agent 规范 — 子 Agent 图设计、流程控制模式、Agent 规范编写、后端逻辑分析；环境先决条件请参阅第 3 节
4. 子 Agent 图示 — 用于可视化 Agent 子 Agent 图的 Mermaid 图表规范
5. Agent 用户设置与权限 — 权限集分配、对象权限、跨子 Agent 验证
6. 元数据与生命周期 — 目录结构、包元数据；发布故障排除
7. 验证与调试 — 验证 Agent 能否编译，通过预览确认行为
8. Agent 访问指南 — 最终用户访问权限、可见性故障排除
9. 已知问题 — 仅在修复代码后错误仍然存在时加载
10. 架构模式 — 中心辐射式、验证关卡、操作后循环
11. 复杂数据类型 — 类型映射决策树
12. 安全审查 — 7 类安全审查
13. Discover 参考 — 目标发现 CLI
14. Scaffold 参考 — 存根生成 CLI
15. Deploy 参考 — 部署生命周期、错误恢复

理解现有 Agent

用户想了解自己未编写或需要重新查看的 Agent Script Agent。用户可能会指向 AiAuthoringBundle 目录，或询问“这个 Agent 是做什么的？”、“我需要修复这个 Agent，但不明白它的工作原理。”。

必需步骤

1. 定位 Agent — 阅读 sfdx-project.json 以确定包目录。在这些目录中查找 AiAuthoringBundle 目录。阅读 .agent 文件和 bundle-meta.xml。
2. 阅读代码 — 在解析 .agent 文件之前，先阅读核心语言，了解语法和执行模型。
3. 梳理后端逻辑 — 对于每个带有 target 的操作，在项目中定位其后端实现（Apex 类、Flow、Prompt Template）。记录输入/输出约定。
4. 逆向工程 Agent 规范 — 阅读设计与 Agent 规范，了解 Agent 规范结构。根据代码生成 Agent 规范并保存为文件。
5. 生成子 Agent 图示 — 阅读子 Agent 图示，了解 Mermaid 规范。生成子 Agent 图的流程图，展示转换、关卡和操作关联。
6. 注释源代码 — 询问用户是否需要为 Agent Script 源代码添加注释说明。如有需要，在 .agent 文件中添加行内注释，解释流程控制决策、关卡理由和子 Agent 关系。
7. 向用户展示 — 分享 Agent 规范、子 Agent 图示，以及（如已生成）带注释的源代码。检查核心语言参考中的“反模式”部分，并指出代码中发现的任何匹配项。

参考文件

1. 核心语言 — 语法、 执行模型、反模式
2. 设计与 Agent 规范 — Agent 规范结构、流程控制模式识别
3. 子 Agent 映射图 — 用于子 Agent 图可视化的 Mermaid 约定
4. 元数据与生命周期 — 目录约定、捆绑包元数据
5. 已知问题 — 仅在代码中 包含无法解释的变通模式时加载

修改现有 Agent

用户希望在现有 Agent 上添加、移除或更改子 Agent、操作、指令或流程控制。用户可能会用普通语言描述更改（“添加一个账单子 Agent”），也可能会引用特定的 Agent Script 结构。

必需步骤

阅读 CLI for Agents，了解准确的命令语法。

1. 理解 — 如果不存在 Agent Spec，请先按照上文“理解现有 Agent”工作流进行逆向工程。
2. 更新 Agent Spec — 阅读 设计与 Agent Spec，了解流程控制模式和后端逻辑分析。修改 Agent Spec 以反映预期变更。对于新操作，始终询问是否应扫描现有后端逻辑。除非另有指示，否则读取 sfdx-project.json 以识别包目录，然后在每个目录的 classes/ 中搜索 @InvocableMethod，在 flows/ 中搜索 AutoLaunchedFlow，并在 promptTemplates/ 中搜索模板元数据。将匹配项标记为 EXISTS；未匹配的操作标记为 NEEDS STUB。始终将更新后的 Agent Spec 保存为文件。
3. 暂停，等待用户批准更新后的 Agent Spec。 向用户展示。询问是否批准或提供反馈。未经批准，不要继续。 获得批准后，除非某个步骤失败，否则继续操作，无需暂停。
4. 编辑代码 — 阅读 核心语言，了解语法和反模式。编辑 .agent 文件以实现已批准的变更。
5. 验证编译 — sf agent validate authoring-bundle --json --api-name <Developer_Name> 如果验证失败，请阅读 验证与调试 进行诊断和修复，然后重新验证。
6. 生成新的后端逻辑 — 对于每个标记为 NEEDS STUB 的新操作： sf template generate apex class --name <ClassName> --output-dir <PACKAGE_DIR>/main/default/classes 使用 设计与 Agent Spec 中的 invocable 模式替换类主体。始终部署： sf project deploy start --json --metadata ApexClass:<ClassName> 始终先修复部署错误，再生成和部署下一个存根。 如果没有新增操作，则跳过此步骤。
7. 验证行为 — 阅读 验证与调试，了解预览工作流和会话跟踪分析。 sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> 如果操作会查询数据，请使用以下命令为测试话语提供数据依据： sf data query --json -q "SELECT <Relevant_Fields> FROM <SObject> LIMIT 100" 使用以下命令发送测试话语： sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>" 优先测试已变更的路径，然后测试相邻路径，以发现现有行为中的回归问题。 检查点 — 只有以下条件全部满足，才能继续发布：
   • validate authoring-bundle 通过且无错误
   • 已使用有代表性的测试话语对每个子 Agent 进行实时预览测试（--use-live-actions）
   • 跟踪记录确认子 Agent 路由和操作调用正确
   • 用户明确批准部署
8. 发布 — 发布会验证元数据结构，而非 Agent 行为。每次发布都会生成永久版本号。 sf agent publish authoring-bundle --json --api-name <Developer_Name> 如果发布失败，请先按照 元数据与生命周期 的第 5 节中的故障排除清单操作，再重试。
9. 激活 — 使新版本可供用户使用。 sf agent activate --json --api-name <Developer_Name>
10. 验证已发布的 Agent — 激活后预览面向用户的行为： sf agent preview start --json --api-name <Developer_Name> 使用 --api-name，不要使用 --authoring-bundle。

参考文件

1. Agent 命令行工具 — validate、deploy、preview、publish、activate 的精确命令语法
2. 核心语言 — 语法、反模式
3. 设计与 Agent 规范 — Agent 规范更新、底层逻辑分析
4. 验证与调试 — 编译诊断、预览工作流、会话跟踪分析
5. 已知问题 — 仅在代码修复后错误仍然存在时加载

诊断编译错误

用户的 Agent Script 无法编译。错误会通过 sf agent validate 或 sf agent preview start 显示，或者用户会描述类似“我遇到了验证错误”的症状。

必需步骤

阅读 Agent 命令行工具，了解精确的命令语法。

1. 复现错误 — 运行 sf agent validate authoring-bundle --json --api-name <Developer_Name> 以捕获基本编译错误。如果没有错误，则运行 sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> 以捕获复杂编译错误。如果用户提供了具体错误输出，务必复现以确认。
2. 对错误分类 — 阅读 验证与调试，了解错误分类法。将每条错误消息对应到根因类别。
3. 定位故障 — 阅读 核心语言，了解正确的语法。找到 .agent 文件中导致每条错误的具体行。
4. 修复代码 — 应用有针对性的修复。检查核心语言参考中的反模式部分，确保不会引入已知的不良模式。
5. 重新验证 — 运行 sf agent validate authoring-bundle --json --api-name <Developer_Name> 然后运行 sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> 如果错误仍然存在，重复步骤 2–5。
6. 说明修复内容 — 告诉用户哪里出了问题，以及你做了哪些更改。结合核心语言中的 Agent 执行模型解释根因。

参考文件

1. 核心语言 — 语法、块结构、反模式
2. 验证与调试 — 错误分类法、错误与根因的对应关系
3. 已知问题 — 仅在错误与用户代码不符时加载；可能是平台错误
4. 生产环境注意事项 — 仅在错误涉及保留关键字或生命周期钩子语法时加载

诊断行为问题

Agent 可以编译，预览可以启动并使用 --use-live-actions，但 Agent 的行为不符合预期。用户可能会描述类似“Agent 总是跳转到错误的子 Agent”或“操作没有被调用”的症状。这与 validate 或 preview start 错误有根本区别——代码有效，但行为不正确。

必需步骤

阅读 CLI for Agents，了解准确的命令语法。

1. 建立基线 — 阅读 Agent Spec。如果不存在 Agent Spec，请按照 Comprehend an Existing Agent 工作流对其进行逆向工程，然后继续。
2. 提出假设 — 阅读 Core Language，了解执行模型。根据用户的描述，列出可能的根本原因。逐一考虑：子 Agent 路由、门控条件、操作可用性、指令清晰度、变量状态和转换时机。
3. 在预览中复现 — 阅读 Validation & Debugging，了解预览工作流和会话跟踪分析。启动预览会话： sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> 然后使用 sf agent preview send 发送测试消息，覆盖每个子 Agent。仅发送一条消息是不够的——继续之前，请确认每个子 Agent 的行为。
4. 分析会话跟踪 — 检查跟踪输出，确认子 Agent 的选择、操作的可用性和执行情况、大模型推理过程，以及行为偏离 Agent Spec 的位置。不要跳过此步骤——仅凭预览输出不足以诊断问题。
5. 确定根本原因 — 将跟踪证据与假设相匹配。查阅 Design & Agent Spec 参考资料中的 Core Language reference and Gating Patterns，确认不存在反模式。
6. 修复代码 — 应用有针对性的修复。如果修复涉及流程控制变更，请相应更新 Agent Spec。
7. 重新验证并再次预览 — 重复步骤 3–6，直到行为符合 Agent Spec，或确认存在平台限制。运行 validate authoring-bundle，然后运行 preview start --use-live-actions，使用相同的表达验证修复。接着测试可能受变更影响的相邻路径。
8. 说明修复 — 告诉用户问题所在以及你做了哪些修改。根据 Core Language 中的 Agent 执行模型解释根本原因。

参考文件

1. Core Language — 执行 模型、反模式
2. Design & Agent Spec — Agent Spec 作为行为基线、门控模式
3. Validation & Debugging — 预览工作流、会话跟踪分析
4. Known Issues — 仅在行为 异常但代码逻辑正确时加载

部署、发布和激活

用户希望将本地开发中已正常工作的 Agent 部署到 Salesforce 组织并使其运行。这涉及部署 AiAuthoringBundle 及其依赖项、发布以提交版本，然后激活使其上线。

必需步骤

阅读 CLI for Agents，了解准确的命令语法。

1. 验证编译 — sf agent validate authoring-bundle --json --api-name <Developer_Name> 如果验证失败，请勿继续。
2. 部署捆绑包及其依赖项 — 阅读 Metadata & Lifecycle，了解依赖项管理和部署命令。将 AiAuthoringBundle 及所有支撑逻辑（Apex 类、Flows、Prompt Templates）和依赖项部署到 org。
3. 实时预览 — 阅读 Validation & Debugging，了解预览工作流和会话跟踪分析。 sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> 然后使用以下命令发送测试话语： sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>" 测试关键对话路径，以验证由实时操作提供支持时 Agent 的行为。 检查点 — 除非以下条件全部满足，否则不要继续发布：
   • validate authoring-bundle 验证通过且没有错误
   • 已使用具有代表性的各子 Agent 话语测试实时预览（--use-live-actions）
   • 跟踪确认子 Agent 路由和操作调用正确
   • 用户明确批准部署
4. 发布 — 发布会验证元数据结构，而非 Agent 行为。请勿在开发/测试迭代中发布。只有在激活 Agent 并向最终用户开放之前，才能将发布作为最后一步。 sf agent publish authoring-bundle --json --api-name <Developer_Name> 如果发布失败，请在重试前按照 Metadata & Lifecycle 中的 Troubleshooting Publish Failures 操作。
5. 激活 — 使新版本可供用户使用。 sf agent activate --json --api-name <Developer_Name>
6. 验证已发布的 Agent — 激活后，通过预览检查面向用户的行为： sf agent preview start --json --api-name <Developer_Name> 使用 --api-name，不要使用 --authoring-bundle。
7. 配置最终用户访问权限 — 仅适用于员工 Agent。阅读 Agent Access Guide，配置权限并分配访问权限。

参考文件

1. CLI for Agents — 部署、发布、激活和停用的准确命令语法
2. Validation & Debugging — 编译验证、预览工作流
3. Metadata & Lifecycle — 依赖项管理、部署命令；发布故障排查
4. Agent Access Guide — 最终用户 访问权限、可见性故障排查
5. Known Issues — 仅在部署卡住、发布失败或激活意外失败时加载

诊断生产问题

用户的 Agent 已发布并处于激活状态，但仍遇到预览阶段未发现的问题。包括积分消耗过多、令牌或大小限制导致的失败、循环防护中断、保留关键字导致的运行时错误、VS Code 同步失败，或预览与生产环境之间出现意外的行为差异。

必需步骤

阅读 面向 Agent 的 CLI，了解准确的命令语法。

1. 对问题进行分类 — 判断这是计费/成本问题、运行时限制、命名冲突、工具问题，还是预览版与生产环境之间的行为差异。
2. 检查已知的生产环境注意事项 — 阅读 生产环境注意事项，了解积分消耗、令牌限制、循环护栏、保留关键字、生命周期钩子和 VS Code 解决方法。
3. 比较预览版与生产环境的行为 — 如果问题与行为有关，请使用 sf agent preview start --json --api-name <Developer_Name> 预览已发布的 Agent（不要使用 --authoring-bundle）。再将其与使用 --authoring-bundle <Developer_Name> --use-live-actions 的实时操作创作捆绑包预览进行比较，以隔离预览版与生产环境之间的差异。
4. 检查已知问题 — 阅读 已知问题，查看可能导致仅在生产环境中出现故障的平台问题。
5. 修复并重新发布 — 应用修复、验证、重新预览、发布、激活并确认。遵循部署、发布和激活步骤。
6. 说明诊断结果 — 告诉用户发生了什么以及你做了哪些更改。说明根本原因。

参考文件

1. 生产环境注意事项 — 积分 消耗、令牌限制、循环护栏、保留关键字、 生命周期钩子、VS Code 解决方法
2. 面向 Agent 的 CLI — 预览、发布、激活的命令 语法
3. 验证与调试 — 预览工作流、会话跟踪分析
4. 已知问题 — 仅在问题可能是 平台错误时加载

删除或重命名 Agent

用户想要移除 Agent 或更改其名称。由于 AiAuthoringBundle 版本控制和已发布版本依赖关系，维护任务较为复杂。

必需步骤

阅读 面向 Agent 的 CLI，了解准确的命令语法。

1. 了解当前状态 — 阅读 元数据与生命周期，了解版本控制、删除机制和重命名机制。确认 Agent 是否已发布、存在多少个版本，以及当前是否处于激活状态。
2. 如果处于激活状态，则停用 — sf agent deactivate --json --api-name <Developer_Name> 处于激活状态的 Agent 无法删除或重命名。
3. 执行操作 — 删除时：遵循“元数据与生命周期”参考文档中的删除机制。重命名时：遵循同一参考文档中的重命名机制。
4. 清理孤立项 — 检查并移除孤立的元数据：Bot、BotVersion、GenAiPlannerBundle、GenAiPlugin、GenAiFunction。“元数据与生命周期”参考文档详细说明了需要检查的内容。
5. 验证 — 确认操作已顺利完成。重命名时，验证新的捆绑包可以编译，并进行预览以确认行为。

参考文件

1. 面向 Agent 的 CLI — 删除、停用、检索的准确 命令语法
2. 验证与调试 — 编译验证、预览工作流
3. 元数据与生命周期 — 删除机制、重命名机制、孤立项清理

测试 Agent

用户想要为 Agent Script Agent 创建自动化测试。这需要以 YAML 格式编写 AiEvaluationDefinition 测试规范，用于定义测试场景、预期行为和质量指标。

必需步骤

阅读 CLI for Agents，了解准确的命令语法。

1. 建立覆盖基线 — 阅读 Agent Spec。如果不存在 Agent Spec，请先按照 Comprehend 步骤进行逆向工程。梳理每个子 Agent、操作和流程控制路径，确定需要测试覆盖的内容。
2. 设计测试场景 — 测试设计方法、预期结果、指标、测试规范 YAML 格式和模板，请使用 testing-agentforce 技能。该技能负责所有测试内容。针对每个覆盖目标，编写一个或多个测试场景：用户话语、预期的子 Agent 路由、预期的操作调用以及预期的 Agent 响应。既要包含正常路径，也要包含边缘情况。
3. 编写测试规范 YAML — 使用 testing-agentforce 技能中的模板和参考文件。将文件保存到 SFDX 项目中的 specs/<Agent_API_Name>-testSpec.yaml。
4. 创建测试元数据 — 使用 CLI 根据测试规范生成 AiEvaluationDefinition。
5. 部署测试 — 将 AiEvaluationDefinition 部署到组织。
6. 运行测试 — 使用 CLI 执行测试运行。捕获结果。
7. 分析结果 — 将实际结果与预期进行比较。对于失败的测试，判断问题出在 Agent 代码、后端逻辑还是测试规范本身。
8. 迭代 — 根据需要修复 Agent 代码或测试规范，重新部署并再次运行，直到达到覆盖目标。

参考文件

1. CLI for Agents — 测试创建、运行和结果查询的准确命令语法
2. Core Language — 用于设计有效测试的 Agent 结构
3. Design & Agent Spec — Agent Spec 作为测试覆盖基线
4. testing-agentforce 技能 — 测试规范 YAML 格式、预期结果、指标、测试设计方法和测试规范模板

Agent Spec

Agent Spec 是此技能生成和使用的核心产物。它是一份结构化设计文档，描述 Agent 的用途、子 Agent 图、带后端逻辑的操作、变量、门控逻辑和行为意图。

Agent Spec 会随着 Agent 演进。在创建 Agent 时内容较少（用途、主题、方向性说明）；在构建 Agent 时逐步完善（流程图、映射后的后端逻辑、记录的门控逻辑）；在理解现有 Agent 时通过逆向工程生成。它对于高级故障排查至关重要，可作为对照预期行为与实际行为的参考。在测试期间，测试覆盖情况会依据它进行映射。

对于任何会更改或分析 Agent 的操作，始终将生成或更新 Agent Spec 作为第一步。它能为工作提供一致的依据，也是开发者可以审阅的持久产物。

阅读 Design & Agent Spec，了解 Agent Spec 的结构和编写方法。

资源

assets/ 目录包含模板和示例。当你需要起点或工件和源文件的具体参考时，请阅读这些内容。

• assets/agent-spec-template.md — Agent Spec 模板，包含所有章节和占位内容。将其复制到项目目录中的 <AgentName>-AgentSpec.md，然后在设计过程中填写。将 Agent Spec 保存为文件——这是一项重要的设计工件，妥善渲染会更有帮助，尤其是 Mermaid 子 Agent 映射图。

• assets/local-info-agent-annotated.agent — 基于 Local Info Agent 编写的完整注释示例，展示了 Agent Script 的所有主要构造及其上下文，并通过行内注释解释使用每种构造的原因。当你需要了解各个概念如何组合成可运行的 Agent，或者参考文件中的针对性示例不够充分时，可阅读此文件作为备用参考。

• assets/template-single-subagent.agent — 包含一个子 Agent 的最简 Agent。复制并修改它，以创建简单的 Agent。

• assets/template-multi-subagent.agent — 包含多个子 Agent 和转换的最简 Agent。复制并修改它，以创建复杂的 Agent。

• assets/invocable-apex-template.cls — 可调用 Apex 类的参考示例。需要复杂的 Apex 后端逻辑时，可复制并修改此文件。

重要限制

• 仅使用 Salesforce CLI 和 Salesforce 组织。 不要引用或依赖其他技能、MCP 服务或外部工具。所有命令都使用 sf（Salesforce CLI）。

• 只有某些后端逻辑类型可用于操作。 例如，操作只能由可调用 Apex（而非任意 Apex 类）提供后端逻辑。Flow 和提示词模板也可能存在类似限制。将操作连接到后端逻辑时，请查阅 Design & Agent Spec 参考文件，了解有效类型和存根方法。

• sf agent generate test-spec 不适用于 Agent 操作。 这是为人类设计的交互式 REPL 风格命令。创建测试规格时，请改用 assets 中的样板模板。

常见问题速查

发布时出现 Internal Error, try again later： default_agent_user 无效或缺失。重新运行 Design & Agent Spec 第 3 节中的查询。不要编造用户名。

预览时出现 Unable to access Salesforce Agent APIs...： default_agent_user 缺少权限。请参阅 Agent User Setup & Permissions。不要通过发布来修复——--use-live-actions 不要求 Agent 已发布。

权限错误中引用的用户名与已配置的用户名不同： 修复方法同上——错误引用的是组织默认运行用户，但根本原因是 Einstein Agent User 的权限。

即使当前子 Agent 的操作可正常运行，Agent 仍因权限错误而失败： Planner 会在启动时验证所有子 Agent 中的所有操作。缺少一项权限就会导致整个 Agent 失败。

Apex 操作在实时预览中返回空结果，但在模拟模式下正常： WITH USER_MODE + 缺少对象权限 = 静默失败（0 行，无错误）。请参阅 Agent User Setup & Permissions 第 6.2 节。

语法快速参考

• 块顺序：system: → config: → variables: → connection: → knowledge: → language: → start_agent agent_router: → subagent: 块
• 缩进：每级缩进使用 4 个空格。切勿使用制表符。混用空格和制表符会导致解析器无法正常工作。
• 布尔值：True/False（首字母大写）
• 字符串：始终使用双引号
• 数值型操作 I/O：变量可以使用裸 number，但在操作 I/O 中会导致发布失败。数值型操作参数请使用 object + complex_data_type_name。完整决策树请参阅 复杂数据类型。
• after_reasoning: 不需要 instructions: 包装
• 不支持 else if——请使用复合条件 if x and y: 或依次编写独立的 if 语句
• 保留的 @InvocableVariable 名称：model、description、label——不能用作 Apex 参数名称
• @inputs 和 @outputs 是临时的：@inputs 只能在 with 中使用；@outputs 只能在操作之后立即使用的 set/if 中使用。在 set 中使用 @inputs 会静默失败。

Lightning 类型映射的完整决策树请参阅 复杂数据类型。有关 3 阶段运行时模型，请参阅 指令解析。

架构模式

三种主要 FSM 模式。完整详情和代码请参阅 架构模式。

• 中心辐射式（最常见）：start_agent 将请求路由到专用子 Agent。每个子 Agent 都有“返回中心”的转换。切勿单独创建路由子 Agent。
• 验证关卡：在受保护的子 Agent 前进行身份验证。受保护转换上使用 available when 守卫。
• 操作后循环：操作后的检查放在 instructions: -> 的顶部，在操作完成后重新解析时触发。

评分标准

按 7 个类别、总分 100 分为每个生成的 Agent 评分：结构（15）、安全性（15）、确定性逻辑（20）、指令解析（20）、FSM 架构（10）、操作配置（10）、部署准备情况（10）。

完整评分标准请参阅 评分标准。

审查模式

用户提供现有的 .agent 文件时（例如 review path/to/file.agent）：

1. 读取文件
2. 根据 100 分制评分标准进行评分
3. 按类别列出所有问题
4. 提供修正后的代码片段
5. 提出代为应用修复

安全审查

针对 .agent 文件的 7 类大模型驱动安全审查。已集成到创作和部署的第 0 阶段。类别：身份与透明度、用户安全、数据处理、内容安全、公平性、欺骗、范围与边界。

有关完整框架、严重级别、误报指南和对抗性测试提示词，请参阅 安全审查。

发现与搭建

验证操作目标是否存在于组织中，并为缺失的目标生成存根。

请参阅 发现参考 和 搭建参考。

重要： 存根必须返回真实的数据，而不是 'TODO'。占位响应会导致 SMALL_TALK grounding，因为大模型会退回到训练数据。

部署生命周期

验证 → 部署元数据 → 发布捆绑包 → 激活。有关各阶段、错误恢复、CI/CD 和回滚，请参阅 部署参考。

模板资源

assets/agents/ 中提供可直接使用的 .agent 模板（hello-world、simple-qa、multi-subagent、production-faq、order-service、verification-gate）。另请参阅 assets/patterns/ 中的 11+ 个可复用设计模式，以及 示例 中的内嵌演练。

补充参考资料

主题	文件
架构模式	architecture-patterns.md
类型映射决策树	complex-data-types.md
不同上下文中的功能有效性	feature-validity.md
指令解析模型	instruction-resolution.md
完整的 Agent 示例	examples.md