Implementing Ui Bundle Agentforce Conversation Client

# Agent ID Resolution

## SOQL Query

```bash
sf data query \
  --query "SELECT BotDefinition.Id, BotDefinition.DeveloperName, BotDefinition.MasterLabel, Status FROM BotVersion WHERE BotDefinition.AgentType = 'AgentforceEmployeeAgent' ORDER BY BotDefinition.CreatedDate ASC" \
  --json
```

- Queries `BotVersion` (not `BotDefinition`) because only `BotVersion` has the `Status` field (`Active` / `Inactive`)
- Filters on `AgentType = 'AgentforceEmployeeAgent'` to return only Employee Agents (excludes Service Agents)

## Response Structure

```json
{
  "status": 0,
  "result": {
    "records": [
      {
        "BotDefinition": {
          "Id": "0Xxxx0000000001CAA",
          "DeveloperName": "Property_Manager_Agent",
          "MasterLabel": "Property Manager Agent"
        },
        "Status": "Active"
      }
    ]
  }
}
```

## Activation Path

Agents cannot be activated programmatically:

> Setup → Agentforce Agents → click agent name → Agent Builder → Activate

## Manual Lookup (without sf CLI)

> Setup → Agentforce Agents → click agent name → copy ID from URL

## Validation

`agentId` must match: `^0Xx[a-zA-Z0-9]{15}$`


# Constraints and Anti-Patterns

This document lists all invalid approaches and patterns to avoid when working with AgentforceConversationClient.

## Never Edit Implementation Files

**CRITICAL: Only edit files where the component is USED, never the component implementation itself.**

- ✅ **DO edit**: Any React files that import and use `<AgentforceConversationClient />` (for example, shared shells, route components, or feature pages)
- ❌ **DO NOT edit**: AgentforceConversationClient.tsx, AgentforceConversationClient.jsx, index.tsx, index.jsx, or any files inside:
  - `node_modules/@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client/src/`
  - `packages/template/feature/feature-react-agentforce-conversation-client/src/`
  - `src/components/AgentforceConversationClient.tsx` (patched templates)
  - Any path containing `/components/AgentforceConversationClient.`

**If you're reading a file named `AgentforceConversationClient.tsx`, you're in the wrong place. Stop and search for the USAGE instead.**

## Invalid Props

AgentforceConversationClient uses a flat prop API and does NOT accept these props:

- ❌ `containerStyle` - Use `width` and `height` props directly instead
- ❌ `style` - Use `styleTokens` for theming
- ❌ `className` - Not supported
- ❌ Any standard React div props - This wraps an embedded iframe, not a div

**Why:** The component is a wrapper around an embedded iframe using Lightning Out 2.0. Standard React styling props don't apply.

## Invalid Styling Approaches

**CRITICAL: For ALL styling, theming, branding, or color changes - ONLY use `styleTokens` prop.**

Never use these approaches:

- ❌ Creating CSS files (e.g., `agent-styles.css`, `theme.css`)
- ❌ Creating `<style>` tags or internal stylesheets
- ❌ Using `style` attribute on the component
- ❌ Using `className` prop
- ❌ Inline styles
- ❌ CSS modules
- ❌ Styled-components or any CSS-in-JS libraries

**Why:** The component controls its own internal styling through the `styleTokens` API. External CSS cannot reach into the embedded iframe.

## Invalid Implementation Approaches

Never do these:

- ❌ Create custom chat UIs from scratch
- ❌ Use third-party chat libraries (socket.io, WebSocket libraries, etc.)
- ❌ Call `embedAgentforceClient` directly from `@salesforce/agentforce-conversation-client`
- ❌ Build custom WebSocket or REST API chat implementations

**Why:** The AgentforceConversationClient component is the official wrapper that handles authentication, Lightning Out 2.0 initialization, and all communication with Salesforce agents. Custom implementations will not work.

## Invalid Update Patterns

When updating an existing component:

- ❌ Delete and recreate the component
- ❌ Remove all props and start over
- ❌ Copy the entire component to a new file

**Why:** This loses configuration, introduces errors, and creates