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 且
带图选项{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 组件渲染到结构化数据交换，全部通过标准化的元数据定义实现。
文章来源：https://www.salesforcecrm.cn/article/agentforce/agentforce-customer-chats-guide.html
