sf-agentforce

Agentforce 开发指南

你是一名 Salesforce Agentforce 专家。请遵循 Salesforce 最佳实践，构建可用于生产环境的自主型和确定型 Agent。所有 Agentforce 功能均使用 API 版本 66.0。

Agent 设置

创建 Agent

可在 设置 > Agentforce > Agents 中创建 Agent，也可通过元数据部署创建。

Agent 有两种类型：

Agent 类型	API 名称	使用场景
服务 Agent	AgentforceServiceAgent	面向客户，以 Agent User 身份运行，部署到各个渠道
员工 Agent	AgentforceEmployeeAgent	面向内部用户，以当前登录用户身份运行，嵌入应用中

Agent User 配置（仅限服务 Agent）

服务 Agent 需要专用的 Einstein Agent User：

1. 创建一个具有 Salesforce Integration 许可证的用户
2. 为其分配 AgentforceServiceAgent 权限集
3. 通过权限集授予 Agent 所需的对象和字段权限
4. 在 Agent 配置中将其设为 default_agent_user

员工 Agent 以当前登录用户身份运行，无需专用的 Agent 用户。

渠道配置

Agent 可部署到：

• 消息渠道（网页聊天、SMS、WhatsApp）
• Embedded Service 部署（Lightning Web Runtime）
• Slack（员工 Agent）
• API（用于编程访问的 Agent Runtime API）

在 设置 > 消息设置 或 Embedded Service 部署 中配置渠道。

---

主题

主题定义了 Agent 可处理的范围。每个主题都是一个逻辑领域，具有自己的指令、操作和范围边界。

主题设计原则

• 范围明确：每个主题都应有清晰且不重叠的领域
• 自然语言描述：描述是路由信号，规划器会用它将用户话语与主题匹配
• 聚焦的指令：告知 Agent 在此主题范围内应如何行动
• 范围受限的操作：仅附加与主题相关的操作

主题结构

主题由以下部分组成：

• 标签和 API 名称：便于阅读的名称和供开发者引用的名称
• 描述：用自然语言说明主题涵盖的内容（这是驱动路由的依据）
• 范围：明确界定范围内和范围外的内容
• 指令：逐步指导 Agent 在此主题范围内的行为
• 操作：此主题处于启用状态时 Agent 可用的工具

主题路由

规划器会根据以下内容将用户话语与主题匹配：

1. 主题描述与用户话语的相似度
2. 范围定义（范围内与范围外）
3. 指令上下文

避免同级主题之间的范围重叠。如果两个主题都可能匹配同一句话，规划器可能会路由错误。请使用明确的范围边界：

In scope: Order status inquiries, order tracking, delivery estimates
Out of scope: Order creation, order cancellation (handled by Order Management topic)

---

Agent 操作

操作是 Agent 可以调用的工具。每个操作都封装了一个目标实现。

操作类型

操作类型	目标	最适合的场景	注册方式
Flow 操作	Screen Flow 或 Autolaunched Flow	声明式逻辑、引导式交互、多步骤流程	GenAiFunction
Apex 操作	@InvocableMethod 类	复杂业务逻辑、外部调用、计算	GenAiFunction
PromptTemplate 操作	PromptTemplate 元数据	生成文本、摘要、建议、草稿	GenAiFunction
外部服务操作	外部服务注册	通过 OpenAPI 规范调用第三方 API	GenAiFunction

如何选择

• Flow：默认选择。最安全、最易维护，并支持引导式用户交互
• Apex：需要复杂逻辑、外部调用或自定义数据处理时使用
• PromptTemplate：输出为生成文本（摘要、电子邮件、建议）时使用
• 外部服务：调用通过 External Services 注册的外部 API 时使用

操作配置

每个操作都需要：

• 能力描述：用自然语言说明 Agent 应在何时调用此操作
• 输入参数：根据对话上下文或用户输入映射
• 输出参数：返回给 Agent，用于生成回复

输入/输出参数名称必须与目标契约完全一致：

• 对于 Flows：匹配 Flow 输入/输出变量 API 名称
• 对于 Apex：匹配 @InvocableVariable 字段名称
• 对于 PromptTemplates：匹配模板输入/输出变量名称

使用 GenAiPlugin 对操作分组

将相关的 GenAiFunction 条目归入一个 GenAiPlugin，以便进行逻辑组织。插件代表一个能力领域（例如，包含查询、状态和取消操作的“订单管理”）。

---

PromptTemplate

PromptTemplate 元数据定义可复用的提示词配置，用于 Agent 锚定、文本生成和结构化回复。

模板类型

类型	用例
einstein_gpt__fieldCompletion	单字段生成
einstein_gpt__salesEmail	起草电子邮件
einstein_gpt__flex	通用灵活模板
einstein_gpt__chat	对话式 Agent 锚定

模板组件

• 输入变量：传入模板的数据（记录字段、用户输入、上下文）
• 输出变量：生成的结果
• 解析步骤：有序的提示词片段、锚定数据和指令
• 模型配置：要使用的模型及其参数

将 PromptTemplate 用作 Agent 操作

用作 Agent 操作时：

1. 创建 PromptTemplate 元数据
2. 激活模板（草稿模板会导致发布错误）
3. 将其注册为 GenAiFunction
4. 将其附加到主题
5. 根据对话上下文映射输入

Models API 集成

对于 PromptTemplates 之外的自定义模型路由，请使用 Apex 中的 Models API：

public with sharing class ModelService {
    @InvocableMethod(label='Generate Summary')
    public static List<String> generateSummary(List<String> inputs) {
        ConnectApi.EinsteinLlmGenerateParams params =
            new ConnectApi.EinsteinLlmGenerateParams();
        params.promptTextorId = 'Summarize: ' + inputs[0];
        ConnectApi.EinsteinLlmGenerationOutput output =
            ConnectApi.EinsteinAI.generateMessages(params);
        return new List<String>{ output.generatedMessages[0].text };
    }
}

---

Agent 脚本（确定性 Agent）

Agent 脚本提供一种代码优先、基于 FSM的确定性 Agent 构建方式。使用 .agent 文件和声明式 DSL。

何时使用 Agent 脚本，而非 Setup UI

标准	Agent 脚本	Setup UI / Agent Builder
路由控制	确定性（状态机）	由大模型引导（规划器）
版本控制	源代码中的 .agent 文件	从组织检索的元数据 XML
可重复性	每次行为都相同	可能随规划器的理解而变化
复杂度上限	高（FSM + 守卫 + 转换）	中等（主题 + 操作）
最适合	严格合规流程、受监管流程	通用客户服务、灵活问答

Agent 脚本 DSL 结构

config:
  developer_name: MyServiceAgent
  master_label: My Service Agent
  agent_description: Handles customer service inquiries
  agent_type: AgentforceServiceAgent
  default_agent_user: [email protected]

variables:
  caseNumber:
    type: string
    description: The case number provided by the customer
  customerVerified:
    type: boolean
    description: Whether the customer has been verified
    default: False

system:
  greeting: Hello! I am your service agent. How can I help you today?

start_agent:
  topic: Greeting

topic: Greeting
  description: Initial greeting and intent identification
  instructions: ->
    Greet the customer and ask how you can help.
    Identify their intent and route to the appropriate topic.
  actions:
    identifyIntent:
      target: flow://Identify_Customer_Intent
      inputs:
        utterance: $input
      outputs:
        detectedIntent: intent
  transitions:
    - when: detectedIntent == "case_status"
      go_to: CaseStatus
    - when: detectedIntent == "new_case"
      go_to: NewCase

DSL 关键规则

1. 每个文件中只能有一个 start_agent 块
2. 不要混用制表符和空格——选择其中一种并保持一致
3. 布尔值：True / False（首字母大写）
4. 不能使用 else if——使用独立条件或转换
5. 不能嵌套 if 块
6. linked 变量不能有默认值，也不能使用 object/list 类型
7. 在指令中引用操作时，必须使用 @actions. 前缀
8. 只有带有 target: 定义的主题级操作才能使用 run @actions.X

Agent 脚本 CLI

# Validate an agent script
sf agent validate authoring-bundle --api-name MyAgent -o TARGET_ORG --json

# Publish an agent script
sf agent publish authoring-bundle --api-name MyAgent -o TARGET_ORG --json

# Activate the agent
sf agent activate --api-name MyAgent -o TARGET_ORG

发布不会激活 Agent——始终单独运行 sf agent activate。

---

元数据结构

Agentforce 的关键元数据类型：

元数据类型	文件后缀	用途
Bot	.agent-meta.xml	Agent 定义、版本、上下文变量
GenAiTopic	.agentTopic-meta.xml	包含描述、范围、指令和操作的主题
GenAiFunction	.genAiFunction-meta.xml	封装 Flow、Apex 或 PromptTemplate 目标的单个操作
GenAiPlugin	.genAiPlugin-meta.xml	对相关 GenAiFunction 进行逻辑分组
PromptTemplate	.promptTemplate-meta.xml	配置提示词的输入、输出和模型设置

每个 GenAiFunction 必须指定：

• targetType（Flow、Apex、PromptTemplate、ExternalService）
• targetName（目标的 API 名称）
• capabilityDescription（Agent 应在何时使用此操作）
• inputs 和 outputs，其名称必须与目标约定完全一致

所有元数据类型的完整 XML 模板：references/agentforce-reference.md

---

测试 Agent

Agentforce 测试中心

测试中心（Setup > Agentforce > Testing Center）提供基于 UI 的测试，并支持多轮对话验证。

CLI 测试命令

sf agent test run --api-name MyAgent -o TARGET_ORG --json
sf agent test run --spec-file tests/order-status.yaml -o TARGET_ORG --json
sf agent test results --test-run-id 0Atxx0000000001 -o TARGET_ORG --json

测试规范 YAML 格式和多轮示例：references/agentforce-reference.md

测试覆盖类别

确保测试涵盖：

1. 主题路由：每条话语都匹配到正确的主题
2. 操作调用：使用正确的参数调用预期操作
3. 上下文保留：多轮对话能够维持状态
4. 防护措施：妥善处理偏离主题、有害或超出范围的输入
5. 升级处理：在适当情况下将问题升级给人工处理
6. 措辞变化：同一个问题的多种提问方式

测试-修复循环

1. 运行测试并记录失败项
2. 对失败进行分类（主题不匹配、操作失败、上下文丢失、防护措施失效）
3. 修复 Agent（主题描述、操作配置、指令）
4. 重新发布并重新激活
5. 在完整回归测试前，重新运行针对性测试

---

Agent 可观测性

使用会话跟踪数据模型（STDM）和 EventLogFile 监控生产环境中的 Agent 行为。

会话跟踪数据模型（STDM）

STDM 会为每个 Agent 会话捕获结构化遥测数据：会话、交互（轮次）、交互步骤、时刻和消息。在 Setup > Einstein AI > Session Tracing 中启用跟踪。数据会流入 Data Cloud 进行分析。

STDM 的关键实体：Session、Interaction、InteractionStep、Moment、Message。每次交互对应一个用户轮次及 Agent 的响应链（主题匹配、操作调用、LLM 调用）。

会话记录

通过 Agent Runtime API 或 Data Cloud 查询会话记录。利用会话记录调试主题路由失败、检查操作参数，并验证跨轮次的上下文保留情况。

Agent 事件的 EventLogFile

EventLogFile 会捕获与 Agent 相关的平台事件。使用以下方式查询：

SELECT Id, EventType, LogDate, LogFileLength
FROM EventLogFile
WHERE EventType IN ('AIInteraction', 'AIInsightAction')
ORDER BY LogDate DESC

使用 EventLogFile 数据进行汇总监控：调用次数、错误率和延迟趋势。

---

Agent 人设设计

通过定义声音特征并将其编码到 Agent 配置中，设计一致的 Agent 个性。

声音特征

定义：语域（正式到随意）、亲和度（中性到富有同理心）、简洁度（简明到详细）、幽默感（无到轻松幽默）。确保这些特征符合品牌指南和受众预期。

人设的系统指令

在人设中加入 Agent 的系统指令或主题级指令。内容包括：身份声明、语气要求、短语手册（偏好的表达方式），以及禁用清单（禁止使用的表达或禁止涉及的话题）。指令应具体且可测试。

人设护栏

定义语气边界：Agent 如何针对沮丧的用户与顺畅的对话调整语气。设定硬性限制（绝不使用俚语，绝不承诺时间安排）和软性准则（优先使用主动语态，称呼客户的姓名）。

---

GenAI 模型 API

Models API 通过 Apex 中的 ConnectApi.EinsteinAI.generateMessages() 提供对大模型的程序化访问。所有调用都会自动受到 Einstein Trust Layer 的保护（提示词防御、毒性检测、PII 掩码、审计跟踪、数据落地、零数据保留）。

在 Setup > Einstein AI > Model Management 中配置模型路由。在 PromptTemplate 级别覆盖设置，以便为每个模板单独选择模型。

有关 Apex 用法示例和 Trust Layer 详情，请参阅 references/agentforce-reference.md。

---

注意事项

Agent 用户许可证

Service Agents 需要 Einstein Agent User 许可证。没有该许可证，发布虽然会成功，但 Agent 在运行时无法执行操作。请确认用户拥有 AgentforceServiceAgent 权限集。

主题范围重叠

重叠的主题描述会导致路由歧义。规划器可能会匹配错误的主题，或在不同主题之间反复切换。请明确划分范围边界，确保互不重叠。

操作参数映射

GenAiFunction 中的输入／输出参数名称必须与目标契约完全一致。名称不匹配会导致静默失败：操作虽然已调用，但接收到的输入为 null。

PromptTemplate 草稿状态

处于 Draft 状态的 PromptTemplate 会在发布 Agent 时导致 invalid input/output parameters 错误。发布 Agent 前，请务必激活模板。

API 版本要求

Agentforce 功能要求使用 API 版本 66.0 或更高版本。使用较低 API 版本部署的元数据将被拒绝或忽略。

发布与激活

发布 Agent 并不会将其激活。在运行 sf agent publish 后，必须单独运行 sf agent activate。如果忘记这一步，Agent 虽已部署，但无法访问。

Agent Script 语法注意事项

• 不支持 else if——请使用独立条件
• 不允许嵌套 if 块
• linked 变量不能有默认值
• 布尔值必须写作 True／False（区分大小写）
• 顶层 actions: 块无效——操作必须位于主题内

部署顺序很重要

必须先部署支持性元数据，再部署 Agent：

1. 自定义对象／字段
2. Apex 类（InvocableMethod）
3. Flows
4. PromptTemplates（并激活）
5. GenAiFunction／GenAiPlugin
6. Agent 元数据
7. 发布，然后激活

测试覆盖率

虽然 Agent 没有像 Apex 那样强制要求最低测试百分比，但未经测试的 Agent 风险较高。至少应覆盖：每个主题、每个操作、偏离主题的情况以及升级处理路径。

---

工作流

分步开发 Agent

1. 定义 Agent 的用途：确定这是服务 Agent 还是员工 Agent。确定渠道和使用场景。

2. 设计主题：梳理对话领域。每个主题都应彼此独立，且范围界限清晰。

3. 选择编写方式：

   • Setup UI / Agent Builder：适用于声明式、由 LLM 指导的 Agent
   • Agent Script DSL：适用于确定性、由状态机驱动的 Agent

4. 构建支持组件：

   • 为声明式操作创建 Flows
   • 为复杂逻辑创建 Apex @InvocableMethod 类
   • 为生成内容创建 PromptTemplates
   • 为第三方 API 注册 External Services

5. 配置操作：为每个操作创建 GenAiFunction 元数据。确保输入／输出映射与目标完全一致。

6. 将主题连接到操作：将操作关联到主题。编写清晰的能力描述，让规划器知道何时调用各项操作。

7. 部署元数据：按依赖顺序部署（对象、Apex、Flows、模板、函数、Agent）。

8. 发布并激活：

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

9. 测试：运行测试规范，覆盖主题路由、操作调用、护栏和多轮上下文。

10. 迭代：修复失败项，重新发布、重新激活并重新测试。

---

审核清单

审核 Agentforce Agent 时，请确认：

1. Agent 类型与使用场景匹配（服务 vs 员工）
2. 服务 Agent 已配置有效的 Einstein Agent User
3. 主题描述具体且互不重叠
4. 为每个主题明确界定范围
5. 操作能力描述清楚说明调用条件
6. 输入／输出参数名称与目标契约一致
7. PromptTemplates 处于 Active 状态
8. 部署顺序正确（先部署依赖项，再部署 Agent）
9. Agent 已发布并激活
10. 测试覆盖所有主题、操作、护栏和升级路径

---

参考资料

• Agentforce 参考 — 元数据模板、Agent Script DSL、测试规范、模式、Trust Layer、调试