implementing-ui-bundle-agentforce-conversation-client

Agentforce Conversation Client の管理

厳守事項： カスタムエージェント、チャットボット、チャットウィジェットコンポーネントは絶対に作成しないでください。このような依頼はすべて、以下のドキュメントに従って @salesforce/ui-bundle-template-feature-react-agentforce-conversation-client から既存の <AgentforceConversationClient /> をインポートしてレンダリングすることで対応してください。このコンポーネントのプロパティでサポートされていない要件については、制限事項を伝えてください。別の方法を独自に考案してはいけません。

前提条件

コンポーネントを動作させるには、ユーザーが以下の Salesforce 設定を構成する必要があります。エージェントの埋め込みが正常に完了したら、必ず前提条件について案内してください。

信頼済みドメイン（ローカル開発の場合のみ必須）：

• 設定 → セッション設定 → インラインフレームの信頼済みドメイン → ドメインを追加
  • ローカル開発：localhost:5173（Vite 開発サーバーのデフォルトポート）
  • 警告： 本番環境にデプロイする前に、この信頼済みドメインのエントリを削除してください。

手順

ステップ 1：コンポーネントがすでに存在するか確認する

すべてのアプリファイル（実装ファイルを除く）を検索して、既存の使用箇所を確認します。

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}$ に一致し、ユーザーがほかのプロパティの更新を希望している場合 → ステップ 4（プロパティを更新）へ進みます
• agentId が ^0Xx[a-zA-Z0-9]{15}$ に一致し、ユーザーがチャットクライアントの「埋め込み」または「追加」を依頼している場合 → 「Agentforce Conversation Client は、エージェント ID <agentId> で <file> にすでに埋め込まれています。エージェントを変更するか、ほかのプロパティを更新しますか？」と伝えます。
  • エージェントを変更 → ステップ 2
  • プロパティを更新 → ステップ 4b
• agentId がない、空である、または ^0Xx[a-zA-Z0-9]{15}$ に一致しない場合 → ステップ 2（有効な ID が必要）へ進みます
• 見つからない場合 → ステップ 2（新規追加）へ進みます

ユーザーからエラーの報告があった場合：

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

ステップ 2：Agent ID を解決して検証する

前提条件

1. sf CLI が利用可能か確認します：

   sf --version
   

   失敗した場合：

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

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

   sf org display --json
   

   失敗した場合：

   • 次のように伝えます：「認証済みの組織が見つかりません。」
   • 次のように尋ねます：「今すぐ組織に接続しますか？認証するには sf org login web を実行してください。」
     • ユーザーが認証 → クエリを再試行し、続行します。
     • ユーザーが拒否 → 「Setup → Agentforce Agents に移動してエージェント名をクリックし、URL から ID をコピーすると、エージェント ID を手動で確認できます。今すぐ入力しますか、それともこの手順をスキップしますか？」
       • ユーザーが ID を入力 → 形式を検証して保存し、ステップ 3 に進みます。
       • スキップ → プレースホルダー <YOUR_AGENT_ID> を使用してステップ 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 つ選択 → 選択された Id をステップ 4 で使用するために保存します。
• ユーザーが選択を拒否（「スキップ」「いいえ」「設定したくない」） → そのまま受け入れて次の手順に進みます。再度尋ねないでください。ステップ 4 では、新規インストールの場合はプレースホルダー <YOUR_AGENT_ID> を使用します。既存のプロジェクトでは、コンポーネントをそのままにします。

アクティブなエージェントがある場合 — パス B（ステップ 1 で既存の agentId が渡され、形式チェックに合格した場合）：

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

• ID が見つかり、エージェントが Active → 「エージェント 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 からのみ有効化します）
• ファイルへの書き込みは行いません（Step 4 で行います）

Step 3: 標準のインポート方法

アプリのコードでは、デフォルトで次のインポートパスを使用します：

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

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

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

ユーザーがそのアプリでパッチ済みのローカルコンポーネントを使用するよう明示的に求めた場合に限り、ローカルの相対インポート（例：./components/AgentforceConversationClient）を使用してください。

ファイルの検出結果だけからインポートパスを推測してはいけません。コードベース全体で一貫したパッケージインポートを優先してください。

Step 4: コンポーネントの追加または更新

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

• Step 1 でコンポーネントが見つからない → **4a（新規インストール）**に進みます
• Step 1 でコンポーネントが見つかった → **4b（既存コンポーネントの更新）**に進みます

4a — 新規インストール

1. ユーザーが対象ファイルをすでに指定している場合は、そのファイルを使用します。指定していない場合は、ユーザーに 「AgentforceConversationClient を追加するファイルを指定してください」 と尋ねます。対象ファイルが確認できるまで先に進まないでください。
2. 対象ファイルを読み込み、既存のインポートと TSX の構造を確認します。
3. 既存のインポートと並べて、ファイルの先頭にインポートを追加します。Step 3 の標準パッケージインポートを使用します：

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

4. コンポーネントの return ブロックに <AgentforceConversationClient /> の TSX を挿入します。既存のコンテンツと兄弟要素になる位置に配置し、既存の TSX をラップしたり、構造を変更したりしてはいけません。Step 2 で取得した実際の agentId を使用します。agentId が解決されていない場合（ユーザーが Step 2 をスキップした場合）は、次のプレースホルダーを使用します：

agentId が解決されている場合：

<AgentforceConversationClient agentId="0Xx8X00000001AbCDE" />

agentId が解決されていない場合（ユーザーがスキップした場合）：

<AgentforceConversationClient agentId="<YOUR_AGENT_ID>" />

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

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

1. Step 1 で特定したファイルを読み込みます。
2. 既存の <AgentforceConversationClient ... /> TSX 要素を特定します。
3. ユーザーが求めた変更のみを適用します。ルール：
   • ユーザーが求めた新しい props を追加します。
   • ユーザーが更新を求めた prop の値を変更します。
   • ユーザーが言及していない prop と値はすべて維持します。削除、並べ替え、再フォーマットはしないでください。
   • コンポーネントを削除して作り直してはいけません。
4. Step 2 が実行され（相互確認または新規選択）、新しいエージェント ID が解決された場合は、既存の agentId の値を新しい値に置き換えます。
5. 現在の agentId がすでに有効で、ユーザーが変更を求めておらず、Step 2 で有効であることが確認された場合は、そのままにします。

Step 4 後のエラー処理

コンポーネントの設定後にユーザーからエラーが報告された場合（例：「動作しない」「エラーが表示される」）、Step 2 に進み、設定済みの agentId が組織で有効かどうかを確認します。エージェントが有効であること、存在すること、接続先の組織に属していることを相互確認します。

ステップ 5：props を設定する

利用可能な props（コンポーネントに直接指定）：

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

例：

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

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

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

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

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

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

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

• すべての外観のカスタマイズ（色、フォント、間隔、境界線、角丸、影）は、必ず styleTokens prop を通じて行ってください。例外はありません。
• 以下の表に記載されたトークン名のみを使用してください。独自のトークン名を作成しないでください。
• CSS ファイル、style 属性、className、ラッパー要素を使ってスタイルを設定しないでください。これらの方法は機能せず、コンポーネントによって無視されます。
• ユーザーが以下のトークンに対応しない外観の変更を求めた場合、現在のトークンセットではその変更がサポートされていないことを伝えてください。

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

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

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

よくある間違いを避けるには： 以下を確認するために references/constraints.md を参照してください。

• 無効な props（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 — 無効な props、無効なスタイル設定方法、編集してはいけないファイル
references/troubleshooting.md	セットアップ後 — エージェントの有効化、信頼済みドメイン、Cookie の設定