> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/ja/serve/vendor-integration-guide.md).

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

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

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

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

## 連携の全体像 <a href="#overview" id="overview"></a>

```mermaid
flowchart LR
    subgraph ONCE["初回の構築"]
        A["Web Chat の埋め込み"] --> B["既存ユーザーの一括補完"]
    end
    subgraph DAILY["日常運用（アカウントのライフサイクル）"]
        C["ユーザー追加時にコンタクトを作成"] --> D["ログイン時に Token を更新"]
        D --> E["Token 更新時に再同期"]
        E --> F["ログアウト時に認証情報を失効"]
    end
    ONCE --> DAILY
```

{% hint style="info" %}
このページのユーザーは**貴社のお客様**です（MaiAgent のコンタクトに対応します）。**貴社またはお客様の従業員**を連携させ、MaiAgent の組織メンバーにする場合（MaiGPT、ロール権限、Credits の利用枠を使用する場合）は、[メンバープロビジョニング：SCIM／招待／SSO](/tech/ja/identity-and-access/member-provisioning.md)をご覧ください。
{% endhint %}

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

### フロントエンドとバックエンドの役割 <a href="#frontend-backend-split" id="frontend-backend-split"></a>

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

```mermaid
flowchart LR
    subgraph FE["貴社のフロントエンド"]
        A["埋め込みコードで SDK を読み込み<br/>config に contactId を指定"]
        B["ログアウト時に signOut を呼び出し"]
    end
    subgraph BE["貴社のバックエンド"]
        C["ログイン／更新：POST setup-contact-credentials"]
        D["一括補完：POST bulk-import"]
        E["データ同期：PATCH contacts"]
        F["ログアウト：DELETE ツールの認証情報"]
    end
    subgraph MA["MaiAgent"]
        G["チャットウィンドウ<br/>chat.maiagent.ai"]
        H["API<br/>api.maiagent.ai"]
    end
    A --> G
    B --> G
    C --> H
    D --> H
    E --> H
    F --> H
```

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

## ステップ 1：Web Chat の埋め込み <a href="#step-embed" id="step-embed"></a>

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

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

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

{% hint style="info" %}
ID 連携を行う Web Chat では、この段階で「埋め込みを許可するドメイン」のリストを設定することをお勧めします（管理者が管理画面の会話プラットフォームの基本設定に入力します）。埋め込みと ID 同期 API の呼び出しが可能なオリジンを制限できます。[埋め込みを許可するドメイン](/tech/ja/serve/web-chat-sdk.md#embed-origin-allowlist)をご覧ください。
{% endhint %}

## ステップ 2：初回連携——既存ユーザーの一括補完 <a href="#step-backfill" id="step-backfill"></a>

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

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

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

## ステップ 3：ユーザー追加時のコンタクト作成 <a href="#step-create-user" id="step-create-user"></a>

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

* バックエンドから[ID 同期 API（`setup-contact-credentials`）](/tech/ja/serve/contacts/contact-credentials-sync.md)を呼び出し、貴社システムのユーザー識別子を `sourceId` に指定します
* 返された `contactId` を会員テーブルに保存します（推奨するフィールド設計は[ログインフローへの組み込み位置](/tech/ja/serve/contacts/contact-credentials-sync.md#login-flow)をご覧ください）

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

## ステップ 4：ログインと Token 更新 <a href="#step-login-refresh" id="step-login-refresh"></a>

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

フロントエンドでは、ページで Web Chat を初期化する際に `contactId` を渡します。[ユーザーの識別](/tech/ja/serve/web-chat-sdk.md#identify-users)をご覧ください。

{% hint style="info" %}
AI に貴社システムの API を呼び出させず、ユーザーを識別するだけでよい場合は、バックエンドを使わず、フロントエンドの config に `auth` を指定するだけでも対応できます。選択の判断材料は[フロントエンド auth とバックエンド連携の選び方](/tech/ja/serve/contacts/contact-credentials-sync.md#frontend-vs-backend)をご覧ください。
{% endhint %}

## ステップ 5：ログアウトと認証情報の失効 <a href="#step-logout" id="step-logout"></a>

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

* **フロントエンド**：SDK の `signOut()` を呼び出し、チャットウィンドウを匿名状態に戻します
* **バックエンド**：そのコンタクトのツール認証情報を削除し、AI がそのユーザーとしてツールを呼び出すことを即座に防ぎます

API の詳細と両者の違いは、[ログアウトと認証情報の失効](/tech/ja/serve/contacts/contact-credentials-sync.md#logout-revoke)をご覧ください。

## 連携チェックリスト <a href="#checklist" id="checklist"></a>

| 段階 | 操作                                                        | ドキュメント                                                                                                                             |
| -- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 構築 | 独自の AI Agent を作成します：Agent モード＋画像生成などのツール追加＋Web Chat の作成です | [MaiGPT 連携：適切な Agent の選択と機能の追加](/tech/ja/work/maigpt-system-integration-guide/maigpt-integration.md)                               |
| 構築 | Web Chat を埋め込みます（通常または MaiGPT モード）                        | [Web Chat の埋め込みと SDK](/tech/ja/serve/web-chat-sdk.md)／[MaiGPT モード](/tech/ja/serve/web-chat-sdk/web-chat-maigpt-mode.md)            |
| 構築 | 管理画面の会話プラットフォームの基本設定に「埋め込みを許可するドメイン」を入力します                | [埋め込みを許可するドメイン](/tech/ja/serve/web-chat-sdk.md#embed-origin-allowlist)                                                             |
| 構築 | 会員テーブルに `maiagent_contact_id` フィールドを追加します                 | [ログインフローへの組み込み位置](/tech/ja/serve/contacts/contact-credentials-sync.md#login-flow)                                                  |
| 構築 | 既存ユーザーを一括補完します                                            | [コンタクトの一括インポート](/tech/ja/serve/contacts.md#bulk-import)                                                                            |
| 運用 | アカウント作成フローで ID 同期 API を呼び出します                             | [コンタクトの ID 同期と Token 更新](/tech/ja/serve/contacts/contact-credentials-sync.md)                                                      |
| 運用 | ログイン／Token 更新フローで認証情報を更新します                               | [呼び出しのタイミング](/tech/ja/serve/contacts/contact-credentials-sync.md#when-to-call)                                                     |
| 運用 | ログアウトフローで認証情報を失効させます                                      | [ログアウトと認証情報の失効](/tech/ja/serve/contacts/contact-credentials-sync.md#logout-revoke)                                                 |
| 応用 | 部門、会員ランクなどのパーソナライズ属性を同期します                                | [コンタクトデータの同期](/tech/ja/serve/contacts/contact-credentials-sync.md#sync-contact-profile)                                            |
| 応用 | クエリメタデータでユーザーごとのナレッジベース検索範囲を制限します                         | [ナレッジ管理権限（Query Metadata）](/tech/ja/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/ja/serve/vendor-integration-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.