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 设为 CustomAiResponseFormat—— 定义单个结构化输出格式JSON Schemainput 字段、描述和指令告诉 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—— CustomAiResponseFormat 字段参考description—— 告诉 Agent何时选择此格式用于选择评估而非仅供人阅读。如 Use this when the number of choices is GREATER THAN 1 and LESSER THAN 8.input—— 定义预期输出结构的 JSON SchemaAgent 尝试映射但非严格强制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再部署 AiSurfacesurfaceType 不匹配确保 AiSurface 和 plannerSurfaces 中 surfaceType 一致响应未格式化验证会话调用中包含 surfaceConfig 且 surfaceType 为 CustomCustom Connections 为你提供了对客户如何与 Agentforce Agent 交互的完全控制 —— 从原生 UI 组件渲染到结构化数据交换全部通过标准化的元数据定义实现。文章来源Agentforce 客户聊天体验开发指南 | Salesforce CRM 中文站