ソフトウェアベンダー向け連携ガイド：顧客向けに AI Agent を組み込みます

ソフトウェアベンダーが自社製品に Web Chat を埋め込み、権限連携を完成させるための一貫したガイドです。埋め込み、一括補完、ログイン同期、Token 更新、ログアウト時の認証情報の失効を説明します

このページは「MaiAgent Web Chat を自社製品に埋め込み、自社のアカウントシステムと権限連携を行う」ソフトウェアベンダー向けです。ユーザーが貴社のシステムにログインすると、AI Agent がそのユーザーを識別し、会話履歴を参照して、そのユーザーの権限で貴社システムの API を呼び出します。

連携は 5 つの段階で進めます。このページでは各段階で行うことと順序を説明し、詳細については対応する技術ドキュメントにリンクしています。

連携の全体像

このページのユーザーは貴社のお客様です（MaiAgent のコンタクトに対応します）。貴社またはお客様の従業員を連携させ、MaiAgent の組織メンバーにする場合（MaiGPT、ロール権限、Credits の利用枠を使用する場合）は、メンバープロビジョニング：SCIM／招待／SSOをご覧ください。

中心となる概念は**コンタクト（Contact）**です。貴社システムの各ユーザーが MaiAgent の 1 つのコンタクトに対応します。コンタクトには会話履歴、パーソナライズ属性、ナレッジベースの検索範囲、ツールの認証情報が紐付きます。権限連携のすべての操作は、この「貴社のユーザー ↔ コンタクト」の対応関係と認証情報を維持するものです。概念の説明はコンタクト（Contact）の概要と連携をご覧ください。

フロントエンドとバックエンドの役割

連携全体を通して、フロントエンドは「チャットウィンドウの読み込み」のみを担当します。Token や API Key を含む呼び出しは、すべてバックエンドから行います：

setup-contact-credentials は API Key が不要な公開エンドポイントです。bulk-import、PATCH、DELETE はすべて Authorization: Api-Key 認証が必要で、バックエンドからのみ呼び出せます。

ステップ 1：Web Chat の埋め込み

最初に、埋め込む AI Agent を決めてください。 埋め込みで使える機能（画像生成、Web アクセス、ツール呼び出し）は Web Chat の背後の Agent 設定によって決まり、埋め込み方式には依存しません。組織に組み込まれた「MaiGPT」製品はログイン済みメンバー専用で、その Web Chat は外部システムに埋め込めません。貴社製品用の AI Agent を作成し、Agent モードに設定して必要なツールを追加してください。MaiGPT 連携：適切な Agent の選択と機能の追加をご覧ください。

製品の形態に応じて埋め込み方式を選択します。どちらも同じ SDK とコンタクトの仕組みを使用します：

形態	適した用途	ドキュメント
チャットバブル（floating／sidebar）	カスタマーサポートや相談などの補助機能です	Web Chat の埋め込みと SDK
MaiGPT モード（ChatGPT のような完全なインターフェース）	ページの主要機能エリア、サイト全体の AI 入口です	MaiGPT モードでの埋め込み

ID 連携を行う Web Chat では、この段階で「埋め込みを許可するドメイン」のリストを設定することをお勧めします（管理者が管理画面の会話プラットフォームの基本設定に入力します）。埋め込みと ID 同期 API の呼び出しが可能なオリジンを制限できます。埋め込みを許可するドメインをご覧ください。

ステップ 2：初回連携——既存ユーザーの一括補完

既存システムを初めて連携する際は、まず既存ユーザーのコンタクトをまとめて作成します。方法は 2 つあります：

方法	適した用途	ドキュメント
Excel による一括インポート（POST /contacts/bulk-import/）	大量のユーザー（1 回あたり最大 10,000 行）に適し、ナレッジ検索範囲と API ツールの認証情報も同時に取り込めます	コンタクトの一括インポート
ID 同期 API をユーザーごとに呼び出す	ログインフローに沿って段階的に補完する場合や、少人数の場合に適しています	既存ユーザーの一括補完

補完時にユーザーの Access Token を取得できなくても問題ありません。先に対応関係を作成し、Token の認証情報はステップ 4 のログインフローで、各ユーザーの次回ログイン時に追加します。

ステップ 3：ユーザー追加時のコンタクト作成

補完後は、貴社システムの「アカウント作成」フローに API 呼び出しを追加し、新規ユーザーが最初から対応するコンタクトを持つようにします：

• バックエンドからID 同期 API（setup-contact-credentials）を呼び出し、貴社システムのユーザー識別子を sourceId に指定します

• 返された contactId を会員テーブルに保存します（推奨するフィールド設計はログインフローへの組み込み位置をご覧ください）

sourceId は冪等性キーです。同じ sourceId で繰り返し呼び出しても更新のみが行われ、重複作成されません。そのため、このステップはステップ 2、ステップ 4 と安全に併用できます。

ステップ 4：ログインと Token 更新

ログインに成功して Access Token が生成されるたびに、バックエンドから同じ ID 同期 API を再度呼び出し、新しい Token（mcpCredentials）を渡します。これにより、AI Agent はそのユーザーの ID と権限で貴社システムの API を呼び出せます。Token 更新時も同じ方法で、もう一度呼び出すだけです。同じコンタクトとツールの組み合わせでは、重複作成ではなく更新になります。完全なシーケンス図と注意事項（非同期呼び出し、失敗してもログインを妨げないこと）は、コンタクトの ID 同期と Token 更新をご覧ください。

フロントエンドでは、ページで Web Chat を初期化する際に contactId を渡します。ユーザーの識別をご覧ください。

AI に貴社システムの API を呼び出させず、ユーザーを識別するだけでよい場合は、バックエンドを使わず、フロントエンドの config に auth を指定するだけでも対応できます。選択の判断材料はフロントエンド auth とバックエンド連携の選び方をご覧ください。

ステップ 5：ログアウトと認証情報の失効

ログアウト時には、作用範囲が異なる 2 つの処理があります。両方の実施をお勧めします：

• フロントエンド：SDK の signOut() を呼び出し、チャットウィンドウを匿名状態に戻します

• バックエンド：そのコンタクトのツール認証情報を削除し、AI がそのユーザーとしてツールを呼び出すことを即座に防ぎます

API の詳細と両者の違いは、ログアウトと認証情報の失効をご覧ください。

連携チェックリスト

段階	操作	ドキュメント
構築	独自の AI Agent を作成します：Agent モード＋画像生成などのツール追加＋Web Chat の作成です	MaiGPT 連携：適切な Agent の選択と機能の追加
構築	Web Chat を埋め込みます（通常または MaiGPT モード）	Web Chat の埋め込みと SDK／MaiGPT モード
構築	管理画面の会話プラットフォームの基本設定に「埋め込みを許可するドメイン」を入力します	埋め込みを許可するドメイン
構築	会員テーブルに maiagent_contact_id フィールドを追加します	ログインフローへの組み込み位置
構築	既存ユーザーを一括補完します	コンタクトの一括インポート
運用	アカウント作成フローで ID 同期 API を呼び出します	コンタクトの ID 同期と Token 更新
運用	ログイン／Token 更新フローで認証情報を更新します	呼び出しのタイミング
運用	ログアウトフローで認証情報を失効させます	ログアウトと認証情報の失効
応用	部門、会員ランクなどのパーソナライズ属性を同期します	コンタクトデータの同期
応用	クエリメタデータでユーザーごとのナレッジベース検索範囲を制限します	ナレッジ管理権限（Query Metadata）