developing-agentforce

Agent Script 技能

此技能的用途

此技能用于开发 Agentforce 智能体，主要使用 Agent Script，即 Salesforce 为 AI 智能体打造的脚本语言。

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

Agent Script 智能体由 AiAuthoringBundle 元数据定义：一个 .agent 文件（智能体行为）以及 bundle-meta.xml（捆绑包元数据）。操作可通过 invocable Apex、自动启动的 Flows、提示词模板及其他受支持的类型实现。

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

如何使用此技能

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

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

始终适用的规则

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

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

3. 先诊断，再修复。 验证或调试 Agent 行为时，务必使用 --use-live-actions 预览创作包。发送话语，然后读取生成的会话跟踪记录，以此了解 Agent 的行为。跟踪文件会显示子 Agent 的选择、操作的输入／输出以及 LLM 的推理。没有这些依据时，不要修改 .agent 文件或操作实现。有关跟踪文件位置和诊断模式，请参阅验证与调试。

4. 规范审批是硬性关卡。 未经用户明确批准，不得在创建 Agent 规范后继续。

5. 不要停滞。 某个步骤成功完成后，告知用户下一步并立即开始。不要等用户询问“接下来做什么”或说“好，继续”。只有以下检查点需要用户明确批准：（a）Agent 规范审批；（b）发布前检查点；（c）技能明确提出的任何 A/B 分支（例如，设置 ADL 期间未配置 Data Cloud）。ADL 索引等长时间运行的异步任务应在后台运行，同时技能继续执行不依赖其结果的工作。

6. 以草稿为先的生命周期。 常规创作期间，应持续迭代草稿：按需编辑 .agent 和操作实现、验证、部署和预览。默认不要发布／激活。发布和激活属于明确的发布操作，必须由用户确认其已准备好将当前草稿提交为元数据并向最终用户开放。

7. 默认采用 Agentic 方式，必要时才固定。 对每个子 Agent，采用满足其要求的最高 Agentic 程度；只有在监管／信任关卡或观察到故障时，才添加确定性控制。详细的执行方式规则请参阅执行方式与确定性。

8. 不要嵌套使用 if 或 else if。 Agent Script 只支持扁平的 if／else 块。不支持 else if、在 else 中使用 if，也不支持在 if 中使用 if。对于多分支逻辑，请使用顺序排列的 if 语句或复合条件（if A and B:）。嵌套结构会导致编译静默失败。

9. 操作实现由用户决定。 在规划／规范阶段，新操作默认使用 NEEDS STUB 占位符。采取任何一种方案之前，都必须询问用户是否要扫描 org／项目以查找现有实现，和／或生成新的 Apex／Flow／Prompt 实现。

任务领域

以下每个任务领域都有必需步骤。请严格按照原文顺序执行。默认流程为：设计 -> 草稿实现循环 -> 验证／预览循环 -> 经用户明确批准后发布。

创建 Agent

用户希望从头开始构建 Agent。务必使用 Agent Script。与用户合作，以通俗语言了解 Agent 的用途、子 Agent 和操作，不要使用 Salesforce 专用术语。

必需步骤

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

1. 设计——阅读 Design & Agent Spec 以起草 Agent 规范。在规划期间，将所有新操作默认标记为 NEEDS STUB 占位项。开始实施前，询问用户想要哪种实施路径：
   • 路径 A：仅保留占位项（暂不实施）
   • 路径 B：扫描并复用现有操作
   • 路径 C：生成新操作 仅当用户明确选择路径 B 或 C 时，才运行扫描（读取 sfdx-project.json、搜索 @InvocableMethod、AutoLaunchedFlow、提示词模板、外部服务注册、标准可调用操作和自定义对象）。 如果 Agent 的用途涉及基于文档回答问题（例如“根据我们的产品手册回答客户问题”“根据政策指南作答”“根据 PDF 回答常见问题”），请询问用户：“此 Agent 会根据文档集合（PDF/DOCX/TXT）回答问题吗？如果会，文件路径是什么？” 在规范的 “Knowledge Grounding” 部分记录该路径。此时——即需求收集期间——询问这一点至关重要：ADL 索引需要几分钟，因此我们希望在规范获批前记录文件路径，并尽早启动配置。 始终将 Agent 规范保存为文件。
2. 暂停，等待用户批准 Agent 规范。 向用户展示规范（如有，则包括 Knowledge Grounding 部分）。请用户批准或提供反馈。未经批准，不得继续。 获批后，除非某一步失败，否则继续执行，不要暂停。
3. 验证环境前提条件——阅读 Design & Agent Spec 的第 3 节（环境前提条件）。根据设计中的 Agent 类型验证组织环境：
   • 员工 Agent：确认配置块不包含 connection messaging: 或 MessagingSession 关联变量。如果存在，则移除。**例外：**如果 Agent 有 knowledge: 块（使用 AnswerQuestionsWithKnowledge），即使是员工 Agent，也必须设置 default_agent_user——平台会在运行时将基于知识的 Agent 视为需要 Einstein Agent User 上下文。查询 Agent 用户并将其加入配置。完整的员工 Agent 示例请参阅 Examples。
   • 服务 Agent：查询组织中是否存在 Einstein Agent User。如果存在，请向用户确认用户名。如果不存在，则指导用户创建。创建步骤请参阅 CLI for Agents 第 12 节；所需权限请参阅 Agent User Setup。 **3b. 启动 ADL 配置（仅当规范包含 Knowledge Grounding 部分时）。**阅读 Data Library Reference。运行步骤 0 的预检：SELECT COUNT() FROM DataKnowledgeSpace（检查 DC 是否已配置），然后运行 sf agent adl list（检查 ADL 服务状态）。如果 DC 尚未配置，则向用户提供该参考中的 A/B 选项。如果 DC 已配置，但 ADL 服务返回 400 INTERNAL_ERROR，则说明“DC 正常，ADL 故障”路径，并在本次运行中跳过知识 grounding。如果两项检查都通过，则运行 sf agent adl create（参考中的步骤 1）以获取 libraryId。仅根据 libraryId 计算 rag_feature_config_id = "ARFPC_<libraryId>"——编写 bundle 只需此值。然后在后台启动上传和索引流程（参考中的步骤 2–6），同时继续编写。根据规则 5，不要等待异步索引完成；只有运行时查询才需要 retrieverId（在步骤 8 中检查）。同时为 Agent 用户启动 Data Cloud 权限集分配——发现后再分配的流程请参阅 Agent User Setup 的步骤 3b。 环境验证完成前，不得继续生成代码（ADL 配置可以在后台继续运行）。
4. 生成编写 bundle—— sf agent generate authoring-bundle --json --no-spec --name "<Label>" --api-name <Developer_Name>
5. 编写代码——阅读 Core Language，了解语法、块结构和反模式。使用参考文件和模板编辑生成的 .agent 文件。不要手动创建 .agent 或 bundle-meta.xml 文件。如果步骤 3b 生成了 libraryId，则按照 Data Library Reference 中的 “Wiring the ADL into Agent Script” 一节，加入顶层 knowledge: 块以及 AnswerQuestionsWithKnowledge 操作连接。模板 assets/agents/knowledge-grounded.agent 可作为复制后修改的起点。
6. 验证编译—— sf agent validate authoring-bundle --json --api-name <Developer_Name> 如果验证失败，请阅读 Validation & Debugging 进行诊断和修复，然后重新验证。生成操作实现前，必须先修复语法和结构错误。
7. 生成操作实现（仅限用户明确要求的路径）——只有用户明确要求生成新实现时，才运行此步骤（步骤 1 中的路径 C）。对每个标记为 NEEDS STUB 的操作，运行： sf template generate apex class --name <ClassName> --output-dir <PACKAGE_DIR>/main/default/classes 使用 Design & Agent Spec 中的可调用模式替换类主体。必须部署： sf project deploy start --json --metadata ApexClass:<ClassName> 生成并部署下一个占位实现前，必须先修复部署错误。
8. 验证行为——阅读 Validation & Debugging，了解预览工作流和会话跟踪分析。 如果步骤 3b 配置了 ADL，在发送任何 grounding 测试语句前，确认知识库可查询：运行 sf agent adl get -i $LIBRARY_ID，并检查是否存在 retrieverId（参阅 Data Library Reference 的步骤 6）。如果仍为 null，则等待并重新轮询——暂时不要预览，否则 Agent 将返回空的 knowledgeSummary，反幻觉保护也会拒绝所有语句。 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>" 冒烟测试要求（参阅 Validation & Debugging 中的 Utterance Derivation）：
   • 测试所有路由分支，而不仅是正常路径。每个分支使用多种措辞。
   • 使用真实的语句——写出人们实际会输入的内容，而不是关键词。
   • 每条语句发送后，都要查看跟踪，确认操作确实已触发（存在 FunctionStep）。不要只相信 Agent 的文本回复——Agent 可能声称执行了操作，却没有实际调用。
   • 像人工测试人员一样对照 Agent 规范评估：检查对话流程、是否遵循指令、是否有不必要的重复，以及回复质量。如果规范要求“确认一次”，而 Agent 确认了两次，那就是错误——应予以修复。 如果行为偏离 Agent 规范，请修复 .agent 文件并重新预览。遇到复杂问题时，切换到 Diagnose Behavioral Issues 工作流。修正问题后再返回。 检查点——除非用户明确要求发布，否则继续在草稿中迭代。 如果用户要求发布，只有满足以下所有条件后才能继续发布：
   • validate authoring-bundle 通过且没有错误
   • 已通过实时预览（--use-live-actions）使用真实语句测试所有路由分支
   • 跟踪确认子 Agent 路由正确、操作已调用（存在 FunctionStep），且行为符合规范
   • 用户明确批准部署
   • 如果 Agent 有 knowledge: 块：已为 Einstein Agent User 分配 Data Cloud 权限集/PSL。验证两项：

     sf data query --json -q "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username='<agent_user>'"
     sf data query --json -q "SELECT PermissionSetLicense.DeveloperName FROM PermissionSetLicenseAssign WHERE Assignee.Username='<agent_user>'"
     

     合并结果中必须包含 GenieDataPlatformStarterPsl、GenieUserEnhancedSecurity、DataCloudUser 或 DataCloudArchitect 之一。如果均未出现，请按照 Agent User Setup，第 3b 步中的流程先发现再分配，并在继续前重新验证。如果已分配 Data Cloud 权限集，但冒烟测试中的 grounding 查询返回空的 knowledgeSummary，则还需要为该权限集授予 Data Space 范围——此操作只能通过 UI 完成，参阅 Agent User Setup，第 3b.4 步。
9. 发布（明确的发布步骤）——只有用户确认准备好将此草稿提交为元数据后，才能执行。发布会验证元数据结构，而非 Agent 行为。每次发布都会创建永久版本号。 sf agent publish authoring-bundle --json --api-name <Developer_Name> 如果发布失败，请按照 Metadata & Lifecycle 第 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 Access Guide，配置权限并分配访问权限。

参考文件

1. 面向 Agent 的 CLI — generate、validate、deploy、publish、activate 的精确命令语法；第 12 节介绍 Einstein Agent 用户创建
2. 核心语言 — 执行模型、语法、块结构、反模式
3. 设计与 Agent 规范 — 子 Agent 图设计、流程控制模式、Agent 规范编写、操作实现分析；第 3 节介绍环境先决条件
4. 子 Agent 映射图 — 用于可视化 Agent 子 Agent 图的 Mermaid 图表约定
5. 姿态与确定性 — 默认的 Agent 式姿态，以及有明确原因的确定性控制
6. Agent 用户设置与权限 — 权限集分配、对象权限、跨子 Agent 验证
7. 元数据与生命周期 — 目录结构、捆绑包元数据；publish 故障排查
8. 验证与调试 — 验证 Agent 能否编译，通过预览确认行为
9. Agent 访问指南 — 最终用户访问权限、可见性故障排查
10. 已知问题 — 仅在修复代码后错误仍持续存在时加载
11. 按需求分类的模式 — 将场景映射到模式，帮助确定架构和流程选项
12. 架构模式 — 路由器优先机制、验证关卡、工作流内的线性模式
13. 复杂数据类型 — 类型映射决策树
14. 安全审查 — 7 类安全审查
15. Discover 参考 — 目标发现 CLI
16. Scaffold 参考 — 存根生成 CLI
17. Deploy 参考 — 部署生命周期、错误恢复
18. 数据库参考 — 配置 SFDRIVE Agentforce 数据库，并通过 knowledge: 块和 AnswerQuestionsWithKnowledge 操作将其接入 .agent

理解现有 Agent

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

必需步骤

1. 定位 Agent — 阅读 sfdx-project.json，确定程序包目录。在其中找到 AiAuthoringBundle 目录。阅读 .agent 文件和 bundle-meta.xml。
2. 阅读代码 — 在解析 .agent 文件之前，先阅读核心语言，了解语法和执行模型。
3. 映射操作实现 — 对每个带有 target 的操作，在项目中找到其实现（Apex 类、Flow、提示词模板）。记录输入/输出契约。
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 结构。

必需步骤

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

1. 理解现有 Agent — 如果不存在 Agent Spec，请先按照上文的“理解现有 Agent”工作流进行逆向工程。
2. 更新 Agent Spec — 阅读 设计与 Agent Spec，了解流程控制模式和现有操作分析。修改 Agent Spec，使其反映预期变更。默认将新操作设为 NEEDS STUB 占位项。询问用户希望选择哪条路径：
   • 路径 A：仅保留占位项
   • 路径 B：扫描并复用现有操作
   • 路径 C：生成新操作 只有用户明确选择路径 B 或 C 时才运行扫描。 如果修改涉及添加、替换或移除知识接地，请询问： “此 Agent 是否会根据文档语料库（PDF/DOCX/TXT）回答问题？如果会，文件路径是什么？” 在更新后的 Spec 中添加 “知识接地” 部分并记录该路径。现在就询问，也就是在更新 Spec 期间询问，可以让用户审批 ADL 变更，并让我们随后立即开始配置。 始终将更新后的 Agent Spec 保存为文件。
3. 暂停，等待用户批准更新后的 Agent Spec。 向用户展示 Spec（如果存在，也包括“知识接地”部分）。请用户批准或提供反馈。未经批准不得继续。 获得批准后，除非某个步骤失败，否则继续执行，不要暂停。
4. 开始配置 ADL（仅当 Spec 中包含“知识接地”部分时）。
   • 如果 .agent 中已有 knowledge: 块，其中的 rag_feature_config_id 已填充，且用户会继续使用同一知识库，则复用该配置。跳过配置步骤。（此处无需确认 retrieverId ——该检查移至步骤 8。）
   • 如果需要新的 ADL，按照创建工作流执行相同流程：阅读 数据库参考，运行步骤 0 的预检（sf agent adl list），并且（如果 DC 已就绪）运行步骤 1（sf agent adl create）以获取 libraryId。仅根据 libraryId 计算 rag_feature_config_id = "ARFPC_<libraryId>" ——这足以编写 bundle。开始上传和索引流程（参考步骤 2–6），并在后台进行，同时继续执行步骤 5（编辑代码）。根据规则 5，不要等待异步索引完成。还要为 Agent 用户开始分配 Data Cloud 权限集 ——参阅 Agent 用户设置，步骤 3b。
   • 如果此次修改不涉及知识接地，则跳过此步骤。
5. 编辑代码 — 阅读 核心语言，了解语法和反模式。编辑 .agent 文件以实现已批准的变更。如果步骤 4 生成了 libraryId，请根据 数据库参考 添加或更新 knowledge: 块和 AnswerQuestionsWithKnowledge 操作。
6. 验证编译 — sf agent validate authoring-bundle --json --api-name <Developer_Name> 如果验证失败，请阅读 验证与调试 以进行诊断和修复，然后重新验证。
7. 生成新操作的实现（仅适用于用户明确要求的路径） — 只有用户明确要求生成新实现（步骤 2 中的路径 C）时，才运行此步骤。对于每个标记为 NEEDS STUB 的新操作： sf template generate apex class --name <ClassName> --output-dir <PACKAGE_DIR>/main/default/classes 将类主体替换为 设计与 Agent Spec 中的可调用模式。始终部署： sf project deploy start --json --metadata ApexClass:<ClassName> 始终先修复部署错误，再生成和部署下一个占位项。 如果没有新增操作，则跳过。
8. 验证行为 — 阅读 验证与调试，了解预览工作流和会话跟踪分析。 如果步骤 4 配置了新的 ADL，在发送任何基于知识接地的测试话语之前，确认该知识库可查询：运行 sf agent adl get -i $LIBRARY_ID 并检查是否存在 retrieverId（数据库参考，步骤 6）。如果仍为 null，请等待并再次轮询 ——暂时不要预览，否则 Agent 会返回空的 knowledgeSummary，反幻觉防护机制会拒绝每条话语。 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>" 冒烟测试要求（参阅 验证与调试 中的“话语推导”）：
   • 先测试变更路径，再测试相邻路径以发现回归问题。
   • 测试变更影响到的所有路由分支。每个分支使用多种措辞。
   • 使用真实的话语 ——写出人们实际会输入的内容，而不是关键词。
   • 每条话语发送后，都要查看跟踪记录，确认操作确实已触发（存在 FunctionStep）。不要仅凭 Agent 的文本回复作判断。
   • 根据 Agent Spec 评估对话流程、指令遵循情况、不必要的重复和回复质量。 如果行为与 Agent Spec 不一致，请修复 .agent 文件并重新预览。对于复杂问题，请切换到 诊断行为问题 工作流。 检查点 ——除非用户明确要求发布，否则请继续进行草稿迭代。 如果用户要求发布，只有以下条件全部满足时才能继续：
   • validate authoring-bundle 验证通过，且错误数为零
   • 已使用真实话语进行实时预览（--use-live-actions），涵盖所有路由分支
   • 跟踪记录确认子 Agent 路由正确、操作已调用（存在 FunctionStep），且行为符合 Spec
   • 用户明确批准部署
   • 如果 Agent 包含 knowledge: 块：Einstein Agent 用户已分配 Data Cloud 权限集/PSL。验证两者：

     sf data query --json -q "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username='<agent_user>'"
     sf data query --json -q "SELECT PermissionSetLicense.DeveloperName FROM PermissionSetLicenseAssign WHERE Assignee.Username='<agent_user>'"
     

     两条查询的合并结果中必须出现 GenieDataPlatformStarterPsl、GenieUserEnhancedSecurity、DataCloudUser 或 DataCloudArchitect 之一。如果均未出现，请执行 Agent 用户设置，步骤 3b 中的先发现、后分配流程，并在继续之前重新验证。如果已分配 Data Cloud 权限集，但基于知识接地的冒烟测试查询返回空的 knowledgeSummary，还需要在该权限集上授予 Data Space 范围 ——仅限 UI 操作，参阅 Agent 用户设置，步骤 3b.4。
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。

参考文件

1. 面向 Agent 的 CLI — validate、deploy、preview、publish、activate 的精确 命令语法
2. 核心语言 — 语法、 反模式
3. 设计与 Agent 规范 — Agent 规范更新、操作实现分析
4. 验证与调试 — 编译诊断、预览工作流、会话跟踪分析
5. 数据库参考 — ADL grounding 的配置和 Agent Script 接线
6. 已知问题 — 仅在修复代码后错误 仍持续存在时加载

诊断编译错误

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

必需步骤

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

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 及其依赖项、发布以提交版本，然后激活使其上线。

必需步骤

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

1. 验证编译 — sf agent validate authoring-bundle --json --api-name <Developer_Name> 如果验证失败，请勿继续。
2. 部署捆绑包及其依赖项 — 阅读 元数据与生命周期，了解依赖项管理和部署命令。将 AiAuthoringBundle、所有操作实现（Apex 类、Flows、提示词模板）及其依赖项部署到组织。
3. 实时预览 — 阅读 验证与调试，了解预览工作流和会话跟踪分析。 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 通过且无错误
   • 已使用真实话语测试实时预览（--use-live-actions），覆盖所有路由分支
   • 跟踪记录确认子 Agent 路由和操作调用正确（存在 FunctionStep），且行为符合规范
   • 用户明确批准部署
4. 发布（明确的发布步骤） — 发布会验证元数据结构，而非 Agent 行为。请勿在开发／测试循环中发布。仅在用户确认提交此草稿后，并且在激活之前，将发布作为最后一步。 sf agent publish authoring-bundle --json --api-name <Developer_Name> 如果发布失败，请先按照 元数据与生命周期中的发布失败排查操作，再重试。
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 访问指南，配置权限并分配访问权限。

参考文件

1. 面向 Agent 的 CLI — 部署、发布、激活和停用的准确 命令语法
2. 验证与调试 — 编译验证、预览工作流
3. 元数据与生命周期 — 依赖项管理、部署命令；发布故障排查
4. Agent 访问指南 — 最终用户 访问权限、可见性故障排查
5. 已知问题 — 仅在部署 卡住、发布失败或激活意外失败时加载

诊断生产问题

用户的 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 的处理方式、确定性控制（需要时）和行为意图。

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 Subagent Map 图表。

• assets/agents/local-info-agent-annotated.agent — 基于 Local Info Agent 的完整注释示例，展示了 Agent Script 的所有主要结构，并附有行内注释，解释使用每种结构的原因。需要了解各概念如何组合成可用 Agent 的具体参考时，或者参考文件中的专题示例不够充分时，可阅读此示例。

• assets/agents/template-single-subagent.agent — 只有一个子 Agent 的最简 Agent。复制并修改它，用于简单 Agent。

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

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

重要限制

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

• 只有特定实现类型可用于操作。 例如，操作只能由可调用 Apex（而非任意 Apex 类）实现。Flows 和 Prompt Templates 也可能有类似限制。将操作关联到实现时，请查阅 Design & Agent Spec 参考文件，了解有效类型和桩代码编写方法。

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

常见问题快速参考

发布时出现 Internal Error, try again later： 服务器端编译失败。500 错误不会告诉你哪项检查未通过——在询问用户问题出在哪里之前，按顺序排查以下四种原因。切勿在原因 1 处停止。

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

预览时出现 Unable to access Salesforce Agent APIs...： default_agent_user 缺少权限。请参阅 Agent 用户设置与权限。不要通过发布来修复——--use-live-actions 不需要已发布的 Agent。

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

当前子 Agent 的操作可正常运行，但 Agent 仍然出现权限错误： Planner 会在启动时验证所有子 Agent 中的所有操作。只要有一项缺少权限，整个 Agent 就会失败。

Apex 操作在实时预览中返回空结果，但在模拟模式下正常： WITH USER_MODE 加上缺少对象权限会导致静默失败（0 行，没有错误）。请参阅 Agent 用户设置与权限 的第 6.2 节。

Agent 已发布，ADL 已编入索引（retrieverId 已填充），但所有有依据的问题都返回空的 knowledgeSummary / “我没有相关信息”： Einstein Agent 用户缺少 Data Cloud 访问权限。请按顺序检查以下两项：

1. 未分配权限集/PSL。 运行 Agent 用户设置，第 3b.3 步中的验证查询。如果没有显示 Data Cloud 权限集/PSL，请运行先发现再分配的流程（优先级：GenieDataPlatformStarterPsl PSL → GenieUserEnhancedSecurity PS → DataCloudUser PS → DataCloudArchitect PS）。
2. 权限集未授予数据空间范围。 目前没有 API。转到设置 → 权限集 → 点击已分配的权限集 → 在“应用”下选择“Data Cloud 数据空间管理” → 编辑 → 添加 ADL 的数据空间（通常为 default）→ 保存。请参阅 Agent 用户设置，第 3b.4 步。

快速链接（详细内容请参阅参考资料）

• 语法和执行模型：核心语言
• Agent 设计/规范流程：设计与 Agent 规范
• 姿态调节（Agent 式与确定性）：姿态与确定性
• 按场景选择模式：按需求选择模式
• 架构机制和迁移：架构模式
• 验证、预览和跟踪记录：验证与调试
• 部署/发布/激活生命周期：部署参考
• 元数据生命周期和发布故障排查：元数据与生命周期
• ADL 配置和连接：数据库参考
• Agent 访问和权限：Agent 访问指南、Agent 用户设置
• 安全审查框架：安全审查
• 评分标准和审查评分：评分标准