MaiGPT をシステムに追加します

MaiGPT を自社システムに組み込み、組織メンバーに提供するためのエンドツーエンドガイドです。メンバーの登録、トークンの発行、フロントエンドへの埋め込み、ログアウト、受け入れテストまで、このページだけで手順を確認できます

このページでは、「自社システムに MaiGPT を追加したい」というエンジニア向けに、最初から最後までの手順を説明します。自社のポータルサイト、社内ワークスペース、顧客向けに運用する SaaS のいずれでも、利用者が MaiAgent 組織のメンバー（従業員や担当者）であれば手順は同じです。各ステップで必要な作業をここにまとめています。詳細が必要な場合はリンク先を参照してください。

利用者が組織メンバーではなく、自社の顧客、会員、匿名の訪問者である場合、MaiGPT 製品自体は提供できません。独自の AI Agent＋MaiGPT ウィンドウモードを利用してください。連絡先の本人情報との連携については、ソフトウェアベンダー向け統合ガイドを参照してください。

全体像

設定が完了すると、従業員が自社システムにログインした際に、ページ内に MaiGPT が表示されます。画像生成、Deep Research、コネクタを利用でき、権限、利用枠、会話履歴は MaiAgent のメンバー情報に紐づきます。MaiAgent に別途ログインする必要はなく、MaiAgent の存在を意識する必要もありません。

事前準備

項目	入手先・設定方法
MaiGPT と ID 同期を含むプランの MaiAgent 組織	不明な場合は営業担当にお問い合わせください
組織の所有者、または「組織概要」の管理権限を持つユーザーが保有する組織 API Key	取得方法はクイックスタートを参照してください
MaiGPT の Web Chat ID	GET /api/v1/web-chats/ のレスポンスで、名前が MaiGPT、accessType が web の項目です
ロールの作成と権限設定	管理画面の「組織設定 → 組織概要 → ロール権限の編集」で、例えば「従業員」ロールを作成し、MaiGPT の利用権限を有効にしてください（設定方法）。メンバーの機能はすべてロールによって決まります。この設定がないと、以降の作業を行っても利用できません
メンバーの登録元を決定	次のセクションの 3 つの方法から選択してください

ステップ 1：メンバーを登録する

利用者は、まず MaiAgent 組織のメンバーになる必要があります。次の 3 つから、最も手軽な方法を選んでください。

組織内ですでに MaiAgent を利用しているユーザーがいる場合も、SCIM 連携によって既存のアカウントが無効になったり、重複アカウントが作成されたりすることはありません。SCIM の管理対象になった既存メンバーは、以降、自社システムと同期されます。詳細は既存のアカウントとメンバーへの影響を参照してください。

自社システムにユーザー管理機能がある場合（推奨）

自社システムでユーザーを追加、変更、無効化するイベントから MaiAgent の SCIM エンドポイントを呼び出すと、メンバー情報をリアルタイムで一致させられます。

1. 管理画面の「組織設定 → ID 同期」で SCIM を選択し、「接続情報」タブから Endpoint URL と Token をコピーしてください（Token は一度しか表示されないため、サーバーの環境変数に保存してください）

2. リアルタイム同期のページにある MaiAgentMembers クライアントをプロジェクトに追加し、イベント内で呼び出してください。

members = MaiAgentMembers()   # 環境変数 MAIAGENT_SCIM_URL / MAIAGENT_SCIM_TOKEN を読み込みます

# ユーザーを追加します
user.maiagent_member_id = members.on_user_created(
    external_id=user.id, email=user.email, name=user.display_name, groups=["従業員"],
)
# 名前や部署を変更します
members.on_user_updated(user.maiagent_member_id, user.id, user.email, user.display_name, ["従業員"])
# 利用停止や退職に対応します
members.on_user_deactivated(user.maiagent_member_id)

1. 初回の導入時に、既存ユーザー全員に対して on_user_created を一度実行してください（冪等です。一括補完を参照してください）。以降はイベントで同期を維持します。

名簿のみがある場合（人事データのエクスポート、Excel、データベース）

名簿同期ツールを利用してください。4 項目（社員番号、Email、氏名、ロール）の CSV または JSON を用意し、SCIM 接続用の環境変数を設定します。まず --dry-run で実行計画を確認してから本実行し、その後は毎日 1 回実行するようにスケジュールを設定してください。名簿にあるユーザーは作成または更新され、名簿から削除されたユーザーは無効化されます。

Okta／Entra ID／JumpCloud がある場合

IdP のプロビジョニング設定に SCIM の Endpoint URL と Token を入力してください。IdP がユーザーとグループを自動的に送信します。詳細はIdP からの送信を参照してください。

実際の連携で特につまずきやすい、次の 3 点を確認してください。

• ロール名を管理画面で作成したロールと一致させてください：SCIM でメンバーを作成する際の groups の名前は、管理画面で権限を設定済みのロール名です。一致しない場合、権限のない新しいロールが自動作成されます。

• Email がアカウントのキーです：userName は、後でトークンを発行する際に使用する Email です。作成後は SCIM で Email を変更できません。

• SCIM で作成したアカウントにはパスワードがありません：この方法では従業員は MaiAgent にログインしません。これは意図した動作です。MaiGPT の Web 版や App も利用可能にする場合は、別途 SSO を設定してください。

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

バックエンドに、ログイン済みのユーザーだけが呼び出せるエンドポイント（例えば GET /maigpt-token）を作成してください。内部では組織 API Key を使用し、MaiAgent にそのメンバーの短期トークンを発行してもらいます。

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": "[e-mail]"}'

成功すると 201 が返ります。

{
  "accessToken": "<メンバーの短期 JWT>",
  "organizationId": "8d2f...-...",
  "expiresAt": 1789906401000,
  "member": { "id": "c1a4...", "userId": "5e77...", "email": "[e-mail]", "name": "Alice" }
}

レスポンス全体をそのままフロントエンドに返してください。ルールとステータスコードは次のとおりです。

仕様	説明
有効期間は 15 分、refresh token は発行されません	更新はフロントエンド SDK が自動処理します（ステップ 3）。バックエンドは呼び出されるたびにトークンを発行するだけです。毎回新しいトークンを発行し、キャッシュしないでください
トークンは MaiGPT の会話エンドポイントでのみ利用できます	このトークンで /api/v1/ のどの API を呼び出しても 401 が返るため、漏えいしても組織データにアクセスできません
401／403	Api-Key が使用されていない、または Key の保有者が所有者でも組織管理者でもありません
404	この Email は、この組織の有効なメンバーではありません。ステップ 1 が未実施、またはすでに無効化されています
トークンを発行するたびに監査ログが残ります	組織の API リクエストログで確認できます。レスポンス内のトークンは記録されません

パラメータや詳細はメンバートークンの発行を参照してください。

ステップ 3：フロントエンドに埋め込む

MaiGPT を配置するページに埋め込みコードを追加し、auth.getToken にステップ 2 のエンドポイントを指定してください。それ以外は SDK が処理します（初期化時のトークン取得、有効期限前の自動再取得、同じ会話の継続）。

<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',
    maigptTitle: 'Acme GPT',            // 任意：左上に表示するブランド名
    locale: 'zh-TW',                    // 任意：インターフェースの言語
    auth: {
      getToken: async () => {
        const res = await fetch('/maigpt-token', { credentials: 'include' })
        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>

sourceId には必ずレスポンスの member.userId を設定してください。member.id や自社システムのユーザー ID ではありません。MaiGPT はこの値で会話をメンバーに紐づけます。誤った値を設定すると匿名の会話になり、そのメンバーの履歴を表示できません。

コンテナの高さは自分で指定してください。SPA ではコンテナがマウントされてから SDK を読み込んでください。baseUrl と SDK の URL は SaaS のアドレスです。プライベートデプロイの場合は自社のドメインに置き換えてください。レイアウトやその他のパラメータは MaiGPT モードの埋め込みを参照してください。

ステップ 4：ログアウトと退職に対応する

イベント	必要な対応	結果
ユーザーが自社システムからログアウト	フロントエンドで MaiAgent.auth.signOut() を呼び出してください	iframe が本人情報を消去し、更新を停止します。発行済みトークンは最大でさらに 15 分間有効です
ユーザーの退職／利用停止	ステップ 1 の無効化を実行してください（on_user_deactivated、名簿からの削除、IdP での無効化）	以降のトークン発行は 404 を返し、埋め込みページは利用できなくなります。会話と利用枠の記録は保持されます
復職	ステップ 1 の再有効化を実行してください	ロールと履歴が復元されます

ステップ 5：受け入れテスト

次の項目を順番に確認してください。それぞれに明確な判定基準があります。

1. メンバーが存在し、ロールが割り当てられています：管理画面の「メンバー管理」に対象者が表示され、権限設定済みのロールが割り当てられていることを確認してください。

2. トークン発行に成功します：ステップ 2 の curl が 201 を返し、存在しない Email を指定すると 404 を返すことを確認してください。

3. 会話できます：埋め込みページで MaiGPT を開き、メッセージを送って返信を受け取ってください。そのメンバーとして MaiGPT の Web 版にログインした場合（SSO がある場合）、または管理画面の会話記録で、この会話を確認できることを確認してください。

4. 機能が正しく利用できます：画像生成を依頼してください。ロールでコネクタと Deep Research が有効になっている場合は、それらの入口が表示されます。

5. 更新を意識せずに利用できます：ページを 15 分以上開いたままにしてからメッセージを送ってください。ページを再読み込みせずに、同じ会話を継続できることを確認してください。

6. ログアウトが有効になります：signOut() 後のメッセージ送信が拒否され、メンバーを無効化するとステップ 2 が 404 を返すことを確認してください。

導入後

• SCIM Token と API Key のローテーション：SCIM Token の作成から 180 日を超えると管理画面に通知されます。再生成すると古いトークンは即座に無効になるため、サーバーの環境変数も更新してください。

• プランの容量：メンバー数は組み込み Agent の席数と各メンバーの Credits 利用枠に影響します。メンバーの Credits 利用枠管理を参照してください。

• 監査：トークン発行は毎回、組織の API リクエストログに記録されます。SCIM の同期は毎回、管理画面の「ID 同期 → 同期ログ」に記録されます。

トラブルシューティング

現象	原因	対処方法
トークン発行で 404 が返ります	Email がこの組織の有効なメンバーではありません	ステップ 1 に戻り、メンバーが存在すること、無効化されていないこと、Email が一致すること（大文字・小文字は区別しません）を確認してください
トークン発行で 403 が返ります	API Key の保有者が所有者ではなく、組織の管理権限もありません	管理者が発行した Key を使用してください
チャットウィンドウに「会話の作成に失敗しました（400）MaiGPT を利用する権限がありません」と表示されます	メンバーのロールに MaiGPT の利用権限がない、または auth が渡されていません	管理画面のロール権限で MaiGPT を有効にし、getToken が accessToken と organizationId を返すことを確認してください
会話が匿名になり、履歴が表示されません	sourceId が誤っています	member.userId を使用してください
15 分後にメッセージ送信が失敗します	getToken が呼び出されていないか、失敗しています（ブラウザの console の [MaiAgent] エラーを確認してください）	ログイン済みのユーザーがエンドポイントを利用でき、レスポンス形式が正しいことを確認してください
メンバーは作成されたのに何も利用できません	ロールが割り当てられていない、またはロールの権限が空です	管理画面でロール権限を設定し、SCIM で同じ名前を指定して割り当ててください
Email の変更が反映されません	SCIM では Email を変更できません	管理画面で変更するか、古いアカウントを無効化して新しい Email で作成してください

その他の SCIM エラーコードは名簿同期ツールのエラー一覧を参照してください。

関連資料

• メンバーの登録：SCIM／招待／SSO — SCIM API の完全なリファレンスと 3 つの方法の比較です

• リアルタイム同期：ユーザーイベントから呼び出す／名簿同期ツール

• MaiGPT との連携：適切な Agent の選択と機能の整備 — MaiGPT 製品と独自 Agent の違い、メンバーの本人情報を使用する埋め込みの全パラメータを説明します

• Web Chat の埋め込みと SDK／MaiGPT モードの埋め込み