MaiGPT 連携：適切なアシスタントの選択と機能の補完

MaiGPTを自社システムに連携します。MaiGPT製品とMaiGPTウィンドウモードの違いを理解し、顧客向けには画像生成などのツールを備えた独自アシスタントを作成し、組織メンバー向けにはメンバーIDでMaiGPT製品を埋め込みます

MaiAgentプラットフォームで「MaiGPT」は2つの異なるものを指します。連携前に区別しておくことで、多くの手戻りを避けられます。

MaiGPT製品（組織組み込みアシスタント）

MaiGPTウィンドウモード（Web Chat SDKのレイアウト）

概要

各組織に自動で提供され、MaiAgentが一元管理する企業向けAIワークスペースです。AI画像生成、Deep Research、コネクタなどの機能を内蔵しています。MaiGPTとは？をご覧ください。

enabledWindowModes: ['maigpt']で有効になる、会話履歴サイドバー、検索、設定を備えたChatGPT風の完全なインターフェースです。フロントエンドの表示形式にすぎません。

利用者

組織のメンバーがログイン後に利用できます（Web、iOS App、LINE、Microsoft Teams）。権限はロール利用権限で制御します。

匿名訪問者や連絡先IDを含め、すべてのWeb Chatで利用できます。

自社システムへの埋め込み

組織メンバー向けに限り可能です。会話作成時に、maigpt_access権限を持つメンバーIDが必要です。そのWeb Chat IDを直接埋め込むと、400 MaiGPTを使用する権限がありません。が返されます。メンバー向けに埋め込む場合は、メンバーIDによる埋め込みを使用し、バックエンドでメンバートークンを発行します。

可能です。本ページの第2節と第3節で説明します。

カスタマイズ

できません。指示、モデル、ツール、スキルはプラットフォームで一元設定されます。組織側ではロール権限による制限のみ可能です。

可能です。画面で動作するのは独自に作成したAI Agentであり、指示、モデル、ツール、ナレッジベースを自由に設定できます。

結論：用途は2つに分かれます。自社の顧客や組織外のユーザー向けには、独自のAI Agentを作成して必要なツールを追加し、MaiGPTウィンドウモードで埋め込みます（第2節、第3節）。組織メンバー向けで、画像生成、Deep Research、コネクタ、ロール権限などMaiGPT製品自体の機能が必要な場合は、メンバーIDによる埋め込み（第5節）を使用し、バックエンドから短期トークンを発行します。

1. よくある症状

表示される現象

原因

解決方法

画面はMaiGPTに見えますが、応答は通常のChatと同じで、画像生成を依頼するとAIが「画像を生成できません」と返します。

埋め込まれているのは通常のAI Agentで、（1）回答モードがAgentモードではない、または（2）画像生成などのツールが追加されていません。

第2節に従ってAgentモードに切り替え、ツールを追加します。

チャットウィンドウが開かず、「会話の作成に失敗しました（HTTP 400）」と表示され、APIからMaiGPTを使用する権限がありません。が返されます。

埋め込んだWeb Chat IDが組織組み込みのMaiGPT製品に属していますが、訪問者にはメンバーIDがありません。

顧客向け → 独自アシスタントのWeb Chat IDを使用します（第3節）。メンバー向け → メンバーIDによる埋め込みに従ってメンバートークンを渡します。

管理画面のAI Agent一覧APIにMaiGPTが表示されません。

GET /api/v1/chatbots/には組織が独自に作成したアシスタントのみが表示され、MaiGPT製品は含まれません。

これは想定された動作です。連携では必ず独自アシスタントを対象にします。

組織組み込みMaiGPTのWeb Chatを埋め込むと、チャットウィンドウに会話作成失敗が表示されます

2. 画像を生成し、ツールを使用できるAI Agentを作成する

以下では「AI画像生成」を例にします。Web検索、Web取得、MCPツール、独自のAPIツールなど、その他の機能も同様に追加できます。

AI Agentを作成する

管理画面の「AI機能 → AIアシスタント」で新しいAI Agentを作成し、ロール指示とモデルを設定します。操作方法はユーザーマニュアルのAIアシスタントの作成をご覧ください。

回答モードを「Agentモード」に切り替える

アシスタントの「回答モード設定」を開き、回答モードをAgentモードに変更します。

ツールを呼び出せるのはAgentモードだけです。デフォルトの「RAG Q&A」モードは応答が速い一方、ツールを一切使用しません。画像生成ツールを追加したのに画像を生成しない場合の最も一般的な原因です。

ツールを追加する

アシスタントの「ツール」ページを開き、「ツールを選択」をクリックして、必要な組み込みツールを選択します。例：

画像生成：Global_Image_Tool_OpenAI_GPT_Image_2、Global_Image_Tool_Gemini_3など（いずれか1つを選択します。モデルの違いは組み込みAI画像生成ツールをご覧ください）
Web検索：Global_Tavily_Search_Tool
Web取得：Global_Web_Fetch_Tool
独自システムのAPIツールまたはMCPツール

詳しい操作方法は、ユーザーマニュアルのAIアシスタントへのツール設定をご覧ください。

Web Chat会話プラットフォームを作成する

「カスタマーサービス会話 → 会話プラットフォーム」で、このアシスタント用のWeb Chatを追加し、webChatIdを取得します。会話プラットフォーム連携：Webサイトをご覧ください。

APIで自動化する（ISVによる顧客環境の構築）

上記4つの手順には対応するAPIがあり、ソフトウェアベンダーは顧客ごとの開通時にプログラムで処理できます。認証方法とAPI Keyの取得方法はクイックスタートをご覧ください。

# 1. 組み込みツールを一覧表示し、画像生成ツールのidを取得します
GET /api/v1/tools/

# 2. AI Agentを作成します：回答モードをagentにし、ツールを追加します
POST /api/v1/chatbots/
{
  "name": "Acme GPT",
  "instructions": "あなたはAcme社のAIアシスタントです。日本語で回答してください。",
  "largeLanguageModel": "<LLM id>",
  "embeddingModel": "<embedding model id>",
  "rerankerModel": "<reranker model id>",
  "replyMode": "agent",
  "tools": ["<Global_Image_Tool_OpenAI_GPT_Image_2のid>"]
}

# 3. アシスタント用のWeb Chat会話プラットフォームを作成します（レスポンスのchannel.idがwebChatIdです）
POST /api/v1/inboxes/
{
  "name": "Acme GPT",
  "chatbot": "<chatbot id>",
  "channelType": "web",
  "channel": {
    "name": "Acme GPT",
    "theme": { "primaryColor": "#1890ff", "...": "..." },
    "darkTheme": { "primaryColor": "#404040", "...": "..." }
  }
}

既存アシスタントのモード変更やツール追加には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モードでの埋め込みに記載された埋め込みコードをページに配置します。

<div id="maigpt-container" style="height: 720px;"></div>
<script>
  window.maiagentChatbotConfig = {
    webChatId: '<第2節で作成したwebChatId>',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    enabledWindowModes: ['maigpt'],
    targetElement: '#maigpt-container',
    maigptTitle: 'Acme GPT',
  }
</script>
<script src="https://chat.maiagent.ai/js/embed.min.js" defer></script>

アシスタントがログインユーザーを識別し、その権限でAPIを呼び出せるようにするには、ソフトウェアベンダー連携ガイドに従ってcontactIdまたはauthを追加します。

検証：機能追加前後で同じ埋め込みコードを使用する

以下の2枚の画像は、同じAI Agentと同じ埋め込みコードを使用しています。違いは「回答モード＋ツール」の設定だけです。

MaiGPTウィンドウモードで、ツール未設定のアシスタントが画像を生成できないと回答します

MaiGPTウィンドウモードで、画像生成ツールを設定したアシスタントが画像を直接出力します

4. MaiGPT製品自体を使用すべき場合

要件が「自社製品に埋め込んで顧客に提供する」ことではなく、「従業員向けにChatGPTレベルの社内アシスタントを用意する」ことであれば、MaiGPT製品を直接使用するのが最も簡単です。

従業員は組織メンバーとしてログインすれば利用できます。入口にはWeb版、iOS App、LINE、Microsoft Teamsがあります。
画像生成、Deep Research、コネクタ、スキルは組み込み済みです。管理者はロール利用権限で各機能を利用できるユーザーを決めるだけです。
会社固有の知識を追加するには、該当するナレッジベースをメンバーに公開します。別のアシスタントを作成する必要はありません。

「自社システムに埋め込み、利用者が組織メンバーである」場合は、第5節のメンバーIDによる埋め込みを使用します。「組織外のユーザー（顧客、会員）向け」「独自のAPIツールが必要」「指示やモデルを変更したい」のいずれかに該当する場合は、第2節、第3節の独自アシスタント方式を使用します。

5. メンバーIDによる埋め込み：組織メンバー向けにMaiGPT製品を自社システムへ埋め込む

最初から最後までの手順は、MaiGPTを自社システムに追加するをご覧ください。本節では各パラメータを網羅的に説明します。

この方法は、自社システムのユーザーがMaiAgent組織のメンバーでもある場合（企業ポータル、従業員ワークスペース、ISVが管理する企業内システムなど）に適しています。別のアシスタントではなくMaiGPT製品自体を利用する場合、バックエンドが組織API Keyを使ってログイン中のメンバー用の短期トークンを発行し、フロントエンドはSDKの既存のメンバーID注入設定でMaiGPTのWeb Chatを埋め込みます。

前提条件

組織API Keyが必要です。所有者が組織オーナーであるか、「組織概要」の管理権限を持っている必要があります。メンバーを管理できるユーザーが発行したKeyだけが、メンバーの代理でトークンを発行できます。API Keyの取得方法はクイックスタートをご覧ください。
埋め込むユーザーが組織メンバーとして登録済みで、ロールにMaiGPT利用権限が付与されている必要があります（MaiGPTロール利用権限）。メンバーが存在しない場合、発行処理は404を返し、自動登録は行いません。SCIMプロビジョニングAPI、管理画面からの招待、SSOなどの登録方法はメンバーのプロビジョニングをご覧ください。ISV管理環境の標準的な方法は、SCIMでメンバーを登録し、本節の方法でトークンを発行することです。
MaiGPTのWeb Chat IDが必要です。GET /api/v1/web-chats/のレスポンスから、名前がMaiGPTでaccessTypeがwebの項目を使用します。

ステップ1：バックエンドでメンバートークンを発行する

ログイン済みユーザーだけが呼び出せるバックエンドエンドポイント（例：GET /maigpt-token）を作成します。内部でMaiAgentを呼び出し、フロントエンドSDKが必要なときにこのエンドポイントを呼び出します。

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はミリ秒単位のepochです）。

{
  "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の組織に所属していません。

トークンのルール：有効期間は15分に固定され、refresh tokenは発行されず、延長もできません。同じメンバーについて繰り返し発行でき、以前のトークンも期限までは有効です。このトークンはWeb Chatの会話にのみ使用できます（会話作成、メッセージ送信、引き継ぎ後の会話継続の3つの呼び出し）。/api/v1/の各エンドポイント、その他の会話管理操作、WebSocketに使用すると、常に401が返されます。発行のたびに監査用として組織のAPIリクエスト履歴に記録されます（レスポンス内のトークンは記録されません）。

ステップ2：SDKにトークン取得関数を渡す

埋め込み設定は第3節と同じですが、auth.getTokenを追加します。webChatIdはMaiGPTのWeb Chat IDに置き換えます。

<div id="maigpt-container" style="height: 720px;"></div>
<script>
  window.maiagentChatbotConfig = {
    webChatId: '<MaiGPTのWeb Chat ID>',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    enabledWindowModes: ['maigpt'],
    targetElement: '#maigpt-container',
    auth: {
      // SDK初期化時に1回呼び出し、その後tokenの期限が近づくたびに再度呼び出して自動更新します。タイマーは不要です
      getToken: async () => {
        const res = await fetch('/maigpt-token', { credentials: 'include' })  // 自社バックエンド。ステップ1を参照してください
        const { accessToken, organizationId, member } = await res.json()
        return { accessToken, organizationId, sourceId: member.userId }
      },
    },
  }
</script>
<script src="https://chat.maiagent.ai/js/embed.min.js" defer></script>

getTokenが返すオブジェクトのフィールド：

フィールド

必須

説明

accessToken

✅

ステップ1のレスポンスに含まれるaccessTokenです。

organizationId

✅

ステップ1のレスポンスに含まれるorganizationIdです。

sourceId

推奨

ステップ1のレスポンスに含まれるmember.userIdです。auth.sourceIdに設定することもでき、両方に指定した場合はauth.sourceIdが優先されます。

SDKが最初の会話を作成する前にメンバーIDの注入を待つよう、authはmaiagentChatbotConfig内に記述する必要があります。SDKの読み込み後にMaiAgent.auth.setup()を呼び出すと、ID注入前に最初の会話が匿名で作成され、拒否される可能性があります。

sourceIdには、レスポンスのmember.userIdを指定する必要があります。member.idや自社システムのユーザー番号ではありません。MaiGPTはこの値で会話をメンバーに関連付けます。誤った値を指定すると匿名の会話となり、そのメンバーのMaiGPT履歴に表示されません。

有効期限と更新の仕組み

トークンの有効期間は15分です。期限の60秒前にiframeがSDKへ通知し、SDKがgetTokenを再度呼び出して新しいトークンを取得・注入します。ページやiframeを再読み込みせず、同じ会話を継続して使用できるため、ユーザーには更新を意識させません。
getTokenを呼び出すたびにMaiAgentから新しいトークンを発行し、キャッシュした値を返さないでください。SDKはトークン自体の残り有効期間に基づいて次回の更新をスケジュールします。前回と同じトークンを返すと失敗と見なされ、以下の再試行処理に移ります。
ユーザーがログアウトした場合やバックエンドが401を返した場合など、getTokenが失敗すると、SDKは30秒後、60秒後、120秒後に各1回再試行します。すべて失敗すると停止し、consoleにエラーを記録します。トークン期限切れ後は、次のメッセージ送信が失敗し、既存のエラー通知が表示されます。会話と送信済みメッセージは消えません。
ユーザーが自社システムからログアウトするときはMaiAgent.auth.signOut()を呼び出します。SDKはIDを消去して更新を停止します。発行済みトークンは最長15分間有効な場合があります。別のユーザーがログインしたときはMaiAgent.auth.setup()を再度呼び出します。前のユーザーに対して進行中の更新は無効になります。
Web ChatでSource ID署名検証を有効にしている場合、署名は1回限りです。SDKは更新時に最初のts/sigを再利用しないため、getTokenからトークンとともに新しい署名を返してください（{ accessToken, ts, sig }）。
getTokenを使用せず、静的なauth.accessTokenを直接指定した場合、SDKは更新しません。15分後にMaiAgent.auth.setup()を再度呼び出す必要があります。

2つの方式の選び方

メンバーIDでMaiGPTを埋め込む（本節）

独自アシスタント＋MaiGPTウィンドウモード（第2節、第3節）

利用者

組織メンバーである必要があります

誰でも利用できます（顧客、会員、匿名ユーザー）

機能

ロール権限に応じたMaiGPTの全機能：画像生成、Deep Research、コネクタ、スキル

選択したツールとナレッジベース

指示／モデルのカスタマイズ

できません（プラットフォームで一元管理）

できます

バックエンド作業

トークン発行APIを中継するエンドポイント1つ

不要（任意で連絡先IDの同期を追加）

課金先

メンバーのクォータ

アシスタント／Web Chat

6. よくある質問

管理画面の「会話プラットフォーム」にMaiGPTというWeb Chatがあります。その埋め込みコードを使えますか？

そのままでは使用できません。これは組織組み込みのMaiGPT製品用の会話プラットフォームであり、組織メンバーだけを対象としています。外部ページに埋め込むと、訪問者にはメンバーIDがないため、会話作成が拒否されます（HTTP 400 MaiGPTを使用する権限がありません。）。利用者が組織メンバーであれば、メンバーIDによる埋め込みに従い、バックエンドでメンバートークンを発行してから埋め込みます。それ以外の場合は、独自のAI Agent用に別のWeb Chatを追加してください。

MaiGPT製品の画像生成、Deep Research、コネクタは、独自アシスタントでも利用できますか？

画像生成、Web検索、Web取得などの組み込みツールは、すべてのアシスタントで利用できます。アシスタントの「ツール」ページで選択してください。
コネクタ（Notion、Slack、Google Driveなど）は、アシスタント設定で独自アシスタントに連携できます。
Deep Researchとツールの切り替えは、MaiGPTウィンドウモードでエンドユーザーに提供できます。アシスタント所有者が管理画面で該当Web ChatのMaiGPTモードを有効にする必要があります。ユーザーマニュアルのMaiGPTウィンドウモードでの埋め込みをご覧ください。

アシスタントをAgentモードにして画像生成ツールも追加しましたが、画像を生成しません。何を確認すべきですか？

次の順序で確認してください。（1）埋め込みコードのwebChatIdが、このアシスタントに紐づくWeb Chatのものか（1つのアシスタントに複数の会話プラットフォームを設定できます）。（2）組織のプランとクォータが十分か（画像生成は画像ごとに課金され、クォータ不足時はメッセージを送信できません）。（3）ロール指示に「テキストのみで回答する」など、ツール利用を制限する記述がないか。ツール設定の変更は既存の会話にも反映されるため、新しい会話を開始する必要はありません。

MaiGPTウィンドウモードとfloating／sidebarモードの違いは何ですか？

異なるのはインターフェースのレイアウトだけです。基盤となるAI Agentと連絡先の仕組みは同じです。MaiGPTモードでの埋め込みをご覧ください。

前へ自社システムへの MaiGPT の追加

次へメンバーのメモリ管理 API

最終更新 14 日前

役に立ちましたか？