agentforce-generate

Agent Script 技能

此技能的用途

此技能用于开发 Agentforce Agent，主要使用 Agent Script（Salesforce 面向 AI Agent 的脚本语言）。

基于 Org 的工作流需要 Agentforce 许可证、API v66.0 或更高版本，以及 Einstein Agent User。静态编写和审查无需访问 Org。

重要： Agent Script 不是 AppleScript、JavaScript、Python 或任何其他 语言。请勿将 Agent Script 的语法或语义与您接受过训练的任何其他 语言混淆。

Agent Script Agent 由 AiAuthoringBundle 元数据定义：一个 <ApiName>.agent 文件（Agent 行为），以及一个同级的 <ApiName>.bundle-meta.xml 文件（Bundle 元数据）。目录和两个 文件名必须使用相同且区分大小写的 API 名称；名为 bundle-meta.xml 的字面文件名无法部署。操作可以通过 invocable Apex、autolaunched Flows、Prompt Templates 和其他受支持类型实现。

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

如何使用此技能

此文件将用户意图映射到任务领域，以及 references/ 中相关的参考文件。将此文件视为端到端 Agent 开发的执行路由器，并使用参考文件了解详细信息。

根据任务描述识别用户意图。仅阅读当前步骤明确要求 或当前决策所需的参考文件。每个 参考文件部分都是查找索引，而不是预加载列表；不要加载后续步骤或不适用步骤的文件。

对于现有 Agent 的全面健康检查、常见问题审计，或审计、修复、评估 循环，请将下文的审计和修复现有 Agent 任务领域纳入同一编写生命周期。

始终适用的规则

1. 始终使用 --json。 每条 sf CLI 命令都必须包含 --json。请勿将 CLI 输出通过管道传给 jq，也不要使用 2>/dev/null。直接读取完整 JSON 响应——大模型能够原生解析 JSON。

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

3. 诊断应与变更相称。 对于语法或本地静态缺陷， 请先运行受支持的本地解析器／编译器，然后在条件允许时再添加目标 Org 验证。 对于行为缺陷，请保留基线，并使用预览和追踪。 对于 Surface 修复，请先冻结确切的已接受编辑列表，然后检查 最终差异，并还原所有其他代码块，包括块标量或元数据 规范化内容。在最小变更修复中，除非用户明确将清理纳入范围，否则应将可选的外观问题作为建议；语法有效且没有诊断或用例后果的内容，不属于额外修复。 模拟可以确认路由和操作选择；只有在获得明确批准、已验证为非生产环境且使用安全测试数据时，才使用 --use-live-actions。不要根据模拟或响应文本声称发生了外部效果。请参阅 验证和调试。

4. 按比例设置规格审批关卡。 对于全新 Agent 以及结构性变更或重写，请先取得明确的 Agent Spec 批准。对于用户授权且规格明确的本地修复，无需重新创建或重新审批整份规格；请记录受影响的用例并保留现有设计。 用户提供了足够详细的设计并明确表示已获批准时，将其视为已批准的规格：不要重新创建规格，也不要要求再次批准，除非需求缺失或发生实质性变化。

5. 不要停滞。 一步成功完成后，宣布下一步并立即开始。不要等用户说“下一步是什么”或“好的，继续”。需要用户明确批准的检查点包括：（a）规则 4 要求的 Agent Spec 批准；（b）发布前的 CHECKPOINT；（c）具有破坏性或后果重大的外部操作；以及（d）技能明确提出的任何 A/B 分支（例如，设置 ADL 期间未配置 Data Cloud）。对于 ADL 索引等长时间运行的异步任务，应在后台运行，同时继续处理不依赖其结果的工作。

6. 以草稿为先的生命周期。 在常规创作期间，保持草稿迭代状态：根据需要反复编辑 .agent 和操作实现、验证、部署并预览。默认情况下，不要发布或激活。发布和激活是明确的发布操作，必须由用户确认已准备好将当前草稿提交到元数据并向最终用户开放。

7. 从一个执行块和无可变状态开始。 专注的 Agent 应直接在 start_agent 中进行推理并执行操作。只有在确有目标、指令、操作、权限或升级边界时，才添加子 Agent。仅当存在明确命名且确定性的使用方时，才添加持久状态，并为其定义完整的生命周期。常规上下文连续性依靠保留的历史记录。应用 The Zen of AgentScript 和 Posture & Determinism 中的具体检查项。

8. 使用受支持的控制流。 使用规范的条件形式，绝不生成嵌套的 if，因为 Agentforce lint 会拒绝此类写法。请参阅 Conditional Control Flow Syntax，然后运行完整的包验证。

9. 由用户决定操作实现方式。 在规划或编写规范期间，新操作默认使用 NEEDS STUB 占位符。在选择任一路径前，始终询问用户是否要扫描组织或项目中的现有实现，和/或生成新的 Apex/Flow/Prompt 实现。

10. 每个可达分支只设置一个下一步结果。 仅选择一个主要结果：回答、提问、调用操作、转换、拒绝或升级。编译器会选择子 Agent 的 system.instructions 覆盖值，而不是全局值；当前运行时会为模型组装有效的系统文本和解析后的推理文本。不要将创作结构放入面向模型的文本中。请参阅 Instruction Resolution。

11. 使用可移植的结构缩进。 新建 .agent 文件时，每级缩进使用 4 个空格。对旧文件进行局部修改时，保留其一致的缩进；如果要统一缩进整个文件，则应将其作为单独的变更进行验证。

12. 不要让提示词格式伪装成控制流。 | 文本中的缩进、编号步骤以及 Show、Ask、Call、Set 或 STOP 等词语都是模型指令，不是可执行作用域。应独立设置操作的门控。每个连续的提示词块使用一个 |；重复相邻的标记不会创建阶段或优先级。不要使用 @utils.setVariables 强制切换回合或触发另一轮推理。请参阅 Common Control-Flow Pitfalls 中的检查清单。

13. 明确由谁负责每项决策。 如果某个机器已知的精确事实会产生必须保持稳定的后果，请使用运行时谓词。如果语义意图、歧义处理、恢复或结合情境的判断使灵活性更有价值，请使用模型指令。除非提示词文本通过 {[email protected]} 注入已存储的变量值，否则模型无法读取这些值；插值可以展示一个值，但无法让模型的比较变得确定。请按照立场与确定性中的权衡测试进行判断。

14. 先在本地以低成本、可见的方式编译 AgentScript。 对于涉及现有 .agent 文件的所有创作、修复或审计任务，在进行组织端验证或提交完成报告前，先尝试使用随附的本地索引器／编译器。运行 node <skill-directory>/scripts/index-agent.mjs <agent-file>。如果无法加载 SDK，请按照 AgentScript 编译器设置中的说明操作，重试并使用其范围受限的 npm／源码回退方案。修复所有严重级别为 1 的诊断，并重新运行，直至检查通过。报告所用的提供方及精确版本或提交哈希。组织访问不能替代这项低成本的本地检查。如果两种本地设置途径都失败，请继续进行目标组织验证或范围受限的静态审查，并说明 未使用编译器 及其原因；不要让任务停滞，也不要暗示建议以后运行的命令已用于验证。离线或非交互模式不会免除这一步：它禁止网络和组织操作，但不禁止使用随附的本地编译器。

15. 确保创作包的结构可部署。 在 aiAuthoringBundles/<ApiName>/ 下，必须恰好包含匹配的一对文件：<ApiName>.agent 和 <ApiName>.bundle-meta.xml。不要将元数据文件名缩短为 bundle-meta.xml。保留脚手架生成或检索到的元数据，不要重写其架构。新的 CLI 脚手架生成的包通常使用 <bundleType>AGENT</bundleType>；现有描述符也可以采用已有的 fullName／type／status 结构，并可选包含 label 和 description。不要创建不完整的混合结构，也不要臆造字段。对 .agent 文件进行本地编译无法验证元数据文件名或 XML，因此在报告验证成功前，务必同时检查两者。

任务领域

选择与用户当前目标相符的领域。行动前请阅读对应领域中列出的参考资料；这些链接是必读说明，并非可选的参考书目。只遵循适用的工作流，并保留已满足的前置条件。正常生命周期为：设计 -> 起草 -> 验证／预览 -> 明确批准后发布。

创建 Agent

用于新建 Agent 或创作包。

1. 阅读 Design & Agent Spec， 然后将已获批准且足够详细的设计直接作为构建依据，不要重新生成或重新审批。 否则，将需求记录在保存的 Agent Spec 中，并取得明确批准。将新的操作实现 保持为 NEEDS STUB，直到用户选择复用实现、生成实现或保留占位符。
2. 阅读 CLI for Agents 中适用的章节， 并在对组织进行操作前验证目标组织的前置条件。对于文档依据，请阅读 Data Library。对于语音 Agent，请阅读 Voice Modality 和 Voice Latency。
3. 使用 Salesforce CLI 生成创作包。编辑脚手架生成的 <ApiName>.agent，并保留匹配的 <ApiName>.bundle-meta.xml。 编写前请阅读 Core Language、 Instruction Resolution 和适用的模板。
4. 运行规则 14 要求的本地编译器。当有已认证的目标组织可用时，还要在组织中验证 创作包。在实现或部署操作依赖项之前，修复阻塞性诊断问题。
5. 仅在用户选择该方案后才生成操作实现。每次验证并部署一个依赖项。
6. 预览草稿并使用 Validation & Debugging 检查跟踪记录。 覆盖真实的正常、相邻、恢复和取消路径。
7. 持续迭代草稿。只有在满足 Deploy, Publish, and Activate 中的发布门槛，且用户明确批准后，才发布并激活。

理解现有 Agent

用于用户希望了解现有包的情况。

1. 找到包及其匹配的创作包文件。
2. 阅读 Core Language，然后梳理 子 Agent 图、确定性代码块、模型指令、操作、变量和操作实现。
3. 阅读 Design & Agent Spec， 并反向编写保存的 Agent Spec。使用 Subagent Map Diagrams 绘制图表。 仅在用户要求时才为源代码添加注释。
4. 标记受支持的反模式，并区分观察到的行为与静态推断。仅在其他情况下无法解释 某项变通方案时，才加载 Known Issues。

审计并修复现有 Agent

用于“修复我的 AgentScript”、健康检查、常见问题审查，以及基线与候选版本的修复迭代。

1. 阅读 Audit and Repair，然后按顺序遵循其中 链接的范围／路径审查和修复／报告工作流。
2. 仅当制品中存在相应类别时，才使用 Diagnostic Catalog 及其针对性诊断参考。对于疑似提示词／控制流缺陷，请使用 Common Control-Flow Pitfalls 及其针对性参考。
3. 更改制品前，先冻结已接受的 Surface 编辑。对于 Structural 或 Rewrite 工作， 必须取得规则 4 要求的批准。
4. 在本地编译，并针对相同用例比较未更改的基线与候选版本，然后遵循 Audit Evaluation Loop。
5. 分别报告 Surface、Structural 和 Rewrite 评估结果。除非用户另行要求执行发布操作， 否则仅保留草稿。

审核参考文件

• 审核范围与路径审查
• 审核修复与报告
• 审核候选项验证
• 指令与路由诊断
• 操作与状态诊断
• 架构与评估诊断
• 操作与排序陷阱
• 生命周期与副作用陷阱
• AgentScript 编译器设置

修改现有 Agent

适用于对现有响应、路由、操作、子 Agent、状态流、落地来源或模态进行已批准的更改。

1. 首先了解受影响的路径。对于重大的设计变更，请更新 Agent 规范并获得批准；对于范围明确的修复，请记录受影响的用例，无需强行重写完整规范。
2. 阅读核心语言，以及本次更改所需的功能参考资料。保留无关的元数据、约定、格式和行为。
3. 直接修改现有包。只有在明确要求时才生成操作实现。
4. 在本地编译，并在条件允许时针对目标组织进行验证。预览所有已更改路径及相邻路径，并检查跟踪记录。在草稿中迭代。
5. 只有在用户另行请求发布时，才使用发布工作流。

诊断编译错误

1. 获取准确的错误报告，并运行 Rule 14 本地编译器。
2. 如果有经过身份验证的目标组织，请运行组织验证；只有在编译成功但运行时准备仍然失败时，才使用实时预览。
3. 使用验证与调试和核心语言对每个具体错误进行分类和修复。
4. 重新运行暴露该错误的检查。报告实际执行的具体检查、剩余限制，且不得将未执行的命令作为验证证据。

诊断行为或生产问题

对于本地行为问题，保留基准状态，使用符合实际情况的话语进行预览，并使用验证与调试检查跟踪记录。编辑之前，确认实际发生了哪个子 Agent、哪些操作调用、操作结果、状态更改以及最终响应。

对于生产会话或跟踪 ID，使用 agentforce-observe 进行检索和重建。只有在证据表明需要更改 AgentScript 时，才返回此处。绝不臆造不可用的操作输入、输出或模型推理过程。

部署、发布和激活

1. 阅读 Agents CLI、 元数据与生命周期 和 部署。
2. 在本地编译，并针对目标组织进行验证。部署捆绑包及其依赖项，然后运行实时预览，覆盖真实场景并检查跟踪记录。遇到阻断性结果时，不要继续。
3. 明确展示目标组织和版本状态。发布或激活前，必须获得用户明确批准。
4. 仅在获得批准后发布、激活并验证面向用户的 Agent。
5. 语音 Agent —— 接入电话渠道是单独的可选步骤；绝不要自动接入。 绑定电话号码会创建实际的路由基础设施（流程、队列、处于活动状态的 MessagingChannel），并会占用一个已配置的号码，因此只有在用户明确提出要求且已提供已配置的电话号码时才执行（确认号码确实存在——不要假设或编造号码）。如果缺少其中任何一项，请停止并说明所需信息。两项条件都满足时，通过 CLI 在无头模式下绑定；不要让用户转到 Agent Builder。请遵循无头电话 CLI。

删除或重命名 Agent

阅读 Agents CLI 和 元数据与生命周期 中有关删除和重命名的章节。列出引用和依赖项，展示确切受影响的捆绑包，并在删除前获得明确确认。重命名时，先创建并验证替代项，再删除原项；之后验证是否存在孤立的元数据。

测试 Agent

使用 agentforce-test 进行测试规范设计、安全覆盖、元数据创建、执行和结果分析。首先将 Agent 规范以及所有可到达的路由／操作映射为覆盖目标。添加安全测试或运行可能调用实时操作的测试前，请先确认。

将旧版 Agent 迁移到 Agent Script

用户想将旧版 GenAiPlannerBundle Agent 升级为 NGA AiAuthoringBundle（Agent Script）Agent。用户可能会说“迁移我的旧版 Agent”“升级到新版构建器”“转换 Agent”“开始迁移”，或提及 genAiPlannerBundle／aiAuthoringBundle 迁移。（这不同于 Einstein Bot 升级——此处指现有的 Agentforce Agent。若要将 Einstein Bot 转换为新 Agent，请改用 agentforce-bot-upgrade 技能。）

必需步骤

阅读将旧版 Agent 升级到 Agent Script，了解完整工作流、准确命令以及 NGA 与旧版的判别方法。简要步骤如下：

1. 设置项目——通过可选菜单确认目标组织——绝不要假设默认组织（显示 sf org list，标明默认组织，并要求用户明确选择）。确认存在 DX 项目（如有需要则创建）；所有检索操作都必须在项目内执行。
2. 选择旧版 Agent 版本——通过两个界面进行选择：先选择 Agent，再选择一个非 NGA 版本。排除规划器 PlannerType 为 Atlas__ConcurrentMultiAgentOrchestration 的版本（这些版本已经是 NGA）。
3. 通过 Connect API 迁移——将所选 botVersionId POST 到 migrateAgentToNga。这是会修改数据的调用；先确认组织和 ID。将其放在子 Agent 中运行，以免大型响应（内嵌的 agentScript）使上下文膨胀——只返回 bundleVersionApiName（以及 conversionWarnings、agentResponse）。
4. 检索新捆绑包——将 AiAuthoringBundle 拉取到项目中（通过 bundleVersionApiName，或在必要时将 bundleVersionId 映射到 fullName）。
5. 分析、优化、迭代——迁移只是机械式转换，不会处理 Agent Script 原语。交由 理解现有 Agent，然后交由 优化 Agent，最后进行验证／预览。

参考文件

1. 将旧版 Agent 升级为 Agent Script — 完整的分步工作流、命令和判别逻辑
2. 核心语言 — 了解迁移后的 .agent 结构

优化 Agent

1. 阅读核心语言，并使用常见控制流陷阱检查所有可达路径。
2. 仅加载适用的优化参考：数据流、确定性逻辑、引用语法、人工交接和语音就绪。
3. 报告有证据支持的改进，并在编辑前获得批准。
4. 仅应用获批的更改，在本地编译，在可行时对照组织进行验证，并报告所得证据。

管理 MCP 服务

执行任何 MCP 操作前，请阅读 MCP 服务管理。确认目标组织，使用 --json，不要在命令行中暴露机密，加入允许列表前先检查工具，并对具有破坏性或重大影响的更改要求确认。

Agent 规范

Agent 规范是此技能生成和使用的核心产物。它是一份结构化设计文档，记录 Agent 的用途、用户成果、子 Agent 图、操作及其实现、变量、子 Agent 定位、确定性控制（必要时）和行为意图。

Agent 规范会随 Agent 一同演进。创建 Agent 时内容简略（包括用途、使用场景和计划中的占位内容）；构建 Agent 时逐步完善（包括流程图、映射的操作实现、记录的定位选择，以及仅在有充分理由时添加的确定性控制）；理解现有 Agent 时通过逆向工程生成。在高级故障排查中，它至关重要，可用于对比预期行为与实际行为。测试期间，测试覆盖情况会与其对应。

对于从零开始的工作、重大设计更改，或结果会改变文档化契约的分析，请创建或更新 Agent 规范。对于范围狭窄且已有规范的修复，记录受影响的使用场景和证据即可，无需强行重写完整规范。

请阅读设计与 Agent 规范，了解 Agent 规范的结构和编写方法。

资产

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

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

• assets/agents/local-info-agent-annotated.agent — 基于 Local Info Agent 编写的完整注释示例，展示了 Agent Script 的所有主要结构，并通过行内注释说明每种结构的用途。当你需要了解这些概念如何组合成可用的 Agent，或参考文件中的针对性示例不够充分时，请阅读此示例。

• assets/agents/template-single-subagent.agent — 为兼容性保留名称的针对性起始模板，包含一个 start_agent 执行块，不包含路由器或子 Agent 块。

• assets/agents/template-multi-subagent.agent — 包含多个子 Agent 和转换的最简 Agent。复制并修改此模板以构建复杂 Agent。

• assets/agents/router-first.agent — 仅包含转换的路由器示例，使用 HyperClassifier 和简洁的路由器指令。

• assets/agents/verification-gate.agent — 身份验证／授权关卡， 可控制受保护操作的可用性。

• assets/agents/simple-qa.agent、production-faq.agent 和 order-service.agent — 完整示例，行为和操作的复杂程度依次递增。

• assets/patterns/README.md — 指向回调、输入绑定、生命周期、委派和多步骤工作流的完整针对性模式。 仅在满足模式所述的用例前提时使用。

• assets/invocable-apex-template.cls — 可调用 Apex 类的参考模板。需要复杂的 Apex 操作实现时，复制并修改此模板。

重要约束

• 使用受支持的工具获取所需证据。 使用 Salesforce CLI 和目标 org 进行基于 org 的验证与发布操作。使用已发布的 AgentScript SDK 执行本地解析／编译检查，并且仅在相关技能文档规定的范围内调用这些技能。

• 只有特定实现类型可用于操作。 例如，只有可调用 Apex（而非任意 Apex 类）可作为操作的后端。Flow 和 Prompt Template 也可能有类似限制。将操作连接到实现时，请查阅 Design & Agent Spec 参考文件，了解有效类型和桩实现方法。

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

常见问题速查

发布时出现 Internal Error, try again later： 服务器端编译失败。500 错误不会告诉你哪项检查失败——在询问用户出了什么问题之前，请依次排查以下四种原因。不要只检查原因 1 就停止。

1. access.default_agent_user 中的 Agent 类型不匹配。 员工 Agent 通常不设置 access.default_agent_user；服务 Agent 必须设置该字段（并且用户必须持有 Einstein Agent 许可证）。请参阅 Design & Agent Spec 的第 3 节。重新运行查询——不要凭空编造用户名。
2. 操作定义缺少 outputs: 块。 如果某个操作包含 target: 和 inputs:，却没有 outputs:，服务器端编译器就无法生成返回绑定。CLI validate 和 LSP 都会通过——只有发布会失败。请参阅 Known Issues 的问题 15。
3. .agent 文件中存在其他结构偏差。 与同一组织中的已知正常 bundle 进行比较： sf project retrieve start --metadata "AiAuthoringBundle:<known-working-agent>" --output-dir /tmp/diff-bundle --json 逐个关键字进行比较。检查是否缺少必需但未记录的字段、块顺序是否偏差，或 bundle 使用了工作版本中没有的 DSL 关键字。
4. 真正的临时后端错误。 如果 1–3 项都正常，且每次重试的响应 requestId 都不同，请等待 60 秒后重试一次。

预览时出现 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 节。

Agent 已发布，ADL 已编入索引（retrieverId 已填充），但所有基于知识的提问都返回空的 knowledgeSummary /“我没有这方面的信息”： Einstein Agent User 缺少 Data Cloud 访问权限。请按顺序检查以下两项：

1. 未分配权限集/PSL。 运行 Agent User Setup，第 3b.3 步中的验证查询。如果未显示 Data Cloud 权限集/PSL，请按“发现后分配”流程操作（优先级：GenieDataPlatformStarterPsl PSL → GenieUserEnhancedSecurity PS → DataCloudUser PS → DataCloudArchitect PS）。
2. 未通过权限集授予数据空间范围。 目前没有 API。前往 Setup → Permission Sets → 点击已分配的权限集 → Apps 下的 "Data Cloud Data Space Management" → Edit → 添加 ADL 的数据空间（通常为 default）→ Save。请参阅 Agent User Setup，第 3b.4 步。

快速链接（详细内容请参阅参考文档）

• 语法和执行模型：核心语言
• Agent 设计/规范流程：设计与 Agent 规范
• 姿态调节（Agent 式与确定性）：姿态与确定性
• 具体的编写不变原则：AgentScript 之道
• 根据场景选择模式：按需求选择模式
• 架构机制、HyperClassifier 路由和迁移：架构模式
• 验证、预览和追踪记录：验证与调试
• 部署/发布/激活生命周期：部署参考
• 元数据生命周期和发布问题排查：元数据与生命周期
• ADL 配置和连接：数据库参考
• Agent 访问和权限：Agent 访问指南、Agent 用户设置
• 语音模态和电话 Agent：语音模态参考
• 安全审查框架：安全审查
• 评分标准和审查评分：评分标准
• 优化模式：模式 1 — 数据流、模式 2 — 确定性逻辑、模式 3 — 引用语法、模式 4 — 升级处理
• MCP 服务注册和工具白名单：MCP 服务管理