description: "Use this skill when the user asks to add, embed, integrate, configure, style, or remove an agent, chatbot, chat widget, conversation client, or AI assistant in a UI Bundle project. Covers styling (colors, fonts, spacing, borders), layout (inline vs floating, width, height, dimensions), and props (agentId, agentLabel, headerEnabled, showHeaderIcon, showAvatar, styleTokens). TRIGGER when: project contains a uiBundles/*/src/ directory and the task involves adding or modifying a chat widget, chatbot, or conversational AI; files under uiBundles/*/src/ import AgentforceConversationClient; user asks to add any chat or agent functionality to a page. DO NOT TRIGGER when: user wants to create a custom agent, chatbot, or chat widget component from scratch; the project has no uiBundles directory."
**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.
## 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
**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` or `AgentforceConversationClient.jsx` - those are the component implementation.
- 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?"
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.
### Step 2: Resolve and Validate Agent ID
#### Prerequisites
1.**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>`.
2.**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.
#### Query all Employee Agents
Run the SOQL query defined in `references/agent-id-resolution.md`.
#### 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):**
- 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.
- **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.
#### 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."
#### What this step does NOT do
- No fallback to GraphQL or Tooling API — SOQL only
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.
1. 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.
2. Read the target file to understand its existing imports and TSX structure.
3. Add the import at the top of the file, alongside existing imports. Use the canonical package import from Step 3:
4. 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:
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.
- 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.
