implementing-ui-bundle-agentforce-conversation-client

管理 Agentforce Conversation Client

**硬性约束：**绝不能创建自定义 Agent、聊天机器人或聊天小组件。所有此类请求都必须通过导入并渲染 @salesforce/ui-bundle-template-feature-react-agentforce-conversation-client 中现有的 <AgentforceConversationClient /> 来实现，具体如下文所述。如果此组件的 props 不支持某项需求，请说明这一限制，不要自行设计替代方案。

前提条件

要使组件正常工作，用户必须先配置以下 Salesforce 设置。成功嵌入 Agent 后，务必说明这些前提条件。

可信域（仅本地开发时需要）：

• 设置 → 会话设置 → 内嵌框架可信域 → 添加您的域
  • 本地开发：localhost:5173（Vite 开发服务器的默认端口）
  • **警告：**部署到生产环境前，请移除此可信域条目。

说明

第 1 步：检查组件是否已存在

在所有应用文件（不包括实现文件）中搜索现有用法：

grep -r "AgentforceConversationClient" --include="*.tsx" --include="*.jsx" --exclude-dir=node_modules

**重要：**查找导入并使用此组件的 React 文件（例如，共享外壳、路由组件或功能页面）。不要打开名为 AgentforceConversationClient.tsx 或 AgentforceConversationClient.jsx 的文件——这些文件是组件实现。

**如果找到多个文件：**询问用户指的是哪个组件文件。澄清前不要继续。

**如果找到：**读取该文件并检查当前的 agentId 值。

Agent ID 验证规则（确定性）：

• 仅当匹配 ^0Xx[a-zA-Z0-9]{15}$ 时才有效
• 含义：以 0Xx 开头，总长度为 18 个字符

决策：

• 如果 agentId 匹配 ^0Xx[a-zA-Z0-9]{15}$，且用户想更新其他 props → 前往第 4 步（更新 props）
• 如果 agentId 匹配 ^0Xx[a-zA-Z0-9]{15}$，且用户要求“嵌入”或“添加”聊天客户端 → 告知用户：“Agentforce Conversation Client 已使用 Agent ID <agentId> 嵌入到 <file> 中。您想更换 Agent，还是更新其他 props？”
  • 更换 Agent → 第 2 步
  • 更新 props → 第 4b 步
• 如果 agentId 缺失、为空，或不匹配 ^0Xx[a-zA-Z0-9]{15}$ → 继续第 2 步（需要真实 ID）
• 如果未找到 → 继续第 2 步（添加新组件）

如果用户报告错误：

如果用户表示组件“无法正常工作”“显示错误”或类似情况，请向他们询问具体错误消息。然后继续第 2 步，核对已配置的 agentId 是否与组织中的 Agent ID 一致。

第 2 步：解析并验证 Agent ID

前置条件

1. 确认 sf CLI 可用：

   sf --version
   

   如果失败：

   • 告知：“未安装 Salesforce CLI（sf）。需要使用它查询组织中可用的 Agent。”
   • 询问：“要我安装它吗？”
     • 是 → 通过 npm install -g @salesforce/cli 安装，然后继续。
     • 否 → “你可以手动查找 Agent ID：前往 Setup → Agentforce Agents → 点击 Agent 名称 → 从 URL 中复制 ID。你想现在提供，还是跳过此步骤？”
       • 用户提供 ID → 验证格式（^0Xx[a-zA-Z0-9]{15}$），保存该 ID，继续执行步骤 3。
       • 跳过 → 使用占位符 <YOUR_AGENT_ID> 继续执行步骤 4。

2. 确认组织连接状态：

   sf org display --json
   

   如果失败：

   • 告知：“未找到已通过身份验证的组织。”
   • 询问：“现在要连接到你的组织吗？运行 sf org login web 进行身份验证。”
     • 用户完成身份验证 → 重试查询，然后继续。
     • 用户拒绝 → “你可以手动查找 Agent ID：前往 Setup → Agentforce Agents → 点击 Agent 名称 → 从 URL 中复制 ID。你想现在提供，还是跳过此步骤？”
       • 用户提供 ID → 验证格式，保存该 ID，继续执行步骤 3。
       • 跳过 → 使用占位符 <YOUR_AGENT_ID> 继续执行步骤 4。

注意： 即使用户提供自己的 agentId，Agent 运行时也必须连接组织。未连接组织的 agentId 无法使用。

查询所有 Employee Agents

运行 references/agent-id-resolution.md 中定义的 SOQL 查询。

处理结果

没有任何记录：

“此组织中未找到 Employee Agents。请在 Setup → Agentforce Agents 中创建一个。”

询问用户是否要手动提供 Agent ID，或跳过。如果跳过，使用占位符 <YOUR_AGENT_ID> 继续执行步骤 4。

所有 Agent 均未激活：

找到了 Employee Agents，但没有已激活的 Agent：

• Agentforce Sales Agent (0Xxxx000000001dCAA)
• HR Assistant (0Xxxx0000000002BBB)

激活方法：Setup → Agentforce Agents → 点击 Agent 名称 → 在 Agent Builder 中打开 → 点击 Activate。 然后重新执行此步骤。

询问用户是否要手动提供 Agent ID，或跳过。如果跳过，使用占位符 <YOUR_AGENT_ID> 继续执行步骤 4。

存在已激活的 Agent — 路径 A（全新安装／不存在现有 agentId）：

仅列出已激活的 Agent 供用户选择：

聊天小组件应使用哪个 Agent？

1. Property Manager Agent (0Xxxx0000000001CAA)
2. HR Assistant (0Xxxx0000000002BBB)

• 只有一个 Agent → 仍需向用户确认，不要自动选择。
• 用户选择一个 → 保存所选的 Id，供步骤 4 使用。
• 用户拒绝选择（“跳过”、“不要”或“我不想设置”）→ 接受用户的选择并继续后续步骤。不要再次询问。对于全新安装，在步骤 4 中使用占位符 <YOUR_AGENT_ID>。对于现有项目，保持组件原样。

存在已激活的 Agent — 路径 B（步骤 1 中提供的现有 agentId 已通过格式检查）：

将现有 agentId 与查询结果交叉核对：

• 找到 ID，且 Agent 已激活 → “Agent ID 对应 ‘Property Manager Agent’——该 Agent 已在组织中激活。”继续。
• 找到 ID，但 Agent 未激活 → “已配置的 Agent ‘Sales Agent’ 存在，但未激活。激活方法：Setup → Agentforce Agents → 点击 Agent 名称 → 在 Agent Builder 中打开 → 点击 Activate。或者选择其他已激活的 Agent：”→ 显示已激活的 Agent 列表。
• 完全找不到 ID → “已配置的 Agent (0Xxxx...) 在此组织中不存在——可能已被删除，或属于其他组织。请选择替代项：”→ 显示已激活的 Agent 列表。如果没有可用的已激活 Agent，则显示未激活的 Agent 列表及激活说明。

如果用户报告了错误 → 即使 Agent 已激活，也显示其名称，以便用户确认这是否是目标 Agent。

查询错误处理

如果 SOQL 查询失败，请将响应中的错误消息直接呈现给用户。不要猜测如何修复——只需报告返回的内容。例如：

“查询失败，错误为：[error message from response]。请检查 org 权限，或确认 API 版本是否支持此对象。”

此步骤不会执行的操作

• 不回退到 GraphQL 或 Tooling API——仅使用 SOQL
• 不自动选择（始终与用户确认）
• 不以编程方式激活（只能通过 Setup UI 激活）
• 不写入文件（这是步骤 4 的操作）

步骤 3：规范导入策略

在应用代码中默认使用此导入路径：

import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";

如果尚未安装该包，请安装：

npm install @salesforce/ui-bundle-template-feature-react-agentforce-conversation-client

只有当用户明确要求在该应用中使用经过修补的本地组件时，才使用本地相对导入（例如 ./components/AgentforceConversationClient）。

不要仅凭文件发现结果推断导入路径。在整个代码库中优先使用一致的包导入方式。

步骤 4：添加或更新组件

确定适用的子步骤：

• 步骤 1 中未找到组件 → 转到 4a（新安装）
• 步骤 1 中找到组件 → 转到 4b（更新现有组件）

4a — 新安装

1. 如果用户已指定目标文件，则使用该文件。否则，询问用户："我应该将 AgentforceConversationClient 添加到哪个文件？" 在确认目标文件之前，不要继续。
2. 读取目标文件，了解其中现有的导入和 TSX 结构。
3. 在文件顶部、现有导入旁添加导入。使用步骤 3 中的规范包导入方式：

import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";

4. 在组件的 return 块中插入 <AgentforceConversationClient /> TSX。将其作为现有内容的同级元素放置——不要包装或重构现有 TSX。使用步骤 2 中获取的真实 agentId。如果未解析出 agentId（用户跳过了步骤 2），则使用占位符：

已解析 agentId：

<AgentforceConversationClient agentId="0Xx8X00000001AbCDE" />

未解析 agentId（用户跳过了步骤 2）：

<AgentforceConversationClient agentId="<YOUR_AGENT_ID>" />

5. 除非用户明确要求，否则不要添加任何其他代码（包装器、布局组件、新函数等）。

4b — 更新现有组件

1. 读取步骤 1 中确定的文件。
2. 找到现有的 <AgentforceConversationClient ... /> TSX 元素。
3. 仅应用用户要求的更改。规则：
   • 添加用户要求的新属性。
   • 更改用户要求更新的属性值。
   • 保留用户未提及的所有属性和值——不要删除、重排或重新格式化。
   • 切勿删除该组件后再重新创建。
4. 如果触发了步骤 2（交叉核对或重新选择），并解析出了新的 Agent ID，则将现有的 agentId 值替换为新值。
5. 如果当前 agentId 已有效、用户未要求更改，且步骤 2 已确认其处于激活状态，则保持原样。

步骤 4 之后的错误处理

如果用户在组件设置完成后报告错误（例如“无法正常运行”“我看到了错误”），请转到步骤 2，根据 org 验证已配置的 agentId。交叉核对 Agent 是否处于激活状态、是否存在，以及是否属于已连接的 org。

步骤 5：配置 props

可用的 props（直接用于组件）：

• agentId（字符串，必填）- Salesforce Agent ID
• inline（布尔值）- true 表示内嵌模式；浮动模式下省略
• width（数字 | 字符串）- 例如，420 或 "100%"
• height（数字 | 字符串）- 例如，600 或 "80vh"
• headerEnabled（布尔值）- 显示/隐藏标题栏
• styleTokens（对象）- 用于所有样式设置（颜色、字体、间距）
• salesforceOrigin（字符串）- 自动解析
• frontdoorUrl（字符串）- 自动解析
• agentLabel（字符串）- Agent 的标题栏标题

示例：

浮动模式（默认）：

<AgentforceConversationClient agentId="0Xx..." />

带尺寸的内嵌模式：

<AgentforceConversationClient agentId="0Xx..." inline width="420px" height="600px" />

添加或更新 Agent 标签：

<AgentforceConversationClient agentId="0Xx..." agentLabel="<dummy-agent-label>" />

样式规则（强制）：

• 所有视觉自定义（颜色、字体、间距、边框、圆角、阴影）都必须通过 styleTokens prop 设置，不得例外。
• 只能使用下表中列出的 token 名称。不要自行创建自定义 token 名称。
• 不得通过 CSS 文件、style 属性、className 或包装元素应用样式。这些方法不起作用，组件会忽略它们。
• 如果用户要求的视觉更改无法通过下方的 token 实现，请告知用户当前 token 集不支持此更改。

如需查看可用样式 token 的完整列表，请参阅 references/style-tokens.md。

复杂模式请参阅 references/examples.md，了解：

• 侧边栏容器和响应式尺寸
• 深色主题和高级主题组合
• 不带标题栏的内嵌模式、计算后的尺寸
• 完整的宿主组件示例

需避免的常见错误： 请参阅 references/constraints.md，了解：

• 无效的 props（containerStyle、style、className）
• 无效的样式设置方法（CSS 文件、style 标签）
• 不应编辑的文件（实现文件）

常见问题

如果组件未显示或身份验证失败，请参阅 references/troubleshooting.md，了解：

• Agent 激活和部署
• localhost 受信任域
• Cookie 限制设置

参考文件索引

文件	何时阅读
references/agent-id-resolution.md	步骤 2 — SOQL 查询结构、响应格式、激活路径、手动查找
references/style-tokens.md	步骤 5 — 所有 UI 区域的完整样式 token 参考
references/examples.md	步骤 5 — 布局模式、尺寸设置、主题组合、宿主组件示例
references/constraints.md	步骤 4 — 无效的 props、无效的样式设置方法、不应编辑的文件
references/troubleshooting.md	设置后 — Agent 激活、受信任域、Cookie 设置