Agentforce Actions 创建与 UI 自定义指南

AuraEnabled 控制器方法创建 Actions

使用 Agentforce Vibes Extension 为带有 @AuraEnabled 注解的 Apex 控制器方法生成 OpenAPI v3 规范文档。与 Apex REST Actions 相同的工作流：生成 OAS → 验证 → 部署类 + 元数据到 API 目录 → 在 Builder 中创建 Agent Action。

AuraEnabled Apex 类限制

API 目录限制适用
达到限制时：先停用或删除不需要的操作（在此之前先从 Agent Action 中移除引用）
参考：View Apex APIs in API Catalog、Apex AuraEnabled Annotation 参考、Lightning Aura Components 和 LWC 开发者指南

Named Query API Actions

在 Setup 中创建自定义 SOQL 查询，并将其暴露为 Agent Actions。这是将数据查询暴露为动作的最简单方式，无需编写 Apex 代码。

所需权限

操作 Named Query API：创建/读取/更新/删除 Named Query API 记录
使用带 Named Query 的 Agent：View Developer Name 或 View Setup and Configuration

设置和使用流程

Setup → User Interface → 启用 "Salesforce Platform REST API, Named Query for Agent Actions"
创建 Named Query APIs（SOQL 查询）—— 它们会出现在 Setup → API Catalog 中，需手动激活
Setup → Agentforce Assets → Actions → New Agent Action
Reference Action Type: API → Reference Action Category: Salesforce Named Query API
从 Reference Action 中选择动作

注意：执行命名查询的用户必须对所查询的数据具有读取权限。

Apex Invocable Method Actions

使用 @InvocableMethod 注解直接从 Apex 代码创建自定义动作。这是最直接的 Apex 集成方式。

关键注解

@InvocableMethod(label='...' description='...') —— 标记方法可被 Agent 调用。label 和 description 帮助 Agent 决定何时调用
@InvocableVariable(required=true label='...' description='...') —— 定义输入/输出参数，description 告诉 Agent 每个字段的含义

代码结构示例

public with sharing class HelloWorld {
  @InvocableMethod(label='Hello World' description='Takes a name and returns a greeting')
  public static List<OutputParameters> sayHello(List<InputParameters> inputs) {
    // 处理输入，返回输出
  }
  public class InputParameters {
    @InvocableVariable(required=true label='Name' description='...')
    public String name;
  }
  public class OutputParameters {
    @InvocableVariable(label='Greeting' description='...')
    public String greeting;
  }
}

重要模式

方法必须为 static，接受和返回 List<T>（即使是单次调用）
输入和输出类在每个字段上使用 @InvocableVariable
label 和 description 决定了 Agent 理解和正确使用动作的能力

使用 Lightning Types 自定义 UI

使用自定义 Lightning Web Components 增强 Agent Action 的聊天体验。替换默认 UI，创建品牌化、交互式的自定义输入表单和输出显示。仅适用于使用 Apex 类作为输入/输出的 Agent Actions。

入门路径

Setup UI：直接在 Setup 中创建
架构理解：学习核心概念、文件结构、Schema 投影
方法选择：Apex 类驱动或手动 JSON Schema
构建：结构化 LightningTypeBundle 元数据
AI 辅助：使用 Agentforce Vibes 中的 Lightning Types skill，用自然语言生成
部署：使用 Metadata API 或 Salesforce CLI

标准 Lightning Types 工作原理

映射：Apex 输入/输出类型映射到标准 Lightning 类型（date→lightning__dateType、string→lightning__stringType）
Schema 验证：每个标准类型有 Schema 定义验证规则
自动 UI 生成：Salesforce 根据映射类型自动生成 UI 组件（多行文本→多行文本框、日期→日期选择器、列表→表格）
数据渲染：Renderer 组件在动作执行时显示结构化数据
开箱即用：标准类型提供即用组件，配置最少

集成自定义 Lightning Type：打开 Agent Action → 编辑 Input Rendering 或 Output Rendering 参数 → 选择自定义 Lightning 类型 → 保存。

航班预订示例：自定义 Lightning Types

以下是一个完整的航班搜索 Agent Action 示例，展示如何使用自定义 Lightning Types 改善输入和输出 UI。

Apex 类

创建两个类：FlightSearchAction（@InvocableMethod 处理航班搜索逻辑）和输入/输出参数类型。输出包含航班选项列表、价格、折扣信息等。

创建 Agent Action 和默认 UI 问题

创建 Agent Action 后，默认 UI 可能杂乱无章 —— 标签不清晰、无操作按钮、折扣信息不突出。通过自定义 Lightning Types 可以彻底改善：

输出 UI：创建 flightResponse CLT — 清晰标签、吸引人的布局、高亮折扣、突出的 Book Now 按钮
输入 UI：创建 flightFilter CLT — 自定义输入表单，更直观的用户交互

改造前后对比

默认 UI（杂乱、无标签、无操作按钮）→ 自定义 UI（清晰标签、吸引人的布局、高亮折扣、突出的操作按钮），显著提升用户体验。

从简单的 Named Query 到完整的 @InvocableMethod 集成，从默认 UI 到自定义 Lightning Type 体验 —— Agentforce Actions 提供了从声明式到程序化的完整灵活度。