Agentforce Actions 构建与增强指南

构建和增强 Agentforce Actions

Actions 是 Agentforce Agent 执行任务和交互数据的构建块。你可以创建自定义 Action 来扩展 Agent 的能力，通过富界面和详细响应增强用户体验。

功能/API	描述	Create	Enhance
Apex REST Actions	从 Apex REST 类创建 Action（使用 Vibes 生成 OpenAPI）	✓
AuraEnabled Actions	从 @AuraEnabled Apex Controller 方法创建 Action	✓
Named Query Actions	创建自定义 SOQL 查询并暴露为 Action	✓
InvocableMethod Actions	使用 @InvocableMethod 注解创建自定义 Action	✓
Lightning Types	使用自定义 LWC 改进复杂输入/输出的 UI		✓
Global Copy	在自定义组件中增强复制功能		✓
Apex Citations	用引用（Citations）扩展自定义 Action		✓

创建与增强 Actions 概览

创建 Actions：

• Apex REST Actions：使用 Vibes Extension 为 @RestResource Apex 类生成 OpenAPI 3.0 文档 → 部署类+OpenAPI+元数据到 Org 的 API Catalog → 在 Agentforce Builder 中创建基于类方法的 Agent Action
• AuraEnabled Actions：为 @AuraEnabled 注解的 Apex Controller 方法生成 OpenAPI → API Catalog → Agent Builder
• Named Query Actions：在 Setup 中创建自定义 SOQL（命名查询）→ 在 Agent Creator 中暴露为 Agent Action
• InvocableMethod Actions：使用 @InvocableMethod Apex 类直接集成自定义 Apex 逻辑到 Agentforce

增强 Actions：

• Lightning Types：自定义 LWC 改进 Agent Action 的输入/输出 UI，特别适合处理复杂数据结构
• Global Copy：为用户提供统一方式从 Agentforce 响应中的 UI 组件复制信息
• Apex Citations：为自定义 Action 添加引用（内联引用+知识文章/PDF/外部 URL 来源标注）

Apex REST Actions：生成 OpenAPI 与配置

使用 Agentforce Vibes Extension（基于 Salesforce 自有安全 AI 模型 CodeGen 和 xGen-Code）为 Apex REST 类快速生成 OpenAPI v3 规范。部署到 API Catalog 后即可创建 Agent Action。

关键术语

• OpenAPI Specification (OAS) 3.0.0：描述 REST API 的行业标准规范
• ExternalServiceRegistration (ESR)：将 OpenAPI 文档部署到 Salesforce API Catalog 的元数据类型
• API Catalog：Salesforce Org 中已注册 API 的中央存储库

前提条件与生成工作流

软件开发环境

1. 安装 Agentforce Vibes Extension：通过 VS Code 或 Open VSX 市场中的 Salesforce Extension Pack 安装。默认为启用状态
2. 安装 MuleSoft for Agentforce Extension Pack：含 API Design Extension + Governance Rulesets（Salesforce API Topic and Action Enablement + Salesforce Apex REST Best Practices）
3. 创建 Salesforce DX 项目：SFDX: Create Project。或从 GitHub 仓库创建
4. 分解 ESR 元数据：运行 sf project convert source-behavior -b decomposeExternalServiceRegistration 将 ESR 分解为 YAML + XML 文件。更新 sfdx-project.json

Apex REST 类要求

• 必须标注 @RestResource
• 含至少一个 HTTP 方法注解（@HttpGet/@HttpPost/@HttpPut/@HttpPatch/@HttpDelete）
• 必须使用 with sharing/without sharing/inherited sharing 修饰符定义共享规则
• 托管包中的 Apex 类不符合条件（即使声明为 global 也不可访问）

使用 Org Browser 检索已有 Apex REST 元数据

Org Browser 显示连接 Org 中的所有元数据类型。导航到目标 Apex REST 类，点击检索图标。检索到的类位于 /force-app/main/default/classes。

完整生成步骤（10 步）

1. SFDX: Create Project → 创建新 Salesforce 项目
2. SFDX: Set a Default Org → 选择部署目标 Org
3. 创建或检索 Apex REST 类（示例：CaseManager.cls，含 @HttpGet/@HttpPost/@HttpDelete/@HttpPut/@HttpPatch 方法）
4. SFDX: Refresh SObjects Definitions → 选择 All SObjects
5. SFDX: Create OpenAPI Document from this Class → 生成 <ApexClass>.yaml 和 <ApexClass>.externalServiceRegistration-meta.xml
6. 验证生成的 YAML 和 XML（检查 Problems 面板的错误和警告）
7. SFDX: Validate OpenAPI Document（或使用 MuleSoft Governance Rulesets）
8. SFDX: Deploy This Source to Org → 先部署 Apex 类
9. 再部署生成的 XML 文件到 Org
10. Setup → API Catalog → Apex 选项卡 → 确认 API 已列出 → Agentforce Builder 中创建 Agent Action

注意：API Catalog 的描述来自 YAML 文件的顶级 description 映射，不是 XML 的 <description> 元素。部署 ESR 不会自动共部署 Apex REST 类——必须单独部署。

重新生成 OpenAPI 文档

1. 修改关联的 Apex 类
2. 运行 SFDX: Create OpenAPI Document from this Class
3. 选择 Overwrite（直接覆盖，不可撤销）或 Manually Merge with Existing ESR（diff 窗口比较新旧文件）
4. 新文件生成在 esr_files_for_merge 文件夹，命名格式 <Class>_<timestamp>.yaml
5. 手动合并变更 → 验证 → 部署

验证 OpenAPI Spec

使用以下验证清单确保生成的 OpenAPI 文档与 Apex REST 类语义一致：

• 路径是否需要定义参数 /a/b/c/{id}（HttpGet/HttpDelete 通常从 URI 获取 ID）
• 生成的方法是否列在正确的路径下
• 路径的可替换参数是否在 parameters 节中正确配置 in 属性
• Query 参数是否在 parameters 节中，in 值正确
• 必需参数的 required 属性是否设为 true
• 所有参数类型是否正确
• 依赖 request body 的方法——body 结构是否正确
• 生成的 YAML 是否包含 200-299 范围的响应
• 响应体是否正确反映 Apex REST 类的返回类型

SFDC 扩展字段（x-sfdc）

这些布尔字段扩展 OpenAPI 规范，定义自动创建并在 Agent 中可用的 Agent Action。元数据必须在 schema（components.schemas）内定义，不能在 $ref 引用的 schema 中定义：

扩展字段	说明	必填
x-sfdc/agent/action/publishAsAgentAction	设为 true 将操作启用为 Agent Action	是
x-sfdc/privacy/isPii	如果启用 publishAsAgentAction，设为 true 为该操作下的查询启用 PII 服务	否
x-sfdc/agent/action/isUserInput	设为 true 将该字段暴露给用户进行进一步输入	是（需 publishAsAgentAction）
x-sfdc/agent/action/isDisplayable	设为 true 使该字段可显示给用户	是（需 publishAsAgentAction）

扩展元数据示例：

components:
  schemas:
    Pet:
      x-sfdc:
        agent:
          action:
            isDisplayable: true

Sample Apex REST Class (CaseManager.cls)

@RestResource(urlMapping='/apex-rest-examples/v1/Cases/*')
global with sharing class CaseManager {
    @HttpGet
    global static Case getCaseById() {
        RestRequest req = RestContext.request;
        String caseId = req.requestURI.substring(req.requestURI.lastIndexOf('/')+1);
        return [SELECT CaseNumber,Subject,Status,Origin,Priority FROM Case WHERE Id = :caseId];
    }
    @HttpPost
    global static ID createCase(String subject,String status,String origin,String priority) {
        Case c = new Case(Subject=subject,Status=status,Origin=origin,Priority=priority);
        insert c; return c.Id;
    }
    @HttpDelete
    global static void deleteCase() { /* 从 URI 获取 caseId 并删除 */ }
    @HttpPut
    global static ID upsertCase(String subject,String status,String origin,String priority,String id) {
        Case c = new Case(Id=id,Subject=subject,Status=status,Origin=origin,Priority=priority);
        upsert c; return c.Id;
    }
    @HttpPatch
    global static ID updateCaseFields() { /* 从 request body 反序列化字段并更新 */ }
}

OpenAPI 规范对象参考与 SFDC 扩展

对象	字段	关键要求
OpenAPI Object	openapi	固定为 3.0.0
	servers	单个 URL: /services/apexrest
	paths	路径必须与 @RestResource 的 urlMapping 完全匹配
Operations	operationId	唯一标识符，便于编程式引用
Parameters	in	仅 query/header/path。不要 cookie
	deprecated/explode/allowReserved	不要包含这些字段
Response	content	application/json（object 类型）或 text/plain（string 类型）
	headers	响应中不允许 headers
Schema	properties	必须包含
	not 块	不要使用
Header	禁止的 headers	cookie, set-cookie, set-cookie2, content-length, Authorization

ExternalServiceRegistration 元数据关键字段

字段	值	说明
namedCredential	null	Apex REST 服务部署在你的 Org 中，不需要外部凭据
registrationProvider	Apex 类名	实现 REST 服务的 Apex 类名称
registrationProviderType	ApexRest	新枚举值：表示 API Spec 由 Org 中的 Apex REST 类实现
schemaType	OpenApi3	固定值

注意：ApexRest 类型的 ESR 在 External Service Setup 中不可见——必须在 API Catalog 中查看。另外 ESR 部署不会自动共部署 Apex REST 类。

验证工具、Rulesets 与限制

MuleSoft for Agentforce Extension Pack

包含三个扩展：API Design Extension（语义和语法检查）+ Dependencies Extension + Platform Extension。

提供两个 Governance Rulesets：

• Salesforce API Topic and Action Enablement — 确保文档包含 Agent Action 所需的元数据
• Salesforce Apex REST Best Practices — 确保文档符合 Apex REST 最佳实践

关键命令：

• MuleSoft: Run Governance Validation with all Rulesets and Rules — 全面检查文档
• MuleSoft: Rerun non-confirmation validations on Governance Rules — 重新运行之前失败的规则（跳过已确认的警告）

API Console 测试

在 API Console 中可以检查端点，通过提供已部署的 Apex REST 实现或模拟请求数据来测试文档。参见 Review Your Spec in the API Console 和 Test Your Spec Using the API Mocking Service。

API Catalog 限制

API Catalog 限制适用于 Apex REST API 在 Agent 中的使用。达到活跃操作（operations）或对象（objects）数量上限时，需停用或删除不需要的操作。参见 View Apex APIs in API Catalog。

重要顺序：在停用或删除 Apex REST API Catalog 注册之前，先从使用该 API 的 Agent Action 中移除引用。