Agentforce 客户聊天体验开发指南

Enhanced Chat v2 概述

Enhanced Chat v2 是 Service Cloud 上 Enhanced Web Chat 的新客户界面，允许你连接和部署 Service Agent 到外部聊天渠道。支持通过 Custom Lightning Types 自定义 UI、通过 utilAPI.setSessionContext 方法传递上下文事件、以及内联模式（Inline Mode）将聊天客户端嵌入到网页特定元素中。

Context Events（上下文事件）

Enhanced Chat v2 提供了一个独特的上下文事件传递方式。Enhanced Web Chat 中的 utilAPI 新增了 setSessionContext 方法，可在 Enhanced Chat v2 部署中使用，用于在网页和聊天客户端之间传递上下文事件。

Inline Mode（内联模式）vs 浮动模式

模式	行为
浮动模式（默认）	用户点击右下角 FAB 按钮时出现聊天窗口
内联模式	聊天直接渲染在父页面指定的 `<div>` 元素内，填满目标元素

启用内联模式：

embeddedservice_bootstrap.settings.displayMode = 'inline';
embeddedservice_bootstrap.settings.headerEnabled = false; // 可选
const myElement = document.querySelector('.chat-container');
embeddedservice_bootstrap.settings.targetElement = myElement;

Custom Lightning Types

使用 Lightning Web Components 个性化聊天外观，可以代表用户发送消息或从 LWC 传递上下文事件。

Custom Connections（自定义连接）

Custom Connections 通过 Agent API 将外部 Web 客户端连接到 Agentforce Agent。你定义基于元数据的连接，告知 Agent 你的客户端支持哪些结构化响应格式，Agent 则返回符合这些 Schema 的 JSON。这使得你的客户端可以渲染原生 UI 组件，如轮播、卡片、表单或选择器。

工作原理

Custom Connections 使用两种元数据类型：

AiSurface —— 定义连接本身：表面级指令（语气、长度限制、格式化条件）、引用的响应格式列表、surfaceType 设为 "Custom"
AiResponseFormat —— 定义单个结构化输出格式：JSON Schema（input 字段）、描述和指令（告诉 Agent 何时应用此格式）、可选的 invocationTarget

响应格式选择过程

当前对话轮次的子代理和动作指令首先运行
Agent 评估每个启用的 AiResponseFormat 的描述和指令
Agent 每轮最多选择一个格式 —— 判定为最匹配的格式
sortOrder 控制 LLM 评估顺序（较低值先评估；影响但不强制执行）
回退：如果没有格式被选中或发生错误 → 返回标准 Agent API 响应（无格式纯文本）

警告：所有响应格式指令都是非确定性的。Agent 可能选择错误的格式或产出不完全符合 JSON Schema 的输出。始终构建客户端解析以处理结构化响应和纯文本回退两种情况。

设置 Custom Connection

目录结构

unpackaged/
  package.xml
  aiResponseFormats/
    AcmeChatChoices_{surfaceId}.aiResponseFormat
    AcmeChatChoicesWithImages_{surfaceId}.aiResponseFormat
    AcmeChatTimePicker_{surfaceId}.aiResponseFormat
  aiSurfaces/
    AcmeChatClient_{surfaceId}.aiSurface
  genAiPlannerBundles/
    {YourPlannerBundle}/
      {YourPlannerBundle}.genAiPlannerBundle

{surfaceId} 是区分自定义连接及其关联响应格式的唯一字母数字标识符。

部署顺序（重要）

AiResponseFormat 必须在 AiSurface 之前部署，因为 Surface 引用了 Format。sf project deploy start --manifest unpackaged/package.xml。更新时直接重新部署同名的定义即可替换旧版本。

AiSurface 字段参考

description —— 连接的用途描述
instructions[] —— 高层指导（instruction 字符串 + sortOrder 整数，较低值优先），如 "Always reply with a brief, friendly, clear response under 160 characters."
responseFormats[] —— 启用的响应格式列表（enabled 布尔值 + responseFormat 开发者名称）
surfaceType —— "Custom"

AiResponseFormat 字段参考

description —— 告诉 Agent 何时选择此格式（用于选择评估，而非仅供人阅读）。如 "Use this when the number of choices is GREATER THAN 1 and LESSER THAN 8."
input —— 定义预期输出结构的 JSON Schema（Agent 尝试映射但非严格强制）
instructions[] —— 应用此特定格式的详细用例条件
invocationTarget / invocationTargetType —— 可选的可调用动作引用（apex/flow/standardInvocableAction）

关联到 Agent

在 GenAiPlannerBundle 中添加 plannerSurfaces 条目，指定 surface 名称和 surfaceType 为 Custom。

使用、解析和测试 Custom Connections

在 Agent API 会话中使用

"surfaceConfig": {
  "surfaceType": "Custom"
}

解析响应

检查消息是否包含 result 数组 → 响应格式已被应用
读取 result[0].type → 格式标识（前缀为 SURFACE_ACTION__ + AiResponseFormat 开发者名称，不含 _{surfaceId} 后缀）
将 result[0].value 解析为 JSON → 符合你定义的 input Schema
无 result 数组 → 回退，将 message 字段渲染为纯文本

// 示例响应
"result": [{
  "type": "SURFACE_ACTION__RegistrationForm",
  "value": "{\"title\":\"registrationForm\",\"message\":\"To register...\"}"
}]

重要：始终在客户端验证 result[0].value 后再交给渲染器 —— 平台不会对 Agent 的结构化输出进行 Schema 验证。

响应格式示例和故障排查

三种常见设计模式

模式	Schema	使用条件
文本选项	`{message: string, choices: string[]}`	选项数 >1 且 <8
带图选项	`{message: string, choices: [{title, imageUrl, actionText}]}`	图片对决策至关重要
时间选择器	Slack Block Kit timepicker 语法	用户需要选择具体时间

设计技巧

保持格式集小 —— 每个连接少于 7 个响应格式；太多会导致选择不可靠
描述要写给选择逻辑 —— 明确写出精确条件（项目数量、是否包含图片、数据形状），而非泛泛的人类描述
用 LLM 生成 JSON Schema —— 向你偏好的 LLM 提供输出结构，让它生成对应的 JSON Schema

故障排查速查

问题	解决方案
无效 JSON Schema	验证 input 字段包含有效、正确转义的 JSON
缺失引用	AiSurface 中所有格式必须作为已部署的 AiResponseFormat 实体存在
元数据部署错误	先部署 AiResponseFormat，再部署 AiSurface
surfaceType 不匹配	确保 AiSurface 和 plannerSurfaces 中 surfaceType 一致
响应未格式化	验证会话调用中包含 surfaceConfig 且 surfaceType 为 "Custom"

Custom Connections 为你提供了对客户如何与 Agentforce Agent 交互的完全控制 —— 从原生 UI 组件渲染到结构化数据交换，全部通过标准化的元数据定义实现。