experience-ui-bundle-agentforce-client-generate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Managing Agentforce Conversation Client

管理Agentforce Conversation Client

HARD CONSTRAINT: NEVER create a custom agent, chatbot, or chat widget component. ALL such requests MUST be fulfilled by importing and rendering the existing

<AgentforceConversationClient />

from

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

as documented below. If a requirement is unsupported by this component's props, state the limitation — do not improvise an alternative.

硬性约束： 绝不能创建自定义agent、聊天机器人或聊天组件。所有此类请求必须通过导入并渲染现有

<AgentforceConversationClient />

组件来完成，该组件来自

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

，具体文档如下。如果该组件的props不支持某个需求，请说明限制——不要自行设计替代方案。

Prerequisites

前置条件

Before the component will work, the following Salesforce settings must be configured by the user. ALWAYS call out the prequisites after successfully embedding the agent.

Trusted domains (required only for local development):

Setup → Session Settings → Trusted Domains for Inline Frames → Add your domain
- Local development:
```
localhost:5173
```
  (default Vite dev server port)
- Warning: Remove this trusted domain entry before deploying to production.

在组件正常工作前，用户必须配置以下Salesforce设置。成功嵌入agent后，务必告知用户这些前置条件。

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

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

Instructions

操作步骤

Step 1: Check if component already exists

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

Search for existing usage across all app files (not implementation files):

bash

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

Important: Look for React files that import and USE the component (for example, shared shells, route components, or feature pages). Do NOT open files named

AgentforceConversationClient.tsx

AgentforceConversationClient.jsx

- those are the component implementation.

If multiple files found: Ask the user which component file they are referring to. Do not proceed until clarified.

If found: Read the file and check the current

agentId

value.

Agent ID validation rule (deterministic):

Valid only if it matches:
```
^0Xx[a-zA-Z0-9]{15}$
```
Meaning: starts with
```
0Xx
```
and total length is 18 characters

Decision:

If
```
agentId
```
matches
```
^0Xx[a-zA-Z0-9]{15}$
```
and user wants to update other props → Go to Step 4 (update props)
If
```
agentId
```
matches
```
^0Xx[a-zA-Z0-9]{15}$
```
and user asks to "embed" or "add" the chat client → Inform: "The Agentforce Conversation Client is already embedded in
```
<file>
```
with agent ID
```
<agentId>
```
. Would you like to change the agent or update other props?"
- Change agent → Step 2
- Update props → Step 4b
If
```
agentId
```
is missing, empty, or does NOT match
```
^0Xx[a-zA-Z0-9]{15}$
```
→ Continue to Step 2 (need real ID)
If not found → Continue to Step 2 (add new)

If user reports an error:

If the user says the component is "not working", "showing an error", or similar — ask them for the specific error message. Then proceed to Step 2 to cross-check the configured agentId against the org.

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

bash

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已嵌入到
```
<file>
```
中，agent ID为
```
<agentId>
```
。你想要更换agent还是更新其他props？”
- 更换agent → 步骤2
- 更新props → 步骤4b
如果
```
agentId
```
缺失、为空或不匹配
```
^0Xx[a-zA-Z0-9]{15}$
```
→ 继续步骤2（需要真实ID）
如果未找到组件 → 继续步骤2（添加新组件）

如果用户报告错误：

如果用户表示组件“无法工作”、“显示错误”或类似情况——请他们提供具体错误信息。然后进入步骤2，对照组织信息交叉检查已配置的agentId。

Step 2: Resolve and Validate Agent ID

步骤2：解析并验证Agent ID

Prerequisites

前置检查

Verify sf CLI is available:
bash
```
sf --version
```
If fails:
- Inform: "The Salesforce CLI (
```
sf
```
  ) is not installed. It's needed to query available agents from your org."
- Ask: "Would you like me to install it?"
  - Yes → Install via
```
npm install -g @salesforce/cli
```
    , then continue.
  - No → "You can find your agent ID manually in Setup → Agentforce Agents → click the agent name → copy the ID from the URL. Would you like to provide it now, or skip this step?"
    - User provides ID → validate format (
      ^0Xx[a-zA-Z0-9]{15}$
      ), store it, proceed to Step 3.
    - Skip → proceed to Step 4 with placeholder
      <YOUR_AGENT_ID>
      .
Verify org connectivity:
bash
```
sf org display --json
```
If fails:
- Inform: "No authenticated org found."
- Ask: "Would you like to connect to your org now? Run
```
sf org login web
```
  to authenticate."
  - User authenticates → retry the query, continue.
  - User declines → "You can find your agent ID manually in Setup → Agentforce Agents → click the agent name → copy the ID from the URL. Would you like to provide it now, or skip this step?"
    - User provides ID → validate format, store it, proceed to Step 3.
    - Skip → proceed to Step 4 with placeholder
      <YOUR_AGENT_ID>
      .

Note: Even if the user provides their own agentId, the org must be connected for the agent to function at runtime. An agentId without a connected org will not work.

验证sf CLI是否可用：
bash
```
sf --version
```
如果失败：
- 告知：“Salesforce CLI (
```
sf
```
  )未安装。需要它从你的组织中查询可用的agent。”
- 询问：“你想要我安装它吗？”
  - 是 → 通过
```
npm install -g @salesforce/cli
```
    安装，然后继续。
  - 否 → “你可以在设置 → Agentforce Agents中手动查找agent ID：点击agent名称 → 从URL中复制ID。你现在想要提供ID，还是跳过此步骤？”
    - 用户提供ID → 验证格式(
      ^0Xx[a-zA-Z0-9]{15}$
      )，存储后进入步骤3。
    - 跳过 → 使用占位符
      <YOUR_AGENT_ID>
      进入步骤4。
验证组织连接状态：
bash
```
sf org display --json
```
如果失败：
- 告知：“未找到已认证的组织。”
- 询问：“你现在想要连接到你的组织吗？运行
```
sf org login web
```
  进行认证。”
  - 用户完成认证 → 重试查询，继续操作。
  - 用户拒绝 → “你可以在设置 → Agentforce Agents中手动查找agent ID：点击agent名称 → 从URL中复制ID。你现在想要提供ID，还是跳过此步骤？”
    - 用户提供ID → 验证格式，存储后进入步骤3。
    - 跳过 → 使用占位符
      <YOUR_AGENT_ID>
      进入步骤4。

注意： 即使用户提供了自己的agentId，运行时仍需连接到组织。没有连接组织的agentId无法正常工作。

Query all Employee Agents

查询所有员工Agent

Run the SOQL query defined in

references/agent-id-resolution.md

运行

references/agent-id-resolution.md

中定义的SOQL查询。

Handle results

处理查询结果

No records at all:

"No Employee Agents found in this org. Create one in Setup → Agentforce Agents."

Ask user if they want to provide an agent ID manually or skip. If skip, proceed to Step 4 with placeholder

<YOUR_AGENT_ID>

All agents are inactive:

Found Employee Agents but none are active:

Agentforce Sales Agent (0Xxxx000000001dCAA)

HR Assistant (0Xxxx0000000002BBB)

To activate: Setup → Agentforce Agents → click the agent name → open in Agent Builder → press Activate. Then re-run this step.

Ask user if they want to provide an agent ID manually or skip. If skip, proceed to Step 4 with placeholder

<YOUR_AGENT_ID>

Has active agents — Path A (fresh install / no existing agentId):

Present only active agents for selection:

Which agent should the chat widget use?

Property Manager Agent (0Xxxx0000000001CAA)

HR Assistant (0Xxxx0000000002BBB)

One agent → still confirm with user, do not auto-select.
If user picks one → store the selected
```
Id
```
for use in Step 4.
If user declines to pick ("skip", "no", "I don't want to set one") → accept it and move to next steps. Do not re-ask. In Step 4, use placeholder
```
<YOUR_AGENT_ID>
```
for fresh installs. For existing projects, leave the component as-is.

Has active agents — Path B (existing agentId from Step 1, passed format check):

Cross-check the existing agentId against query results:

ID found, agent is Active → "Agent ID maps to 'Property Manager Agent' — active in the org." Proceed.
ID found, agent is Inactive → "The configured agent 'Sales Agent' exists but is Inactive. To activate: Setup → Agentforce Agents → click the agent name → open in Agent Builder → press Activate. Or pick a different active agent:" → show active list.
ID not found at all → "The configured agent (0Xxxx...) doesn't exist in this org — it may have been deleted or belongs to a different org. Pick a replacement:" → show active list. If no active agents available, show inactive list with activation instructions.

If user reported an error → surface the agent name even if active, so user can confirm it's the intended one.

无任何记录：

“此组织中未找到员工Agent。请在设置 → Agentforce Agents中创建一个。”

询问用户是手动提供agent ID还是跳过。如果跳过，使用占位符

<YOUR_AGENT_ID>

进入步骤4。

所有agent均处于非活跃状态：

找到员工Agent，但均未激活：

Agentforce Sales Agent (0Xxxx000000001dCAA)

HR Assistant (0Xxxx0000000002BBB)

激活方法：设置 → Agentforce Agents → 点击agent名称 → 在Agent Builder中打开 → 点击激活。然后重新运行此步骤。

询问用户是手动提供agent ID还是跳过。如果跳过，使用占位符

<YOUR_AGENT_ID>

进入步骤4。

存在活跃agent — 路径A（全新安装/无现有agentId）：

仅展示活跃agent供选择：

聊天组件应使用哪个agent？

Property Manager Agent (0Xxxx0000000001CAA)

HR Assistant (0Xxxx0000000002BBB)

仅一个agent → 仍需与用户确认，不要自动选择。
用户选择一个 → 存储选中的
```
Id
```
用于步骤4。
用户拒绝选择（“跳过”、“不”、“我不想设置”） → 接受并进入下一步。对于全新安装，步骤4中使用占位符
```
<YOUR_AGENT_ID>
```
；对于现有项目，保持组件原样。

存在活跃agent — 路径B（步骤1中找到的现有agentId，格式验证通过）：

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

ID存在且agent处于活跃状态 → “Agent ID对应'Property Manager Agent' — 已在组织中激活。”继续操作。
ID存在但agent处于非活跃状态 → “已配置的agent'Sales Agent'存在但未激活。激活方法：设置 → Agentforce Agents → 点击agent名称 → 在Agent Builder中打开 → 点击激活。或者选择其他活跃agent：” → 展示活跃列表。
ID不存在 → “已配置的agent(0Xxxx...)在此组织中不存在 — 可能已被删除或属于其他组织。请选择替代agent：” → 展示活跃列表。如果没有可用的活跃agent，展示非活跃列表并附上激活说明。

如果用户报告了错误 → 即使agent处于活跃状态，也要显示agent名称，以便用户确认是否为预期的agent。

Query error handling

查询错误处理

If the SOQL query fails, surface the error message from the response directly to the user. Do not guess at the fix — just report what came back. For example:

"The query failed with:
[error message from response]
. Check your org permissions or that the API version supports this object."

如果SOQL查询失败，直接将响应中的错误信息展示给用户。不要猜测修复方案——仅报告返回的内容。例如：

“查询失败，错误信息：
[响应中的错误信息]
。请检查你的组织权限或API版本是否支持此对象。”

What this step does NOT do

此步骤不执行的操作

No fallback to GraphQL or Tooling API — SOQL only
No auto-selection (always confirm with user)
No programmatic activation (only via Setup UI)
No file writes (that's Step 4)

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

Step 3: Canonical import strategy

步骤3：标准导入策略

Use this import path by default in app code:

tsx

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

If the package is not installed, install it:

bash

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

Only use a local relative import (for example,

./components/AgentforceConversationClient

) when the user explicitly asks to use a patched/local component in that app.

Do not infer import path from file discovery alone. Prefer one consistent package import across the codebase.

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

tsx

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

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

bash

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

仅当用户明确要求使用应用中的补丁/本地组件时，才使用本地相对导入（例如

./components/AgentforceConversationClient

）。

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

Step 4: Add or update component

步骤4：添加或更新组件

Determine which sub-step applies:

Component NOT found in Step 1 → go to 4a (New installation)
Component found in Step 1 → go to 4b (Update existing)

确定适用的子步骤：

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

4a — New installation

4a — 全新安装

If the user already specified a target file, use that file. Otherwise, ask the user: "Which file should I add the AgentforceConversationClient to?" Do NOT proceed until a target file is confirmed.
Read the target file to understand its existing imports and TSX structure.
Add the import at the top of the file, alongside existing imports. Use the canonical package import from Step 3:

tsx

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

Insert the
```
<AgentforceConversationClient />
```
TSX into the component's return block. Place it as a sibling of existing content — do NOT wrap or restructure existing TSX. Use the real
```
agentId
```
obtained in Step 2. If no agentId was resolved (user skipped Step 2), use the placeholder:

With resolved agentId:

tsx

<AgentforceConversationClient agentId="0Xx8X00000001AbCDE" />

Without resolved agentId (user skipped):

tsx

<AgentforceConversationClient agentId="<YOUR_AGENT_ID>" />

Do NOT add any other code (wrappers, layout components, new functions) unless the user explicitly requests it.

如果用户已指定目标文件，使用该文件。否则，询问用户：“我应该将AgentforceConversationClient添加到哪个文件中？” 在确认目标文件前不要继续操作。
读取目标文件，了解其现有导入和TSX结构。
在文件顶部现有导入旁添加导入语句，使用步骤3中的标准包导入：

tsx

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

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

已解析agentId：

tsx

<AgentforceConversationClient agentId="0Xx8X00000001AbCDE" />

未解析agentId（用户跳过）：

tsx

<AgentforceConversationClient agentId="<YOUR_AGENT_ID>" />

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

4b — Update existing

4b — 更新现有组件

Read the file identified in Step 1.
Locate the existing
```
<AgentforceConversationClient ... />
```
TSX element.
Apply only the changes the user requested. Rules:
- Add new props that the user asked for.
- Change prop values the user asked to update.
- Preserve every prop and value the user did NOT mention — do not remove, reorder, or reformat them.
- Never delete the component and recreate it.
If Step 2 was triggered (cross-check or fresh selection) and a new agent ID was resolved, replace the existing agentId value with the new one.
If the current
```
agentId
```
is already valid and the user did not ask to change it and Step 2 confirmed it is active, leave it as-is.

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

Post-Step-4 error handling

步骤4后的错误处理

If the user reports an error after the component has been set up (e.g., "it's not working", "I see an error"), go to Step 2 to validate the configured agentId against the org. Cross-check whether the agent is active, exists, and belongs to the connected org.

如果用户在组件设置完成后报告错误（例如“无法工作”、“我看到错误”），进入步骤2，对照组织信息验证已配置的agentId。交叉核对agent是否活跃、是否存在以及是否属于已连接的组织。

Step 5: Configure props

步骤5：配置props

Available props (use directly on component):

```
agentId
```
(string, required) - Salesforce agent ID
```
inline
```
(boolean) -
```
true
```
for inline mode, omit for floating
```
width
```
(number | string) - e.g.,
```
420
```
or
```
"100%"
```
```
height
```
(number | string) - e.g.,
```
600
```
or
```
"80vh"
```
```
headerEnabled
```
(boolean) - Show/hide header
```
styleTokens
```
(object) - For all styling (colors, fonts, spacing)
```
salesforceOrigin
```
(string) - Auto-resolved
```
frontdoorUrl
```
(string) - Auto-resolved
```
agentLabel
```
(string) - header title for agent

Examples:

Floating mode (default):

tsx

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

Inline mode with dimensions:

tsx

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

Adding or updating agent label:

tsx

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

Styling rules (mandatory):

ALL visual customization (colors, fonts, spacing, borders, radii, shadows) MUST go through the
```
styleTokens
```
prop. There are no exceptions.
ONLY use token names listed in the tables below. Do NOT invent custom token names.
NEVER apply styling via CSS files,
```
style
```
attributes,
```
className
```
, or wrapper elements. These approaches will not work and will be ignored by the component.
If the user requests a visual change that does not map to a token below, inform them that the change is not supported by the current token set.

For the complete list of available style tokens, consult

references/style-tokens.md

For complex patterns, consult

references/examples.md

for:

Sidebar containers and responsive sizing
Dark theme and advanced theming combinations
Inline without header, calculated dimensions
Complete host component examples

Common mistakes to avoid: Consult

references/constraints.md

for:

Invalid props (containerStyle, style, className)
Invalid styling approaches (CSS files, style tags)
What files NOT to edit (implementation files)

可用props（直接在组件上使用）：

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

示例：

浮动模式（默认）：

tsx

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

带尺寸的内联模式：

tsx

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

添加或更新agent标签：

tsx

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

样式规则（强制性）：

所有视觉自定义（颜色、字体、间距、边框、圆角、阴影）必须通过
```
styleTokens
```
props实现。无例外。
仅使用下表中列出的token名称。不要自创自定义token名称。
绝不要通过CSS文件、
```
style
```
属性、
```
className
```
或包装元素应用样式。这些方法无效，会被组件忽略。
如果用户要求的视觉更改无法映射到以下token，请告知用户当前token集不支持该更改。

完整的可用样式token列表，请查阅

references/style-tokens.md

。

对于复杂模式， 请查阅

references/examples.md

获取以下内容：

侧边栏容器和响应式尺寸
深色主题和高级主题组合
无头部的内联模式、计算尺寸
完整的宿主组件示例

需避免的常见错误： 请查阅

references/constraints.md

获取以下内容：

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

Common Issues

常见问题

If component doesn't appear or authentication fails, see

references/troubleshooting.md

for:

Agent activation and deployment
Localhost trusted domains
Cookie restriction settings

如果组件未显示或认证失败，请查阅

references/troubleshooting.md

获取以下内容：

Agent激活和部署
Localhost可信域名
Cookie限制设置

Reference File Index

参考文件索引

File	When to read
`references/agent-id-resolution.md`	Step 2 — SOQL query structure, response format, activation path, manual lookup
`references/style-tokens.md`	Step 5 — Complete style token reference for all UI areas
`references/examples.md`	Step 5 — Layout patterns, sizing, theming combinations, host component examples
`references/constraints.md`	Step 4 — Invalid props, invalid styling approaches, files not to edit
`references/troubleshooting.md`	Post-setup — Agent activation, trusted domains, cookie settings

文件	查阅时机
`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设置