sf-ai-agentforce

sf-ai-agentforce：标准 Agentforce 平台开发

在使用 Setup UI / Agent Builder 路径时使用此技能：声明式主题、由 Builder 管理的操作、GenAiFunction / GenAiPlugin 元数据、以 GenAiPromptTemplate 元数据形式存储的 Prompt Builder 模板、从 Apex 调用 Models API，以及自定义 Lightning 类型。

对于新的代码优先 Agent 开发，优先使用 sf-ai-agentscript。

如果工作会创建或编辑 .agent 文件——包括最终生成创作包的 Builder Script / Canvas 工作——请使用 sf-ai-agentscript。

此技能适用的任务

用户正在进行以下工作时，请使用 sf-ai-agentforce：

• 维护基于 Builder 的现有 Agent
• 在 Setup → Agentforce → Agents 中工作
• 创建或修复 GenAiFunction、GenAiPlugin 或 GenAiPromptTemplate 元数据
• 将 Builder 主题连接到 Flow / Apex / Prompt Builder 操作
• 在基于 Builder 的 Agent 中使用 Models API 或 LightningTypeBundle

以下情况不要使用此技能：

• .agent 文件或确定性 FSM 设计 → sf-ai-agentscript
• Agent 测试套件和覆盖率循环 → sf-ai-agentforce-testing
• Persona / 语气设计 → sf-ai-agentforce-persona

---

首先收集必要背景信息

请询问或推断：

• 这是 Builder / Setup UI 项目，还是代码优先的 Agent Script 项目
• 用户正在编辑 Builder 元数据，还是 .agent 创作包
• Agent 类型：Service Agent 还是 Employee Agent
• 工作目标是主题、操作、Prompt Builder 模板、Models API，还是自定义 Lightning 类型
• 已有哪些支持性的 Flow / Apex / 元数据依赖项
• 用户需要创作指导、发布帮助，还是故障排除

---

两种 Agentforce 路径

路径	技能	最适合
Builder 元数据路径	sf-ai-agentforce	声明式维护、现有 Builder Agent、由元数据驱动的操作注册
Agent Script 创作包路径	sf-ai-agentscript	代码优先的 .agent 创作、确定性路由、受版本控制的 Agent 逻辑

如果用户从头开始，并希望对流程/状态拥有更强的控制权，请引导其使用 Agent Script。

---

Builder 工作流摘要

1. 确认这是 Builder / Setup UI 项目
2. 选择 Service Agent 或 Employee Agent
3. 对于 Service Agent，配置运行用户（优先使用 sf org create agent-user）
4. 对于 Employee Agent，规划包含 <agentAccesses> 的权限集可见性
5. 通过明确的描述、范围和说明来定义主题
6. 准备支持性操作（Flow、Apex、Prompt Builder 模板）
7. 谨慎配置输入/输出
8. 验证依赖项和模板状态
9. 发布，然后激活

扩展工作流：references/builder-workflow.md

---

平台关键规则

主题质量至关重要

主题描述是规划器的路由指令，必须：

• 具体明确
• 基于场景
• 与同级主题不重叠

操作是实际目标的封装

目标类型	典型用途	注册方式
Flow	Builder 操作最安全的默认选择	GenAiFunction
Apex	通过 @InvocableMethod 实现复杂业务逻辑	GenAiFunction
Prompt Builder 模板	生成摘要/草稿/建议	GenAiFunction

提示词模板与 GenAiPromptTemplate

• 提示词模板是 Prompt Builder 中使用的通俗英文／界面术语。
• **GenAiPromptTemplate**是当前用于基于源文件开展模板工作的 Metadata API 类型。
• 优先使用当前源文件格式：genAiPromptTemplates/*.genAiPromptTemplate-meta.xml。
• 对于灵活的 Prompt Builder 模板，请按最多 5 个输入进行规划，并在需要时合并输入。
• 提示词内容应使用当前合并字段格式引用输入，例如 {!$Input:TargetRecord} 或 {!$Input:AdditionalContext}。

先部署支持性元数据

发布 Agent 本身之前，请先部署支持栈：

1. 元数据／字段（如有需要）
2. Apex（如有需要）
3. Flow（如有需要）
4. GenAiPromptTemplate / GenAiFunction / GenAiPlugin
5. 然后发布 Agent

Service Agent 运行用户

对于 Service Agent，优先使用原生 GA 命令： sf org create agent-user --target-org <alias> --json 在运行用户配置中使用返回的用户名。

Employee Agent 可见性

对于 Employee Agent，请确保最终用户获得包含 <agentAccesses> 的权限集。否则，Agent 可能处于活动状态，但在 Lightning Experience 中仍不可见。 请参阅 ../sf-permissions/references/agent-access-guide.md。

发布不会激活 Agent

发布后，请单独运行 sf agent activate。 对于自动化，优先使用 sf agent activate --api-name <AgentName> --version <n> --target-org <alias> --json，以确保推出过程可确定且机器可读。

---

元数据指南

GenAiFunction

用于注册单个可调用操作。请验证：

• 目标存在
• 目标处于活动状态／可部署
• 输入名称与目标契约一致
• 输出名称与目标契约一致
• 能力说明清楚指出何时应使用此操作

GenAiPlugin

用于将相关函数归入一个逻辑包。

GenAiPromptTemplate

用于生成内容，而非确定性业务规则。

优先使用当前元数据格式：

• 元数据类型：GenAiPromptTemplate
• 文件夹：genAiPromptTemplates/
• 文件后缀：.genAiPromptTemplate-meta.xml
• 内容位于 templateVersions 下
• 在接入依赖这些模板的操作之前，先使用已发布的模板版本

Models API

当解决方案应采用由 Apex 驱动的 AI 编排，而非仅使用 Builder 操作时使用。

自定义 Lightning 类型

当操作需要更丰富的结构化输入或输出展示时使用。

扩展参考：

• references/metadata-reference.md
• references/genaiprompttemplate.md

---

跨技能集成

推荐的编排顺序

sf-metadata → sf-apex → sf-flow → sf-ai-agentforce → sf-deploy

必需的委派

要求	委派给	原因
创建／修复 Flow	sf-flow	创建操作目标并验证 Flow
创建／修复 Apex 操作	sf-apex	确保 @InvocableMethod 和 Apex 正确无误
部署／发布	sf-deploy	编排部署流程
测试 Agent	sf-ai-agentforce-testing	执行正式测试并进行断言
Employee Agent 可见性／访问权限	sf-permissions	配置权限集 <agentAccesses>

---

高信号故障模式

症状	可能原因	接下来阅读
Builder 中没有可用操作	缺少目标元数据或尚未部署	references/metadata-reference.md
提示词操作在发布或激活时失败	模板处于 Draft 状态、缺少输入，或使用了旧版元数据结构	references/genaiprompttemplate.md
需要超过 5 个模板输入	达到灵活模板输入上限	references/genaiprompttemplate.md
Apex AI 逻辑超时	在错误的上下文中执行 Models API 操作	references/models-api.md
富输入／输出 UI 未渲染	Lightning 类型配置或前置条件不完整	references/custom-lightning-types.md
Agent 已发布但无法使用	忘记显式激活	references/cli-commands.md
Service Agent 发布／运行时失败	缺少或无效的运行用户	../sf-ai-agentscript/references/agent-user-setup.md
Employee Agent 已激活，但用户看不到	缺少 <agentAccesses> 权限集	../sf-permissions/references/agent-access-guide.md

---

参考索引

从这里开始

• references/builder-workflow.md
• references/metadata-reference.md
• references/genaiprompttemplate.md
• references/cli-commands.md

术语与模板规划

• references/prompt-templates.md
• references/models-api.md
• references/custom-lightning-types.md

评分标准

• references/scoring-rubric.md

跨技能阅读

• sf-ai-agentscript
• sf-ai-agentforce-testing
• sf-flow
• sf-apex
• sf-permissions
• sf-deploy

---

评分指南

分数	含义
90+	可以部署
80–89	表现出色，仅需少量清理
70–79	部署前需要审核
60–69	需要改进
< 60	阻止部署

完整评分标准：references/scoring-rubric.md