/experience-ui-bundle-agentforce-client-generate

name: experience-ui-bundle-agentforce-client-generate
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. 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."
metadata:
  version: "1.1"
  cliTools:
    - tool: ["npm"]
      semver: ">=9.0.0"
    - tool: ["sf"]
      semver: ">=2.0.0"

Managing 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.

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.

Instructions

Step 1: Check if component already exists

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

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` or `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.

Step 2: Resolve and Validate Agent ID

Prerequisites

1. **Verify sf CLI is available:**

   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:**

   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):**

Present only active agents for selection: > Which agent should the chat widget use? > 1. Property Manager Agent (0Xxxx0000000001CAA) > 2. HR Assistant (0Xxxx000000000