sf-ai-agentscript

SF-AI-AgentScript 技能

Agent Script 是适用于确定性 Agentforce Agent 的代码优先路径。当用户编写 .agent 文件、构建有限状态主题流程，或需要可重复地控制路由、变量、操作和发布行为时，请使用此技能。

先从最精简的指南开始：references/activation-checklist.md

正在从 Builder UI 迁移？请使用 references/migration-guide.md

此技能适用的任务

当工作涉及以下内容时，请使用 sf-ai-agentscript：

• 创建或编辑 .agent 文件
• 确定性主题路由、守卫条件和转换
• Agent Script CLI 工作流（sf agent generate authoring-bundle、sf agent validate authoring-bundle、sf agent preview、sf agent publish authoring-bundle、sf agent activate）
• 槽位填充、指令解析、操作后循环或 FSM 设计

当用户正在进行以下工作时，请委派给其他技能：

• 维护 Builder 元数据 Agent（GenAiFunction、GenAiPlugin、GenAiPromptTemplate、Models API、自定义 Lightning 类型）→ sf-ai-agentforce
• 设计角色形象 / 语气 / 声线 → sf-ai-agentforce-persona
• 构建正式测试计划或覆盖率循环 → sf-ai-agentforce-testing

如果用户正在 Builder Script / Canvas 视图中操作，但最终产物是 .agent 编写包，请继续使用 sf-ai-agentscript。

---

合理把握确定性程度

• 确定性是一个调节旋钮，而非最终目标。
• 当“基本正确”无法接受时，请使用 Agent Script：例如需要关卡、强制顺序、明确的状态转换、合规性或漂移控制。
• 如果工作流完全静态且线性，请使用 Flow 或 Apex，而不是编写对话脚本。
• 优先采用确定性外壳：确定性入口 / 关卡 → 灵活的中间部分 → 确定性收尾。
• 确定性并非越高越好。先从最简方案开始，只加固出现路由漂移、顺序执行失败或合规风险的部分。

---

首先收集必要的上下文

询问或推断以下信息：

• Agent 的用途，以及 Agent Script 是否确实适合
• Service Agent 还是 Employee Agent
• 目标 org 和发布意图
• 预期的操作 / 目标（Flow、Apex、PromptTemplate 等）
• 请求属于编写、验证、预览还是发布问题排查

---

激活检查清单

编写或修复任何 .agent 文件之前，请先确认以下各项：

1. 恰好有一个 start_agent 块
2. 不混用制表符和空格
3. 布尔值使用 True / False
4. 不使用 else if，也不使用嵌套 if
5. 没有顶层 actions: 块
6. set 表达式中没有 @inputs
7. linked 变量没有默认值
8. linked 变量不使用 object / list 类型
9. 明确使用 agent_type
10. 一致地使用 @actions. 前缀
11. 仅当 X 是带有 target: 的主题级操作定义时，才使用 run @actions.X
12. 不要直接基于原始 @system_variables.user_input contains/startswith/endswith 分支处理意图路由
13. 对于提示词模板输出，优先使用 is_displayable: False + is_used_by_planner: True
14. 不要假定 @outputs.X 是标量——在分支或赋值前检查输出架构

完整版本请参阅 references/activation-checklist.md。

---

不可妥协的规则

1) Service Agent 与 Employee Agent

Agent 类型	必需项	禁止 / 注意事项
AgentforceServiceAgent	有效的 default_agent_user、正确的权限、目标 org 检查，优先使用 sf org create agent-user	不得在没有真实 Einstein Agent User 的情况下发布
AgentforceEmployeeAgent	明确指定 agent_type	不得提供 default_agent_user

完整详情：references/agent-user-setup.md

2) 建议的顶层代码块约定

为保持本技能中的示例和评审一致，请按以下顺序排列：

config:
variables:
system:
connection:
knowledge:
language:
start_agent:
topic:

Salesforce 官方资料中的顶层代码块顺序各不相同，本地验证证据也表明，多个顺序都能通过编译。请将其视为风格约定，而非单独的正确性问题或发布阻塞项。

3) 关键配置字段

字段	规则
developer_name	必须与文件夹／捆绑包名称一致
description	公共文档／示例应使用此配置字段
agent_type	每次都要显式设置
default_agent_user	仅适用于 Service Agents

为保持兼容性，本地工具也接受 agent_description:，但本技能的公共文档和示例应优先使用 description:。

4) 应立即视为失败的语法阻塞项

• else if
• 嵌套 if
• 仅包含注释的 if 语句体
• 顶层 actions:
• 调用级别的 inputs: / outputs: 代码块
• 保留变量／字段名称，如 description 和 label

规范规则集：references/syntax-reference.md 和 references/validator-rule-catalog.md

---

建议的工作流

建议的编写工作流

阶段 1 — 设计 Agent

• 判断问题是否足够确定，适合使用 Agent Script
• 将主题建模为状态，将转换建模为边
• 仅定义真正需要的变量

阶段 2 — 编写 .agent

• 先创建 config、system、start_agent 和主题
• 添加具有完整 inputs: 和 outputs: 的目标绑定工具
• 使用 available when 实现确定性的工具可见性
• 在分支判断前，将原始意图／验证信号规范化为布尔值或枚举；对于关键控制流，避免直接对原始用户话语进行子字符串检查
• 将操作后的检查放在 instructions: -> 的顶部

默认编写方式

• 默认直接编写 .agent 并在源代码管理中进行编辑。
• 仅当用户需要本地捆绑包脚手架时，才使用 sf agent generate authoring-bundle --no-spec。
• 将 sf agent generate agent-spec 视为可选的构思／主题引导方式，而非默认工作流。
• 不要引导 Agent Script 用户使用 sf agent create 或 sf agent generate template。

阶段 3 — 持续验证

写入／编辑时已自动运行验证。发布前请使用 CLI：

sf agent validate authoring-bundle --api-name MyAgent -o TARGET_ORG --json

验证器会检查结构、运行时注意事项、目标就绪情况以及组织感知型 Service Agent 检查。规则 ID 位于 references/validator-rule-catalog.md。

阶段 4 — 预览冒烟测试

发布前请使用预览循环：

• 制定 3–5 条冒烟测试话语
• 使用 start / send / end 子命令启动预览，不要直接运行 sf agent preview
• 如果使用 --authoring-bundle，务必明确选择一种模式：--simulate-actions 或 --use-live-actions
• 检查主题路由／工具调用／安全性／依据
• 修复后重新运行，最多 3 次

完整循环：references/preview-test-loop.md

阶段 5 — 发布并激活

sf agent publish authoring-bundle --api-name MyAgent -o TARGET_ORG --json

# Manual activation
sf agent activate --api-name MyAgent -o TARGET_ORG

# CI / deterministic activation of a known BotVersion
sf agent activate --api-name MyAgent --version <n> -o TARGET_ORG --json

发布不会激活 Agent。 对于自动化，优先使用 --version <n> --json，以确保激活过程具有确定性且机器可读。

确定性构建块

这些会作为代码执行，而非建议：

• 条件语句
• available when 守卫
• 变量检查
• 直接使用 set / transition to
• 仅当 X 是带有 target: 的主题级操作定义时，才运行 run @actions.X
• 将变量注入面向 LLM 的文本

重要区别：

• 确定性：set、transition to，以及针对带目标的主题操作运行 run @actions.X
• 由 LLM 指示：reasoning.actions: 实用工具 / 委派，例如 @utils.setVariables、@utils.transition，以及 {[email protected]} 指令引用

如果你需要为当前建模为推理级实用工具的内容实现确定性行为，可以：

• 将其改写为直接使用 set / transition to，或
• 将其提升为主题级带目标操作，并运行该操作

请参阅 references/instruction-resolution.md 和 references/architecture-patterns.md。

---

跨技能集成

跨技能编排

任务	委派给	原因
构建 flow:// 目标	sf-flow	流程创建 / 验证
构建 Apex 操作目标	sf-apex	@InvocableMethod 和业务逻辑
测试主题路由 / 操作	sf-ai-agentforce-testing	正式测试规范和修复循环
部署 / 发布	sf-deploy	部署编排

---

高信号故障模式

症状	可能原因	接下来阅读
发布期间出现 Internal Error	Service Agent 用户无效或缺少操作 I/O	references/agent-user-setup.md、references/actions-reference.md
提示词模板操作出现 invalid input/output parameters	目标模板处于 Draft 状态——请先激活	references/action-prompt-templates.md
解析器拒绝条件语句	else if、嵌套 if、空的 if 主体	references/syntax-reference.md
操作目标问题	缺少 Flow / Apex 目标、Flow 未激活、架构错误	references/actions-reference.md
提示词模板运行成功，但用户看到的响应为空	提示词输出标记为 is_displayable: True	references/production-gotchas.md、references/action-prompt-templates.md
提示词操作运行成功，但规划器的行为就像缺少输出	输出对直接显示不可见，但对规划器可见	references/production-gotchas.md、references/actions-reference.md
run @actions.X 出现 ACTION_NOT_IN_SCOPE	run 指向实用工具、委派或未解析的操作，而不是主题级别的目标绑定定义	references/syntax-reference.md、references/instruction-resolution.md
确定性取消 / 修改 / URL 检查的行为不一致	将原始 @system_variables.user_input 匹配或字符串方法守卫用作控制流关键验证	references/syntax-reference.md、references/production-gotchas.md
@outputs.X 比较或赋值的行为出乎预期	操作输出是结构化 / 包装值，而非纯标量	references/actions-reference.md、references/syntax-reference.md
预览与运行时结果不一致	链接变量 / 上下文 / 已知平台问题	references/known-issues.md
验证通过但发布失败	组织特定的用户 / 权限 / 取回后问题	references/production-gotchas.md、references/cli-guide.md

---

参考资料索引

从这里开始

• references/activation-checklist.md
• references/syntax-reference.md
• references/actions-reference.md

发布 / 运行时安全

• references/agent-user-setup.md
• references/production-gotchas.md
• references/customer-web-client.md
• references/known-issues.md

架构 / 推理

• references/architecture-patterns.md
• references/instruction-resolution.md
• references/fsm-architecture.md
• references/patterns-quick-ref.md

验证 / 测试 / 调试

• references/preview-test-loop.md
• references/testing-guide.md
• references/debugging-guide.md
• references/validator-rule-catalog.md

Examples / scaffolds

• references/minimal-examples.md
• references/migration-guide.md
• assets/
• assets/agents/
• assets/patterns/

Project documentation

• references/version-history.md
• references/sources.md

---

Score Guide

Score	Meaning
90+	Deploy with confidence
75–89	Good, review warnings
60–74	Needs focused revision
< 60	Block publish

Full rubric: references/scoring-rubric.md

---

Official Resources

• Agent Script Documentation
• Agent Script Recipes
• Agentforce DX Guide
• references/official-sources.md