> 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/work/maigpt-system-integration-guide/maigpt-integration.md). # MaiGPT 連携：適切な Agent の選択と機能の補完 MaiGPT を自社システムに連携する方法：MaiGPT 製品と MaiGPT ウィンドウモードの違いを理解し、顧客向けには独自の Agent に画像生成などのツールを追加し、組織メンバー向けにはメンバーの認証情報で MaiGPT 製品を埋め込みます MaiAgent プラットフォームでは、「MaiGPT」は異なる 2 つのものを指します。連携前に違いを理解しておくと、確認のやり取りを大幅に減らせます。 | | **MaiGPT 製品**（組織に組み込まれた Agent） | **MaiGPT ウィンドウモード**（Web Chat SDK のレイアウトの一種） | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | 概要 | 各組織に自動で提供され、MaiAgent が一元管理する企業向け AI ワークスペースです。AI 画像生成、Deep Research、コネクタなどが組み込まれています。[MaiGPT とは？](https://docs.maiagent.ai/work/maigpt)をご覧ください | `enabledWindowModes: ['maigpt']` で有効にする**ChatGPT のようなフルインターフェース**（サイドバーの会話履歴、検索、設定）です。フロントエンドの表示形式のみを提供します | | 利用できるユーザー | 組織の**メンバー**がログインして利用します（Web、iOS App、LINE、Microsoft Teams）。権限は[ロール別の利用権限](https://docs.maiagent.ai/org/roles/maigpt-role-permissions)で制御します | 匿名の訪問者や[連絡先の認証情報](/tech/ja/serve/web-chat-sdk.md#identify-users)を使用する場合も含め、どの Web Chat にも適用できます | | 自社システムへの埋め込み | **組織メンバー向けにのみ利用できます**。会話の作成にはメンバーの認証情報と `maigpt_access` 権限が必要です。Web Chat ID だけで直接埋め込むと `400 MaiGPT を利用する権限がありません。` が返ります。メンバー向けに埋め込む場合は、[メンバー認証による埋め込み](#member-embed)に従い、自社バックエンドでメンバートークンを発行します | **可能です**。本ページの第 2、3 節で説明します | | カスタマイズ | **できません**。指示、モデル、ツール、スキルはすべてプラットフォームが一元設定します。組織側はロール権限によって利用範囲を**制限**することだけができます | **可能です**。インターフェースの背後で動く AI Agent は自分で作成するため、指示、モデル、ツール、ナレッジベースをすべて自分で決められます | **結論**：用途は 2 つに分かれます。**組織メンバーではない自社の顧客**向けには、**独自の AI Agent を作成し、必要なツールを追加して MaiGPT ウィンドウモードで埋め込みます**（第 2、3 節）。**組織メンバー**向けに MaiGPT 製品そのものの機能（画像生成、Deep Research、コネクタ、ロール権限）を利用する場合は、[メンバー認証による埋め込み](#member-embed)（第 5 節）を使用し、自社バックエンドでメンバーの短期トークンを発行します。 ## 1. よくある症状と対処方法 | 表示される症状 | 原因 | 対処方法 | | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | インターフェースは MaiGPT のように見えるものの、応答は通常のチャットと同じで、画像生成を依頼すると AI が「画像を生成できません」と答えます | 通常の AI Agent を埋め込んでおり、（1）応答モードが **Agent モード**ではない、または（2）画像生成などのツールが設定されていません | [第 2 節](#build-agent)に従って Agent モードに切り替え、ツールを追加します | | チャットウィンドウが開かず、「会話の作成に失敗しました（HTTP 400）」と表示され、API が `MaiGPT を利用する権限がありません。` を返します | 埋め込んだ Web Chat ID が組織に組み込まれた MaiGPT 製品のもので、訪問者にメンバーの認証情報がありません | 顧客向け → 独自 Agent の Web Chat ID に変更します（[第 3 節](#embed)）。メンバー向け → [メンバー認証による埋め込み](#member-embed)に従ってメンバートークンを渡します | | 管理画面の AI Agent 一覧 API に MaiGPT が見つかりません | `GET /api/v1/chatbots/` は組織が独自に作成した Agent だけを返し、MaiGPT 製品は含みません | これは想定どおりの動作です。連携の対象には独自に作成した Agent を使用します |
組織に組み込まれた MaiGPT の Web Chat を埋め込むと、チャットウィンドウに会話作成の失敗が表示されます

組織に組み込まれた MaiGPT の Web Chat の埋め込み：訪問者はログイン済みのメンバーではないため、会話の作成が拒否されます（HTTP 400）

## 2. 画像生成やツールの利用ができる AI Agent を作成する 以下では「AI 画像生成」を例に説明します。ほかの機能（Web 検索、Web ページの取得、MCP ツール、自社の API ツール）も同じ方法で追加できます。 {% stepper %} {% step %} ### AI Agent を作成する 管理画面の「AI 機能 → AI アシスタント」で新しい AI Agent を作成し、ロール指示とモデルを設定します。操作方法はユーザーマニュアルの[Agent の作成](https://docs.maiagent.ai/build/agent/setup)をご覧ください。 {% endstep %} {% step %} ### 応答モードを「Agent モード」に切り替える Agent の「応答モード設定」を開き、応答モードを **Agent モード**に変更します。 {% hint style="danger" %} ツールを呼び出すのは Agent モードだけです。デフォルトの「RAG 質疑応答」モードは応答が速いものの、**ツールは一切使用しません**。画像生成ツールを追加したのに画像を生成しない場合、これが最もよくある原因です。 {% endhint %} {% endstep %} {% step %} ### ツールを追加する Agent の「ツール」ページを開き、「ツールを選択」をクリックして、必要な組み込みツールを選択します。例： * **画像生成**：`Global_Image_Tool_OpenAI_GPT_Image_2`、`Global_Image_Tool_Gemini_3` など（1 つ選択すれば十分です。モデルの違いは[組み込み AI 画像生成ツール](https://docs.maiagent.ai/build/tools/ai-image-generation-guide)をご覧ください） * **Web 検索**：`Global_Tavily_Search_Tool` * **Web ページの取得**：`Global_Web_Fetch_Tool` * 自社システムの [API ツール](/tech/ja/api-integration/api-tool-engineering-guide.md)または MCP ツール 詳しい操作方法はユーザーマニュアルの[Agent へのツールの設定](https://docs.maiagent.ai/build/tools/configure_tools)をご覧ください。 {% endstep %} {% step %} ### Web Chat の会話プラットフォームを作成する 「カスタマーサポート会話 → 会話プラットフォーム」で、この Agent に **Web Chat** を追加し、`webChatId` を取得します。操作方法は[会話プラットフォームの連携：Web サイト](https://docs.maiagent.ai/build/choose-channel/web-chat/website)をご覧ください。 {% endstep %} {% endstepper %} ### API で自動化する（ISV による顧客向け環境の構築） 上記の 4 ステップには、それぞれ対応する API があります。ソフトウェアベンダーが顧客ごとの利用開始時にプログラムで設定する用途に適しています。認証方法と API Key の取得方法は[クイックスタート](/tech/ja/api-integration/quickstart.md)をご覧ください。 ```bash # 1. 組み込みツールの一覧を取得し、画像生成ツールの id を取得します GET /api/v1/tools/ # 2. AI Agent を作成します：応答モードを agent に設定し、ツールを追加します POST /api/v1/chatbots/ { "name": "Acme GPT", "instructions": "あなたは Acme 社の AI アシスタントです。日本語で回答してください。", "largeLanguageModel": "", "embeddingModel": "", "rerankerModel": "", "replyMode": "agent", "tools": [""] } # 3. Agent の Web Chat 会話プラットフォームを作成します（応答の channel.id が webChatId です） POST /api/v1/inboxes/ { "name": "Acme GPT", "chatbot": "", "channelType": "web", "channel": { "name": "Acme GPT", "theme": { "primaryColor": "#1890ff", "...": "..." }, "darkTheme": { "primaryColor": "#404040", "...": "..." } } } ``` * 既存 Agent のモード変更やツールの追加には `PATCH /api/v1/chatbots/{id}/` を使用します。`tools` にはツール id の配列全体を渡します（全体を置き換えます） * `theme` と `darkTheme` は必須です。フィールドの一覧は、まず `GET /api/v1/web-chats/{既存の webChatId}/` で既存の設定を取得してコピーできます * Web Chat は必ず `POST /api/v1/inboxes/` で受信トレイと一緒に作成します。`POST /api/v1/web-chats/` を直接呼び出すと、受信トレイのない孤立した Web Chat が作成され、埋め込み時に 404 が返ります ## 3. MaiGPT ウィンドウモードで埋め込む 第 2 節で取得した `webChatId` を使用し、[MaiGPT モードの埋め込み](/tech/ja/serve/web-chat-sdk/web-chat-maigpt-mode.md)に従って埋め込みコードをページに追加します。 ```html
``` Agent がログイン中のユーザーを識別し、その権限で自社 API を呼び出せるようにするには、[ソフトウェアベンダー向け連携ガイド](/tech/ja/serve/vendor-integration-guide.md)に従って `contactId` または `auth` を追加します。 ### 検証：同じ埋め込みコードで機能を追加する前と後 以下の 2 枚の画像は、同じ AI Agent と同じ埋め込みコードを使用しています。違いは「応答モード＋ツール」の設定だけです。 {% tabs %} {% tab title="追加前：RAG 質疑応答モード、ツールなし" %}
MaiGPT ウィンドウモードで、ツールを設定していない Agent が画像を生成できないと回答します

インターフェースは MaiGPT ウィンドウモードですが、Agent は「画像を生成、作成、制作できません」と回答します

{% endtab %} {% tab title="追加後：Agent モード＋画像生成ツール" %}
MaiGPT ウィンドウモードで、画像生成ツールを設定した Agent が画像を直接生成します

同じ埋め込みコードで、Agent が画像生成ツールを呼び出し、会話内に直接画像を生成します

{% endtab %} {% endtabs %} ## 4. MaiGPT 製品そのものを使用すべきケース 「自社製品に埋め込んで顧客に提供する」のではなく、「社員が使える ChatGPT 相当の社内 Agent が欲しい」場合は、MaiGPT 製品を直接使用する方法が最も簡単です。 * 社員は組織メンバーとしてプラットフォームにログインするだけで利用できます。[Web 版](https://docs.maiagent.ai/work/maigpt/access/web)、[iOS App](https://docs.maiagent.ai/work/maigpt/access/ios)、[LINE](https://docs.maiagent.ai/work/maigpt/access/line)、[Microsoft Teams](https://docs.maiagent.ai/work/maigpt/access/teams)からアクセスできます * 画像生成、Deep Research、コネクタ、スキルはすべて組み込まれています。管理者は[ロール別の利用権限](https://docs.maiagent.ai/org/roles/maigpt-role-permissions)で、誰がどの機能を利用できるかを決めるだけです * 社内専用の知識を追加するには、メンバーが参照できる範囲にナレッジベースを設定します。別の Agent を作成する必要はありません 「自社システムに埋め込むが、ユーザーは組織メンバー」→ 第 5 節のメンバー認証による埋め込みを使用します。「メンバー以外（顧客、登録ユーザー）向け」「自社の API ツールを追加したい」「指示やモデルを変更したい」のいずれかに該当する場合は、第 2、3 節の独自 Agent を作成する方法を使用します。 ## 5. メンバー認証による埋め込み：組織メンバー向けに MaiGPT 製品を自社システムに埋め込む {% hint style="info" %} 最初から順に進めたい場合は、[MaiGPT を自社システムに追加する](/tech/ja/work/maigpt-system-integration-guide.md)をご覧ください。本節は各パラメーターの完全なリファレンスです。 {% endhint %} 対象となるケース：自社システムのユーザーが**MaiAgent 組織のメンバーでもあり**（企業ポータル、社員用ワークスペース、ISV が管理する企業内システムなど）、別の Agent を作成せずに MaiGPT 製品そのものを利用したい場合です。**自社バックエンド**が組織 API Key を使用してログイン中のメンバーの短期トークンを発行し、フロントエンドでは SDK の既存のメンバー認証情報の注入設定を使用して MaiGPT の Web Chat を埋め込みます。 ```mermaid sequenceDiagram participant U as メンバーのブラウザー participant P as 自社バックエンド participant M as MaiAgent API participant W as MaiGPT Web Chat U->>P: ログイン済みで MaiGPT を含むページを開きます U->>P: SDK が auth.getToken を呼び出し、自社バックエンドにリクエストします P->>M: POST /api/v1/members/embed-tokens/（Api-Key、メンバーの email を指定） M-->>P: accessToken（15 分）、organizationId、member.userId P-->>U: getToken に返します U->>W: SDK がメンバーとして会話を作成し、メッセージを送信します Note over U,W: トークンの期限が近づくと iframe が SDK に通知し、SDK が getToken を再度呼び出して自動更新します ``` ### 前提条件 * **組織 API Key** が必要です。所有者は組織オーナー、またはロールに「組織概要」の管理権限を持つユーザーである必要があります。メンバーを管理できる人が発行した Key だけが、メンバーの代理でトークンを発行できます。API Key の取得方法は[クイックスタート](/tech/ja/api-integration/quickstart.md)をご覧ください * 埋め込み先のユーザーは既にその組織のメンバーで、ロールに MaiGPT の利用権限が必要です（[MaiGPT のロール別利用権限](https://docs.maiagent.ai/org/roles/maigpt-role-permissions)）。メンバーが存在しない場合、トークン発行は 404 を返し、自動でメンバーを作成しません。メンバーになる方法（SCIM プロビジョニング API、管理画面からの招待、SSO）は[メンバーのプロビジョニング](/tech/ja/identity-and-access/member-provisioning.md)をご覧ください。ISV が管理する場合の標準的な連携方法は、SCIM でメンバーを作成し、本節の方法でトークンを発行する構成です * MaiGPT の Web Chat ID：`GET /api/v1/web-chats/` の応答に含まれる、名前が `MaiGPT` で `accessType` が `web` のレコードです ### ステップ 1：バックエンドでメンバートークンを発行する 自社バックエンドにログイン済みのユーザーだけが呼び出せるエンドポイント（例：`GET /maigpt-token`）を作成し、内部で MaiAgent を呼び出します。フロントエンドの SDK が必要に応じてこのエンドポイントを呼び出します。 ```bash curl -X POST https://api.maiagent.ai/api/v1/members/embed-tokens/ \ -H "Authorization: Api-Key <自社の組織 API Key>" \ -H "Content-Type: application/json" \ -d '{"email": "alice@acme.com"}' ``` `email` または `memberId` のどちらかを指定します（`memberId` は MaiAgent のメンバー ID です）。成功時は `201` が返ります（`expiresAt` はエポックミリ秒です）。 ```json { "accessToken": "<メンバーの短期 JWT>", "organizationId": "8d2f...-...", "expiresAt": 1789906401000, "member": { "id": "c1a4...-...", "userId": "5e77...-...", "email": "alice@acme.com", "name": "Alice" } } ``` | ステータスコード | 意味 | | -------- | ----------------------------------------------- | | `400` | `email` と `memberId` の両方を指定した、またはどちらも指定していません | | `401` | Api-Key で認証していません（メンバーのログイントークンや匿名リクエストは拒否されます） | | `403` | API Key の所有者が組織オーナーではなく、組織管理権限もありません | | `404` | 指定したメンバーが存在しない、無効になっている、またはこの Key の組織に属していません | {% hint style="warning" %} **トークンのルール**：有効期間は **15 分**で固定され、refresh token は発行されず、延長もできません。同じメンバーに繰り返し発行でき、古いトークンも期限までは有効です。このトークンは**Web Chat の会話にのみ使用できます**（会話の作成、メッセージ送信、引き継ぎ後の会話継続の 3 つの呼び出し）。`/api/v1/` の任意のエンドポイント、その他の会話管理操作、WebSocket に使用すると、すべて `401` が返ります。発行のたびに組織の API リクエストログに監査用の記録が残ります（応答内のトークンは記録されません）。 {% endhint %} ### ステップ 2：フロントエンドの SDK にトークン取得関数を渡す 埋め込み設定は[第 3 節](#embed)と同じですが、`auth.getToken` を追加し、`webChatId` を MaiGPT の Web Chat ID に変更します。 ```html
``` `getToken` が返すオブジェクトのフィールド： | フィールド | 必須 | 説明 | | ---------------- | -- | -------------------------------------------------------------------------------------------------- | | `accessToken` | ✅ | ステップ 1 の応答に含まれる `accessToken` です | | `organizationId` | ✅ | ステップ 1 の応答に含まれる `organizationId` です | | `sourceId` | 推奨 | ステップ 1 の応答に含まれる `member.userId` です。`auth.sourceId` に設定することもできます。両方を指定した場合は `auth.sourceId` が優先されます | `auth` は `maiagentChatbotConfig` 内に記述する必要があります。これにより SDK は、チャットウィンドウを作成するときに、メンバーの認証情報の注入が完了してから最初の会話を作成することを認識できます。SDK の読み込み後に `MaiAgent.auth.setup()` を呼び出す方法では、認証情報の注入前に最初の会話が匿名で作成され、拒否される場合があります。 {% hint style="danger" %} `sourceId` は応答に含まれる `member.userId` である必要があります。`member.id` や自社システムのユーザー番号ではありません。MaiGPT はこの値を使って会話をメンバーに紐付けます。誤った値を指定すると匿名の会話になり、そのメンバーの MaiGPT 履歴が表示されません。 {% endhint %} ### 有効期限と更新の仕組み * トークンの有効期間は 15 分です。iframe は期限の 60 秒前に SDK に通知し、SDK は `getToken` を再度呼び出して新しいトークンを取得し、注入し直します。**ページや iframe を再読み込みせず、同じ会話をそのまま継続できます**。ユーザー側で操作する必要はありません。 * **`getToken` は毎回 MaiAgent に新しいトークンを要求する必要があり、キャッシュした値を返してはいけません**。SDK はトークン自体の有効期間に基づいて次の更新を予定します。前回と同じトークンを返すと失敗とみなされ、次の項目の再試行処理に進みます。 * `getToken` が失敗した場合（ユーザーがログアウトした、自社バックエンドが 401 を返した場合など）、SDK は 30 秒、60 秒、120 秒後にそれぞれ 1 回再試行します。それでも失敗すると停止し、コンソールにエラーを記録します。トークンの期限が切れた後は次のメッセージの送信が失敗し、既存のエラー通知が表示されます。会話と送信済みのメッセージは消えません。 * ユーザーが自社システムからログアウトするときは `MaiAgent.auth.signOut()` を呼び出します。SDK は認証情報を削除し、更新を停止します。発行済みトークンは最大であと 15 分有効です。別のユーザーがログインした場合は、`MaiAgent.auth.setup()` を再度呼び出すだけで対応できます。前のユーザーの進行中の更新処理は無効になります。 * Web Chat で [Source ID の署名検証](/tech/ja/serve/web-chat-sdk.md#source-id-signature)を有効にしている場合、署名は 1 回限りです。SDK は更新時に最初の `ts`／`sig` を再利用しません。`getToken` の戻り値に新しい署名も含めてください（`{ accessToken, ts, sig }`）。 * `getToken` を使用せず、静的な `auth.accessToken` を直接指定する場合、SDK は更新しません。15 分後に自分で `MaiAgent.auth.setup()` を再度呼び出す必要があります。 ### この方法と独自 Agent の選び方 | | メンバー認証による MaiGPT の埋め込み（本節） | 独自 Agent＋MaiGPT ウィンドウモード（第 2、3 節） | | ------------- | -------------------------------------------------- | --------------------------------- | | ユーザー | 組織メンバーである必要があります | 誰でも利用できます（顧客、登録ユーザー、匿名） | | 機能 | MaiGPT の全機能：画像生成、Deep Research、コネクタ、スキル。ロール権限に従います | 選択したツールとナレッジベースです | | 指示／モデルのカスタマイズ | できません（プラットフォームが一元設定します） | 可能です | | バックエンドの実装 | トークン発行 API を呼び出すエンドポイントが 1 つ必要です | 不要です（任意で連絡先の認証情報の同期を追加できます） | | 課金先 | そのメンバーのクレジットです | その Agent／Web Chat です | ## 6. よくある質問
管理画面の「会話プラットフォーム」に MaiGPT という Web Chat があります。その埋め込みコードを使用できますか？ 埋め込みコードをそのまま使用することはできません。これは組織に組み込まれた MaiGPT 製品の会話プラットフォームで、組織メンバー専用です。外部ページに埋め込むと訪問者にメンバーの認証情報がないため、会話の作成が拒否されます（HTTP 400 `MaiGPT を利用する権限がありません。`）。ユーザーが既に組織メンバーである場合は、[メンバー認証による埋め込み](#member-embed)に従い、自社バックエンドでメンバートークンを発行してから埋め込みます。それ以外の場合は、独自に作成した AI Agent に別の Web Chat を追加してください。
MaiGPT 製品の画像生成、Deep Research、コネクタを、独自 Agent でも利用できますか？ * **画像生成、Web 検索、Web ページの取得**などの組み込みツールは、すべての Agent で利用できます。Agent の「ツール」ページで選択するだけです * **コネクタ**（Notion、Slack、Google Drive など）は、Agent の設定で独自 Agent に紐付けられます * **Deep Research とツールの切り替え**は、MaiGPT ウィンドウモードでエンドユーザーに提供できます。Agent の所有者が管理画面で、その Web Chat の MaiGPT モードを有効にする必要があります。ユーザーマニュアルの [MaiGPT ウィンドウモードの埋め込み](https://docs.maiagent.ai/build/choose-channel/web-chat/maigpt-embed#deep-research)をご覧ください
応答モードは Agent で、画像生成ツールも追加しましたが、画像を生成しません。どうすればよいですか？ 次の順序で確認してください。（1）埋め込みコードの `webChatId` が、この Agent に紐付いた Web Chat のものか確認します（1 つの Agent に複数の会話プラットフォームを設定できます）。（2）組織のプランとクレジットが十分か確認します（画像生成は枚数ごとに課金され、クレジット不足時はメッセージ自体を送信できません）。（3）ロール指示に「テキストのみで回答する」など、ツールの使用を制限する記述がないか確認します。ツール設定の変更は既存の会話にも反映されるため、新しい会話を開始する必要はありません。
MaiGPT ウィンドウモードは floating／sidebar と何が違いますか？ 違いはインターフェースのレイアウトだけです。内部では同じ AI Agent と同じ連絡先の仕組みを使用します。詳しくは [MaiGPT モードの埋め込み](/tech/ja/serve/web-chat-sdk/web-chat-maigpt-mode.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/work/maigpt-system-integration-guide/maigpt-integration.md?ask=&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.