创建和增强 Actions 总览
Actions 是使 Agent 能够执行任务和与数据交互的构建块。有四种创建方式和三种增强方式：
创建 Actions — 四种方式
| 方式 | 说明 |
|---|---|
| Apex REST Actions | 使用生成式 AI 为 @RestResource 类创建 OpenAPI 文档。部署类 + OAS + 元数据到 API 目录，然后从方法创建 Agent 动作 |
| AuraEnabled Actions | 为带有 @AuraEnabled 的 Apex 控制器方法生成 OpenAPI 文档。部署到 API 目录并在 Builder 中创建 Agent 动作 |
| Named Query Actions | 在 Setup 中创建自定义 SOQL 查询（命名查询），在 Agent Creator 中暴露为 Agent 动作 |
| Apex Invocable Method | 在 Apex 类上使用 @InvocableMethod 注解，将自定义 Apex 逻辑直接集成到 Agentforce 中 |
增强 Actions — 三种方式
| 方式 | 说明 |
|---|---|
| Lightning Types | 使用自定义 LWC 为复杂输入和输出改善 UI |
| Global Copy | 提供一致的从 UI 复制功能，提升可用性 |
| Apex Citations | 使用内联引用扩展动作，支持知识文章、PDF 数据和外部 URL 的来源标注 |
Apex REST Actions：生成 OpenAPI 和配置
使用 Agentforce Vibes Extension 通过生成式 AI 快速为你的 Apex REST 类创建 OpenAPI v3 文档。工作流：编写或获取 Apex REST 类 → 生成 OpenAPI 文档 → 验证 → 部署类 + 元数据到 API 目录 → 在 Agentforce Builder 中创建 Agent 动作。
前提条件
- Agentforce Vibes Extension（包含在 Salesforce Extension Pack for VS Code 或 Agentforce Vibes IDE 中）
- MuleSoft for Agentforce Extension Pack（可选）—— 用于治理规则集验证（API Design、Dependencies、Platform）
- Apex REST Class：必须有 @RestResource 注解 + 至少一个 @HttpGet/@HttpPost/@HttpPut/@HttpPatch/@HttpDelete 方法
- 必须有共享规则：with sharing / without sharing / inherited sharing
- 托管包类不符合条件；先分解 ExternalServiceRegistration 文件
10 步生成工作流
- 创建 Salesforce DX 项目（SFDX: Create Project）
- 设置默认组织（SFDX: Set a Default Org）
- 创建或获取 Apex REST 类
- 运行：SFDX: Create OpenAPI Document from this Class
- 选择输出文件夹（默认：externalServiceRegistration）
- 生成：
<ApexClass>.yaml+<ApexClass>.externalServiceRegistration-meta.xml - 验证：检查 Problems 标签页修复错误；运行 SFDX: Validate OpenAPI Document
- 部署 Apex 类：SFDX: Deploy This Source to Org
- 部署生成的 XML 文件到组织
- 确认：Setup → API Catalog → Apex 标签页 → API 已列出 → 可作为 Apex Reference Action 使用
类更改后重新生成：再次运行 Create OpenAPI Document → 选择 Overwrite（覆盖）或 Manually Merge（手动合并，打开 diff 视图，带时间戳的新文件放在 esr_files_for_merge 文件夹）→ 验证 → 部署。
验证 OpenAPI Spec 和扩展字段
生成 OpenAPI 文档后，验证其与 REST 类语义一致。确认路径参数、方法路径、查询参数、必填字段、参数类型、请求体形状、响应码（200-299 范围）和响应体结构。
关键 OpenAPI 对象要求
- openapi: 3.0.0
- servers: 单个
/services/apexrestURL - paths: 必须精确匹配 @RestResource urlMapping
- security: OAuth2 或 HTTP Bearer
关键字段规则
- Path Item：不要包含 servers、options、head、trace
- Operations：不要包含 callbacks、deprecated、security、servers
- Parameters：仅 query、header、path（无 cookie）；不要包含 deprecated、explode、allowReserved
- Request Body：仅 application/json 媒体类型
- Response：仅 application/json（对象）或 text/plain（字符串）；响应中无 headers
- Schema：不允许 'not' 块
Salesforce 扩展字段（x-sfdc）—— 启用 Agent Action 必需
| 扩展字段 | 说明 |
|---|---|
x-sfdc/agent/action/publishAsAgentAction: true | 必填 —— 启用为 Agent Action |
x-sfdc/privacy/isPii: true | 可选 —— 启用 PII 服务 |
x-sfdc/agent/action/isUserInput: true | 必填 —— 将字段暴露为输入 |
x-sfdc/agent/action/isDisplayable: true | 必填 —— 向用户显示字段 |
重要：扩展必须定义在 Schema 内部（非 $ref Schema），嵌套在 components.schemas.Pet.x-sfdc.agent.action 路径下。
ESR 元数据关键字段
- namedCredential: 始终为 null（部署到组织）
- registrationProvider: Apex REST 类名
- registrationProviderType: Custom（新枚举值）
- schemaType: OpenApi3
验证工具、规则集和限制
MuleSoft for Agentforce Extension Pack（3 个扩展）
- API Design Extension —— 检查语义和语法正确性
- Dependencies Extension —— 管理 API 依赖
- Platform Extension —— 特定于平台的验证
治理规则集
- Salesforce API Topic and Action Enablement —— 确保文档具备 Agent Action 所需的元数据
- Salesforce Apex REST Best Practices —— 确保 REST 实现遵循最佳实践
命令：MuleSoft: Run Governance Validation（全部规则） 或 MuleSoft: Rerun non-confirmation validations（重新运行之前失败的规则）。
API Console 测试
使用已部署的 Apex REST 实例或 Mock 请求数据检查端点，使用 API Mocking 服务审查 Spec 并测试。
限制和注意事项
- API 目录限制适用于 Agent 中的 Apex REST API
- 达到限制时：先停用或删除不需要的操作（在此之前先从 Agent Action 中移除）
- provider type 为 ApexRest 的 ExternalServiceRegistration 不可见于 External Service Setup
- 部署 ESR 不会同时部署 Apex REST 类 —— 必须分别部署
- 托管包类不符合条件（代码不可访问）
- 新的 ESR 文件在生成时自动分解
Agentforce Actions 让你完全控制扩展 Agent 的能力 —— 从 Apex REST 到 OpenAPI 生成、验证、部署，再到 UI 增强和引用标注，覆盖完整的 Action 开发生命周期。