> 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.md). # MaiGPT を自社システムに組み込む MaiGPT を自社システムに組み込み、組織メンバーに提供するためのエンドツーエンドガイドです。メンバーの登録、トークンの発行、フロントエンドへの埋め込み、ログアウト、受け入れテストまで、このページだけで手順を確認できます このページでは、「自社システムに MaiGPT を追加したい」というエンジニア向けに、最初から最後までの手順を説明します。自社のポータルサイト、社内ワークスペース、顧客向けに運用する SaaS のいずれでも、利用者が **MaiAgent 組織のメンバー**（従業員や担当者）であれば手順は同じです。各ステップで必要な作業をここにまとめています。詳細が必要な場合はリンク先を参照してください。 {% hint style="info" %} 利用者が組織メンバーではなく、**自社の顧客、会員、匿名の訪問者**である場合、MaiGPT 製品自体は提供できません。[独自の AI Agent＋MaiGPT ウィンドウモード](/tech/ja/work/maigpt-system-integration-guide/maigpt-integration.md#build-agent)を利用してください。連絡先の本人情報との連携については、[ソフトウェアベンダー向け統合ガイド](/tech/ja/serve/vendor-integration-guide.md)を参照してください。 {% endhint %} ## 全体像 ```mermaid flowchart LR A["1 メンバーを登録
SCIM／招待／SSO"] --> B["2 バックエンドでメンバートークンを発行
組織 API Key"] B --> C["3 フロントエンドに埋め込み
auth.getToken"] C --> D["4 ログアウトと退職
signOut／無効化"] D --> E["5 受け入れテスト"] ``` 設定が完了すると、従業員が自社システムにログインした際に、ページ内に MaiGPT が表示されます。画像生成、Deep Research、コネクタを利用でき、権限、利用枠、会話履歴は MaiAgent のメンバー情報に紐づきます。MaiAgent に別途ログインする必要はなく、MaiAgent の存在を意識する必要もありません。 ## 事前準備 | 項目 | 入手先・設定方法 | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | MaiGPT と ID 同期を含むプランの MaiAgent 組織 | 不明な場合は営業担当にお問い合わせください | | 組織の所有者、または「組織概要」の管理権限を持つユーザーが保有する組織 API Key | 取得方法は[クイックスタート](/tech/ja/api-integration/quickstart.md)を参照してください | | MaiGPT の Web Chat ID | `GET /api/v1/web-chats/` のレスポンスで、名前が `MaiGPT`、`accessType` が `web` の項目です | | ロールの作成と権限設定 | 管理画面の「組織設定 → 組織概要 → ロール権限の編集」で、例えば「従業員」ロールを作成し、MaiGPT の利用権限を有効にしてください（[設定方法](https://docs.maiagent.ai/org/roles/maigpt-role-permissions)）。**メンバーの機能はすべてロールによって決まります**。この設定がないと、以降の作業を行っても利用できません | | メンバーの登録元を決定 | 次のセクションの 3 つの方法から選択してください | ## ステップ 1：メンバーを登録する 利用者は、まず MaiAgent 組織のメンバーになる必要があります。次の 3 つから、最も手軽な方法を選んでください。 {% hint style="info" %} 組織内ですでに MaiAgent を利用しているユーザーがいる場合も、SCIM 連携によって既存のアカウントが無効になったり、重複アカウントが作成されたりすることはありません。SCIM の管理対象になった既存メンバーは、以降、自社システムと同期されます。詳細は[既存のアカウントとメンバーへの影響](/tech/ja/identity-and-access/member-provisioning.md#scim-existing-accounts)を参照してください。 {% endhint %} {% tabs %} {% tab title="自社システムにユーザー管理機能がある場合（推奨）" %} 自社システムでユーザーを追加、変更、無効化するイベントから MaiAgent の SCIM エンドポイントを呼び出すと、メンバー情報をリアルタイムで一致させられます。 1. 管理画面の「組織設定 → ID 同期」で SCIM を選択し、「接続情報」タブから Endpoint URL と Token をコピーしてください（Token は一度しか表示されないため、サーバーの環境変数に保存してください） 2. [リアルタイム同期のページ](/tech/ja/identity-and-access/member-provisioning/member-event-sync.md)にある `MaiAgentMembers` クライアントをプロジェクトに追加し、イベント内で呼び出してください。 ```python 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) ``` 3. 初回の導入時に、既存ユーザー全員に対して `on_user_created` を一度実行してください（冪等です。[一括補完](/tech/ja/identity-and-access/member-provisioning/member-event-sync.md#backfill)を参照してください）。以降はイベントで同期を維持します。 {% endtab %} {% tab title="名簿のみがある場合（人事データのエクスポート、Excel、データベース）" %} [名簿同期ツール](/tech/ja/identity-and-access/member-provisioning/member-roster-sync.md)を利用してください。4 項目（社員番号、Email、氏名、ロール）の CSV または JSON を用意し、SCIM 接続用の環境変数を設定します。まず `--dry-run` で実行計画を確認してから本実行し、その後は毎日 1 回実行するようにスケジュールを設定してください。名簿にあるユーザーは作成または更新され、名簿から削除されたユーザーは無効化されます。 {% endtab %} {% tab title="Okta／Entra ID／JumpCloud がある場合" %} IdP のプロビジョニング設定に SCIM の Endpoint URL と Token を入力してください。IdP がユーザーとグループを自動的に送信します。詳細は[IdP からの送信](/tech/ja/identity-and-access/member-provisioning.md#scim-idp)を参照してください。 {% endtab %} {% endtabs %} 実際の連携で特につまずきやすい、次の 3 点を確認してください。 * **ロール名を管理画面で作成したロールと一致させてください**：SCIM でメンバーを作成する際の `groups` の名前は、管理画面で権限を設定済みのロール名です。一致しない場合、**権限のない**新しいロールが自動作成されます。 * **Email がアカウントのキーです**：`userName` は、後でトークンを発行する際に使用する Email です。作成後は SCIM で Email を変更できません。 * **SCIM で作成したアカウントにはパスワードがありません**：この方法では従業員は MaiAgent にログインしません。これは意図した動作です。MaiGPT の Web 版や App も利用可能にする場合は、別途 [SSO](/tech/ja/identity-and-access/member-provisioning.md#sso) を設定してください。 ## ステップ 2：バックエンドでメンバートークンを発行する バックエンドに、**ログイン済みのユーザー**だけが呼び出せるエンドポイント（例えば `GET /maigpt-token`）を作成してください。内部では組織 API Key を使用し、MaiAgent にそのメンバーの短期トークンを発行してもらいます。 ```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"}' ``` 成功すると `201` が返ります。 ```json { "accessToken": "<メンバーの短期 JWT>", "organizationId": "8d2f...-...", "expiresAt": 1789906401000, "member": { "id": "c1a4...", "userId": "5e77...", "email": "alice@acme.com", "name": "Alice" } } ``` レスポンス全体をそのままフロントエンドに返してください。ルールとステータスコードは次のとおりです。 | 仕様 | 説明 | | --------------------------------- | --------------------------------------------------------------------------------------------- | | 有効期間は 15 分、refresh token は発行されません | 更新はフロントエンド SDK が自動処理します（ステップ 3）。バックエンドは呼び出されるたびにトークンを発行するだけです。**毎回新しいトークンを発行し、キャッシュしないでください** | | トークンは MaiGPT の会話エンドポイントでのみ利用できます | このトークンで `/api/v1/` のどの API を呼び出しても `401` が返るため、漏えいしても組織データにアクセスできません | | `401`／`403` | Api-Key が使用されていない、または Key の保有者が所有者でも組織管理者でもありません | | `404` | この Email は、この組織の有効なメンバーではありません。ステップ 1 が未実施、またはすでに無効化されています | | トークンを発行するたびに監査ログが残ります | 組織の API リクエストログで確認できます。レスポンス内のトークンは記録されません | パラメータや詳細は[メンバートークンの発行](/tech/ja/work/maigpt-system-integration-guide/maigpt-integration.md#member-embed-issue)を参照してください。 ## ステップ 3：フロントエンドに埋め込む MaiGPT を配置するページに埋め込みコードを追加し、`auth.getToken` にステップ 2 のエンドポイントを指定してください。それ以外は SDK が処理します（初期化時のトークン取得、有効期限前の自動再取得、同じ会話の継続）。 ```html
``` {% hint style="danger" %} `sourceId` には必ずレスポンスの `member.userId` を設定してください。`member.id` や自社システムのユーザー ID ではありません。MaiGPT はこの値で会話をメンバーに紐づけます。誤った値を設定すると匿名の会話になり、そのメンバーの履歴を表示できません。 {% endhint %} コンテナの高さは自分で指定してください。SPA ではコンテナがマウントされてから SDK を読み込んでください。`baseUrl` と SDK の URL は SaaS のアドレスです。プライベートデプロイの場合は自社のドメインに置き換えてください。レイアウトやその他のパラメータは [MaiGPT モードの埋め込み](/tech/ja/serve/web-chat-sdk/web-chat-maigpt-mode.md)を参照してください。 ## ステップ 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 利用枠管理](https://docs.maiagent.ai/others/credits/member-credit-quota)を参照してください。 * **監査**：トークン発行は毎回、組織の 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 エラーコードは[名簿同期ツールのエラー一覧](/tech/ja/identity-and-access/member-provisioning/member-roster-sync.md#errors)を参照してください。 ## 関連資料 * [メンバーの登録：SCIM／招待／SSO](/tech/ja/identity-and-access/member-provisioning.md) — SCIM API の完全なリファレンスと 3 つの方法の比較です * [リアルタイム同期：ユーザーイベントから呼び出す](/tech/ja/identity-and-access/member-provisioning/member-event-sync.md)／[名簿同期ツール](/tech/ja/identity-and-access/member-provisioning/member-roster-sync.md) * [MaiGPT との連携：適切な Agent の選択と機能の整備](/tech/ja/work/maigpt-system-integration-guide/maigpt-integration.md) — MaiGPT 製品と独自 Agent の違い、メンバーの本人情報を使用する埋め込みの全パラメータを説明します * [Web Chat の埋め込みと SDK](/tech/ja/serve/web-chat-sdk.md)／[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.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.