experience-ui-bundle-agentforce-client-generate

Agentforce Conversation Client の管理

このスキルはフレームワークに依存しません。React と Angular の両方の UI Bundle アプリに対応しています。Agentforce クライアントは、同じ Lightning Out の連携処理をラップする 2 つの機能パッケージとして提供されます。アプリのフレームワーク（ステップ 0 で検出）に合ったものを選んでください。

フレームワーク	機能パッケージ	要素	コンポーネントシンボル
React	@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client	<AgentforceConversationClient />	AgentforceConversationClient
Angular	@salesforce/ui-bundle-template-feature-angular-agentforce-conversation-client	<app-agentforce-conversation-client>	AgentforceConversationClientComponent

厳守事項： カスタムのエージェント、チャットボット、チャットウィジェットのコンポーネントは絶対に作成しないでください。このようなリクエストにはすべて、以下の説明に従って、機能パッケージから既存の適切なフレームワーク用コンポーネント（React の <AgentforceConversationClient /> または Angular の <app-agentforce-conversation-client>）をインポートしてレンダリングすることで対応してください。要件がコンポーネントの props／inputs でサポートされていない場合は、その制約を明示してください。代替手段を独自に考案してはいけません。

前提条件

コンポーネントを動作させるには、ユーザーが次の Salesforce 設定を行う必要があります。エージェントの埋め込みに成功したら、必ず前提条件について伝えてください。

信頼済みドメイン（ローカル開発時のみ必要）：

• Setup → Session Settings → Trusted Domains for Inline Frames → Add your domain
  • ローカル開発：localhost:<dev-server-port> — React（Vite）のデフォルトは localhost:5173 です。Angular テンプレートでは別のポートを使用する場合があります（アプリの開発サーバー設定を確認してください。例：localhost:5174）。アプリが実際に使用するポートを追加してください。
  • 警告： 本番環境へのデプロイ前に、この信頼済みドメインのエントリを削除してください。

手順

ステップ 0：アプリのフレームワークを検出する

何よりも先に、対象の UI Bundle アプリが React と Angular のどちらであるかを特定してください。この判定によって、以降のすべてのステップでの検出、インポート、要素の構文、プロパティのバインド方法が決まります。

アプリ（または uiBundle）のルートに対して、同梱の検出ツールを実行してください。検出ツールは決定論的に判定し、react、angular、ambiguous、unknown のいずれか 1 つのトークンだけを出力します。

bash "<skill_dir>/scripts/detect-framework.sh" "<app-or-uiBundle-root>"

検出ツールは、ルートまたはその上位階層にある angular.json、node_modules 以外の任意の package.json に含まれる @angular/core／react、およびソースファイルの特徴（Angular の場合は *.component.ts、app.routes.ts、または @Component でデコレートされたクラス、React の場合は *.tsx／*.jsx）を組み合わせて判定します。

判定結果に応じて対応してください。

• react または angular → そのフレームワークを使用してください。ユーザーに質問してはいけません。検出結果は決定論的です。
• ambiguous（両方のフレームワークが検出された場合）または unknown（どちらも検出されなかった場合）→ 続行する前に、アプリでどちらのフレームワークを使用しているかユーザーに尋ねてください。

特定したフレームワークを以降の手順でも使用してください。

Step 1: コンポーネントがすでに存在するか確認する

すべてのアプリファイル（実装ファイルを除く）を対象に、既存の使用箇所を検索します。検出されたフレームワークに応じて、次の grep を使用します。

React:

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

Angular:

grep -rn "app-agentforce-conversation-client" --include="*.html" --exclude-dir=node_modules
grep -rn "AgentforceConversationClientComponent" --include="*.ts" --exclude-dir=node_modules

重要: 要素を使用しているファイル（共有シェル／レイアウト、ルートコンポーネント、機能ページなど）を探します。Angular の場合、<app-agentforce-conversation-client> タグは *.html テンプレートにあり、コンポーネントはホストの imports: [...] に登録されています。コンポーネントの実装ファイルは開かないでください。

• React: AgentforceConversationClient.tsx / AgentforceConversationClient.jsx
• Angular: conversation.ts、conversation.html、__inherit__conversation.ts、agentforce-embed.service.ts

複数のファイルが見つかった場合: どのコンポーネントファイルを指しているのか、ユーザーに確認します。確認が取れるまでは先に進みません。

見つかった場合: ファイルを読み、現在の agentId の値を確認します。

Agent ID の検証ルール（決定的）：

• 次の形式に一致する場合のみ有効です：^0Xx[a-zA-Z0-9]{15}$
• 意味：0Xx で始まり、全長が18文字です

判断：

• agentId が ^0Xx[a-zA-Z0-9]{15}$ に一致し、ユーザーがほかの props の更新を希望している場合 → Step 4（props の更新）に進みます
• agentId が ^0Xx[a-zA-Z0-9]{15}$ に一致し、ユーザーがチャットクライアントの「埋め込み」または「追加」を依頼した場合 → 次のように伝えます：「Agentforce Conversation Client は、Agent ID <agentId> を使って <file> にすでに埋め込まれています。エージェントを変更するか、ほかの props を更新しますか？」
  • エージェントの変更 → Step 2
  • props の更新 → Step 4b
• agentId がない、空、または ^0Xx[a-zA-Z0-9]{15}$ に一致しない場合 → Step 2 に進みます（実際の ID が必要です）
• 見つからない場合 → Step 2 に進みます（新規追加）

ユーザーがエラーを報告した場合：

ユーザーがコンポーネントが「動作しない」、「エラーが表示される」などと伝えた場合は、具体的なエラーメッセージを尋ねます。その後、設定されている agentId と組織を照合するため、Step 2 に進みます。

Step 2: Agent ID を解決して検証する

前提条件

1. sf CLI が利用できることを確認します：

   sf --version
   

   失敗した場合：

   • 次のように伝えます：「Salesforce CLI（sf）がインストールされていません。組織で利用可能なエージェントを照会するために必要です。」
   • 次のように尋ねます：「インストールしますか？」
     • はい → npm install -g @salesforce/cli でインストールしてから続行します。
     • いいえ → 「Setup → Agentforce Agents でエージェント名をクリックし、URL から ID をコピーすると、Agent ID を手動で確認できます。今ここで指定しますか、それともこの手順をスキップしますか？」
       • ユーザーが ID を指定 → 形式を検証（^0Xx[a-zA-Z0-9]{15}$）して保存し、Step 3 に進みます。
       • スキップ → プレースホルダー <YOUR_AGENT_ID> を使用して Step 4 に進みます。

2. 組織への接続を確認します：

   sf org display --json
   

   失敗した場合：

   • 次のように伝えます：「認証済みの組織が見つかりません。」
   • 次のように尋ねます：「今すぐ組織に接続しますか？認証するには sf org login web を実行してください。」
     • ユーザーが認証 → 照会を再試行して続行します。
     • ユーザーが断る → 「Setup → Agentforce Agents でエージェント名をクリックし、URL から ID をコピーすると、Agent ID を手動で確認できます。今ここで指定しますか、それともこの手順をスキップしますか？」
       • ユーザーが ID を指定 → 形式を検証して保存し、Step 3 に進みます。
       • スキップ → プレースホルダー <YOUR_AGENT_ID> を使用して Step 4 に進みます。

注: ユーザーが独自の agentId を指定した場合でも、実行時にエージェントを動作させるには、組織が接続されている必要があります。組織に接続されていない agentId は機能しません。

すべての Employee Agent を照会する

references/agent-id-resolution.md で定義されている SOQL クエリを実行します。

結果の処理

レコードがまったくない場合：

「この組織に Employee Agent が見つかりません。Setup → Agentforce Agents で作成してください。」

エージェント ID を手動で指定するか、スキップするかをユーザーに尋ねます。スキップする場合は、プレースホルダー <YOUR_AGENT_ID> を使ってステップ 4 に進みます。

すべてのエージェントが非アクティブの場合：

Employee Agent は見つかりましたが、アクティブなものはありません：

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

有効化するには、Setup → Agentforce Agents → エージェント名をクリック → Agent Builder で開く → Activate を押します。 その後、このステップを再実行してください。

エージェント ID を手動で指定するか、スキップするかをユーザーに尋ねます。スキップする場合は、プレースホルダー <YOUR_AGENT_ID> を使ってステップ 4 に進みます。

アクティブなエージェントがある場合 — パス A（新規インストール／既存の agentId がない場合）：

選択肢としてアクティブなエージェントのみを提示します：

チャットウィジェットで使用するエージェントを選択してください。

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

• エージェントが 1 つだけの場合でも、ユーザーに確認し、自動選択しないでください。
• ユーザーが 1 つ選択した場合 → ステップ 4 で使うため、選択した Id を保存します。
• ユーザーが選択を断った場合（「スキップ」「いいえ」「設定したくありません」など）→ そのまま受け入れ、次のステップに進みます。再度尋ねないでください。ステップ 4 では、新規インストールの場合はプレースホルダー <YOUR_AGENT_ID> を使用します。既存のプロジェクトでは、コンポーネントをそのままにします。

アクティブなエージェントがある場合 — パス B（ステップ 1 の既存の agentId が形式チェックを通過した場合）：

既存の agentId とクエリ結果を照合します。

• ID が見つかり、エージェントが Active の場合 → 「Agent ID は『Property Manager Agent』に対応しています。この組織でアクティブです。」そのまま進みます。
• ID が見つかり、エージェントが Inactive の場合 → 「設定されているエージェント『Sales Agent』は存在しますが、Inactive です。有効化するには、Setup → Agentforce Agents → エージェント名をクリック → Agent Builder で開く → Activate を押します。または、別のアクティブなエージェントを選択してください：」→ アクティブなエージェントの一覧を表示します。
• ID が見つからない場合 → 「設定されているエージェント（0Xxxx...）はこの組織に存在しません。削除されたか、別の組織に属している可能性があります。代わりのエージェントを選択してください：」→ アクティブなエージェントの一覧を表示します。アクティブなエージェントがない場合は、有効化の手順とともに非アクティブなエージェントの一覧を表示します。

ユーザーからエラーの報告があった場合は、エージェントがアクティブでも、その名前を提示して、意図したエージェントかどうか確認できるようにします。

クエリエラーの処理

SOQL クエリが失敗した場合は、レスポンスに含まれるエラーメッセージをそのままユーザーに提示します。修正方法を推測せず、返された内容のみを報告してください。例：

「クエリに失敗しました：[error message from response]。組織の権限、またはこのオブジェクトが API バージョンでサポートされているかを確認してください。」

このステップで行わないこと

• GraphQL や Tooling API へのフォールバックは行いません。SOQL のみを使用します。
• 自動選択は行いません（必ずユーザーに確認します）。
• プログラムによる有効化は行いません（Setup UI からのみ可能です）。
• ファイルへの書き込みは行いません（ステップ 4 で行います）。

ステップ 3：標準的なインポート方法

検出されたフレームワークに応じたインポートを使用します。

React — デフォルトでは、アプリのコードでコンポーネントをインポートします。

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

パッケージがインストールされていない場合は、インストールします。

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

Angular — スタンドアロンコンポーネントをインポートし、ホストコンポーネントの imports 配列にも登録します（この登録を行わないと Angular は何もレンダリングしません。React に同等の仕組みはありません）。

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

@Component({
  selector: "app-layout",
  imports: [/* existing imports */, AgentforceConversationClientComponent],
  templateUrl: "./app-layout.html",
})
export class AppLayoutComponent {}

パッケージがインストールされていない場合は、インストールします。

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

ローカル／合成インポート： ユーザーがパッチ適用済み／ローカルコンポーネントの使用を明示的に求めた場合、またはアプリが機能ファイルをすでにローカルで継承している合成 UI Bundle の場合に限り、ローカルの相対インポートを使用します。React の合成アプリでは ./components/AgentforceConversationClient からインポートし、Angular の合成アプリでは継承した機能ファイルから AgentforceConversationClientComponent をインポートします（例：../../../features/agentforce/__inherit__conversation）。ホストがすでにその方法でインポートしている場合は、パッケージへの切り替えではなく、既存のインポートに合わせます。

ファイルの検出結果だけからインポートパスを推測しないでください。コードベース全体で、一貫したインポート方法を優先してください。

ステップ 4：コンポーネントの追加または更新

該当するサブステップを判断します。

• ステップ 1 でコンポーネントが見つからなかった場合 → **4a（新規インストール）**へ進みます
• ステップ 1 でコンポーネントが見つかった場合 → **4b（既存のコンポーネントを更新）**へ進みます

4a — 新規インストール

1. ユーザーがすでに対象ファイルを指定している場合は、そのファイルを使用します。指定していない場合は、ユーザーに 「Agentforce Conversation Client を追加するファイルを指定してください。」 と尋ねます。対象ファイルが確認できるまで先に進まないでください。（React：*.tsx／*.jsx コンポーネント。Angular：ホストコンポーネントの *.html テンプレートに加えて、インポートと imports: [] への登録用の *.ts。）
2. 対象ファイルを読み、既存のインポートとテンプレートの構造を確認します。
3. ステップ 3 のインポートを追加します。Angular では、ホストの @Component({ imports: [...] }) 配列へのコンポーネント登録も必要です。登録しないと要素は何も表示しません。
4. 既存のコンテンツと同じ階層に要素を挿入します。既存のマークアップをラップしたり、構造を変更したりしないでください。ステップ 2 で確認した実際の agentId を使用するか、ユーザーがステップ 2 をスキップした場合はプレースホルダー <YOUR_AGENT_ID> を使用します。

React（JSX）：

<AgentforceConversationClient agentId="0Xx8X00000001AbCDE" />

Angular（テンプレート）：

<app-agentforce-conversation-client agentId="0Xx8X00000001AbCDE" />

5. ユーザーから明示的な依頼がない限り、その他のコード（ラッパー、レイアウトコンポーネント、新しい関数など）は追加しないでください。

Angular のプロパティバインディング規則（重要）： 入力の 名前 は React と同じですが、バインディング構文は異なります。属性だけを記述すると 文字列 になるため、ブール値／数値／オブジェクトには必ず [prop] バインディングを使用してください。

• 文字列 → agentId="0Xx..."、width="420px"（通常の属性で問題ありません）
• ブール値 → [inline]="true"、[headerEnabled]="false"（inline のみの指定は不可です。文字列 "" になります）
• 数値 → [width]="420"
• オブジェクト → [styleTokens]="{ headerBlockBackground: '#0176d3' }"

完了前に確認（Angular）：

• 文字列以外の入力（ブール値／数値／オブジェクト）はすべて [prop] バインディングを使用していること。inline／headerEnabled のみの属性指定がないこと。
• AgentforceConversationClientComponent がホストコンポーネントの @Component({ imports: [...] }) 配列に登録されていること（登録しないと要素は何も表示しません）。

4b — 既存のコンポーネントを更新

1. ステップ 1 で特定したファイルを読みます。
2. 既存の要素（React の場合は <AgentforceConversationClient ... />、Angular の場合は <app-agentforce-conversation-client ...>）を見つけます。
3. ユーザーが依頼した変更のみを適用します。ルール：
   • ユーザーが依頼した新しいプロパティを追加します。
   • ユーザーが更新を依頼したプロパティ値を変更します。
   • ユーザーが言及していないプロパティと値はすべて保持します。削除、並べ替え、書式変更はしないでください。
   • コンポーネントを削除して作り直すことは絶対にしないでください。
4. ステップ 2 が実行され（相互確認または新たな選択）、新しいエージェント ID が確認された場合は、既存の agentId の値を新しい値に置き換えます。
5. 現在の agentId がすでに有効で、ユーザーが変更を依頼しておらず、ステップ 2 で有効であると確認された場合は、そのままにします。

ステップ 4 後のエラー対応

コンポーネントのセットアップ後にユーザーからエラーの報告（例：「動作しません」「エラーが表示されます」）があった場合は、ステップ 2 に戻り、設定された agentId を組織と照合して検証します。エージェントが有効であること、存在すること、接続先の組織に属していることを相互確認します。

ステップ 5：プロパティを設定する

使用可能なプロパティ／入力（両方のフレームワークで名前は同じです。バインド構文のみ異なります。ステップ 4a の Angular のルールを参照してください）：

• agentId（string、必須）- Salesforce エージェント ID
• inline（boolean）- インラインモードでは true を指定し、フローティングモードでは省略します
• width（number | string）- 例：420 または "100%"
• height（number | string）- 例：600 または "80vh"
• headerEnabled（boolean）- ヘッダーの表示／非表示
• styleTokens（object）- すべてのスタイル設定（色、フォント、間隔）に使用します
• salesforceOrigin（string）- 自動解決されます
• frontdoorUrl（string）- 自動解決されます
• agentLabel（string）- エージェントのヘッダータイトル

例：

フローティングモード（デフォルト）：

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

<app-agentforce-conversation-client agentId="0Xx..." />

サイズを指定したインラインモード：

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

<app-agentforce-conversation-client agentId="0Xx..." [inline]="true" width="420px" height="600px" />

エージェントラベルの追加または更新：

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

<app-agentforce-conversation-client agentId="0Xx..." agentLabel="<dummy-agent-label>" />

スタイル設定のルール（必須）：

• すべての外観のカスタマイズ（色、フォント、間隔、枠線、角の丸み、影）は、必ず styleTokens プロパティ／入力を通じて行ってください。例外はありません。
• 以下の表に記載されているトークン名のみを使用してください。カスタムのトークン名を作成しないでください。
• CSS ファイル、style 属性、className／class、またはラッパー要素を使ってスタイルを適用しないでください。これらの方法は機能せず、コンポーネントによって無視されます。
• Angular：トークンは属性だけでなく、[styleTokens]="{ ... }" バインド（オブジェクト）で渡してください。
• ユーザーが以下のトークンに対応しない外観の変更をリクエストした場合、現在のトークンセットではその変更がサポートされていないことを伝えてください。

使用可能なスタイルトークンの完全な一覧については、references/style-tokens.md を参照してください。

複雑なパターンについては、 以下を参照するために references/examples.md を確認してください：

• サイドバーコンテナとレスポンシブなサイズ設定
• ダークテーマと高度なテーマ設定の組み合わせ
• ヘッダーなしのインライン表示、計算されたサイズ
• ホストコンポーネントの完全な例

よくある間違いを避けるには： 以下について references/constraints.md を確認してください：

• 無効なプロパティ（containerStyle、style、className）
• 無効なスタイル設定方法（CSS ファイル、style タグ）
• 編集してはいけないファイル（実装ファイル）

よくある問題

コンポーネントが表示されない場合や認証に失敗する場合は、以下について references/troubleshooting.md を参照してください：

• エージェントの有効化とデプロイ
• localhost の信頼済みドメイン
• Cookie の制限設定

参照ファイル一覧

ファイル	確認するタイミング
references/agent-id-resolution.md	ステップ 2 — SOQL クエリの構造、レスポンス形式、有効化の手順、手動での検索
references/style-tokens.md	ステップ 5 — すべての UI 領域に対応するスタイルトークンの完全なリファレンス
references/examples.md	ステップ 5 — レイアウトパターン、サイズ設定、テーマ設定の組み合わせ、ホストコンポーネントの例
references/constraints.md	ステップ 4 — 無効なプロパティ、無効なスタイル設定方法、編集してはいけないファイル
references/troubleshooting.md	セットアップ後 — エージェントの有効化、信頼済みドメイン、Cookie の設定