Employee AgentによるプロアクティブUXの実装：ACC API活用の技術ポイントと課題回避策

この記事はバージョン Summer ’26 において執筆しています。
現在の動作と異なる場合がありますので、ご認識おきください。

Agentforce Conversation Client (ACC) API（lightning/accApi）を活用することで、特定のレコードを開いたタイミングやシステムイベントを受信したタイミングで、システム側からAgentforceを自動起動させることが可能になります。

しかし、ユーザーの業務を妨げないプロアクティブなUXを構築しようとする際、公式ドキュメントの記載のみでは解決が難しい技術的な制約やエラーに直面することがあります。

本記事では、3つの実践的なユースケースにおけるUXの設計意図と、開発時に直面した技術的な課題およびその回避策を解説します。全体のソースコードはGitHubで公開していますので、併せて参照してください。

DXforce Point for Developers

今回の記事で作成したコンポーネントの全ソースコードをGitHubで公開しています。ぜひ Clone して、あなたの組織で動かしてみてください。

GitHub - dxforce-site/AgentforceConversationClient

Contribute to dxforce-site/AgentforceConversationClient development by creating an account on GitHub.

ACC APIのデータ認識仕様
プロアクティブUXを体現する3つの実践ユースケース
ACC実装時における注意点
まとめ
参考URL

ACC APIのデータ認識仕様

Agentforceは、ユーザーが現在開いているレコード（商談やケースなど）のコンテキストを自律的に認識する仕様を持っています。そのため、LWC側でレコードの各項目データを個別に取得し、プロンプト文字列に結合して渡す処理は不要です。

バックエンドのAI側が自律的にデータハンドリングを行うため、フロントエンド（画面側）の実装は大幅に簡略化され、開発コストの抑制に寄与します。LWC側に記述するコードは、以下のようにパネルを開いて指示を送信する最小限の実装で完結します。

import { open, execute } from 'lightning/accApi';

async function triggerAgent() {
    // パネルを自動で開く
    await open('0Xx...');       
    // 自然言語で指示を送信
    await execute('メールを作成して', '0Xx...'); 
}

プロアクティブUXを体現する3つの実践ユースケース

単にAPIを呼び出すだけでなく、現場のオペレーションに溶け込むためのアーキテクチャを採用しています。

1. 商談フォローアップの自動提案（accOpportunityFollowUp）

営業担当者が商談レコードを開いた際、現在のフェーズや活動履歴から「次に行うべきフォローアップ」を自動提案するコンポーネントです。

UXの設計: レコードを開くたびに発火してノイズにならないよう、「タブを開いている間、最初の1回のみ」動作するように制御しています。また、AIが生成したテキストを直接出力するのではなく、Custom Lightning Types を用いてチャットパネル内にカスタムLWC（インラインエディタ）を埋め込み、ユーザーが最終確認・編集できる「ヒューマン・イン・ザ・ループ」の設計としています。
アーキテクチャの制約: 「Agentforceに下書きを作成させ、それを初期値としてカスタムフォーム（LWC）に表示してユーザーに最終確認させる」というUXを標準機能で実現しようとすると、Agentforce特有の制約にぶつかりました。AIがアクションの入力パラメータを自力で埋めてしまうと、Agentforceの推論エンジンは「ユーザーへのフォーム提示は不要」と判断し、画面表示をスキップして即座にバックグラウンドで送信処理を実行してしまうためです。
制約への対応: 上記の制約があるため、LWCが画面に描画された後（connectedCallback）に、LWC自身からApexを非同期に呼び出してプロンプトを実行するアーキテクチャを採用しています。また、この構造により長文生成時のフリーズ感をなくし、裏でApex（プロンプトによる文面生成）を待つ間にスケルトン（Stencil）アニメーションを表示するというモダンな体験を提供する副次効果も得ました。

2. クレーム対応の条件付きアドバイス（accCaseClaimAdvice）

サポート担当者がケースを開いた際、その案件が「クレーム」であった場合にのみ、過去の履歴やナレッジを踏まえた初期対応アドバイスを提示します。

UXの設計: すべてのケースでAIを起動するのではなく、担当者が最も支援を必要とする瞬間にだけ介入させることで、Flex Creditの無駄な消費を抑え、現場の生産性を高めるアプローチをとっています。

3. 重大システム障害時のアラート連携（accMessagingSystemAlert）

コールセンター全体に影響するシステム障害発生時、リアルタイムチャットで対応中のオペレーターに対し、個別のお詫び文案を即座に提供します。

UXの設計: オペレーターが「今どの画面を見ているか」によって振る舞いを変えています。チャット画面（MessagingSession）を開いている場合はパネルを自動展開し、別の作業をしている場合はユーティリティバーをハイライトさせるのみとし、ユーザーの作業を妨げないよう配慮しています。

ACC実装時における注意点

組織内でEmployee Agentを拡張、または外部プログラムと連携させる際、公式ドキュメントの記載と実際の挙動が異なる仕様や、暫定的な挙動の不具合が確認されています。以下に検証に基づく事実と対策をまとめます。

1. エージェント指定における botId の特定

呼び出すエージェントを明示する際、Agent BuilderのURLに表示されているプロジェクトID（1bY から始まる文字列）を指定してもエージェントの切り替えは行われません。指定すべき botId は、Salesforce内部の BotDefinition オブジェクトのレコードID（0Xx から始まる18桁の文字列）です。

開発環境において、以下のSOQLクエリ等を用いて真のIDを取得し、カスタムメタデータ等に定義して利用する必要があります。

SELECT Id, MasterLabel, DeveloperName FROM BotDefinition

2. 複数エージェント存在時におけるセッション切り替えの不具合

2026年6月25日現在のDeveloper Edition環境における検証では、組織内に複数のエージェントが存在する場合、open(botId) や execute(utterance, botId) に特定のIDを指定しても、デフォルトのエージェントが優先して開く、あるいはチャットパネルが白化してフリーズする挙動が確認されています。この際、チャット履歴のリセットボタンを手動で押すことで処理が開始されます。

現時点のAPIバージョンにおける暫定的な回避策として、ACC APIを使用する運用においては、1ユーザーあたりがアクセスできるEmployee Agentをひとつに絞るプロファイル設計、あるいは権限セットによるルーティングの制限を推奨します。

3. Apexからプロンプトテンプレートを呼び出す際の引数仕様

LWCのバックエンドなどで ConnectApi.EinsteinLLM.generateMessagesForPromptTemplate() を使用してプロンプトテンプレートを実行する場合、引数として単なるレコードIDの文字列を渡すと、システム内部エラー（500エラー）が発生します。

このエラーを回避するためには、値を Map<String, Object>{'id' => recordId} の形式でラップし、キー名を Input:オブジェクトAPI名 と厳密に一致させる必要があります。また、環境依存のエラーを防止するため、additionalConfig を明示的に初期化してセットする実装が必須です。

ConnectApi.EinsteinPromptTemplateGenerationsInput promptInput = new ConnectApi.EinsteinPromptTemplateGenerationsInput();

// 内部エラー（500）回避のための追加設定初期化
promptInput.additionalConfig = new ConnectApi.EinsteinLlmAdditionalConfigInput();

ConnectApi.WrappedValue recordValue = new ConnectApi.WrappedValue();
// 単なるID文字列ではなくMapでラップする
recordValue.value = new Map<String, Object>{'id' => recordId};

Map<String, ConnectApi.WrappedValue> valueMap = new Map<String, ConnectApi.WrappedValue>();
// キー名は Input: + SObject名
String inputKey = 'Input:' + recordId.getSObjectType().getDescribe().getName();
valueMap.put(inputKey, recordValue);

promptInput.inputParams = valueMap;

4. 設定のハードコード排除

対象のエージェントID（botId）や利用対象のプロファイルをソースコードに直接記述することは推奨されません。GitHubに公開したソースコードでは、EmployeeAgentConfig__mdt カスタムメタデータに設定を切り出し、LWC側で権限判定を行っています。これにより、権限のないユーザーが画面を開いた場合はコンポーネントが沈黙し、本番環境での安全な段階的リリースが可能になります。