> 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/work/maigpt-system-integration-guide/maigpt-integration.md).

# 串接 MaiGPT：選對 Agent、補齊能力

把 MaiGPT 串進自家系統：釐清 MaiGPT 產品與 MaiGPT 視窗模式的差別、給客戶用就自建 Agent 補齊生圖等工具、給組織成員用就以成員身分嵌入 MaiGPT 產品

「MaiGPT」在 MaiAgent 平台上指兩件不同的東西，串接前先分清楚，可以省掉大部分的來回：

|           | **MaiGPT 產品**（組織內建 Agent）                                                                                                                  | **MaiGPT 視窗模式**（Web Chat SDK 的一種佈局）                                        |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| 是什麼       | 每個組織自動配備一個、由 MaiAgent 統一維護的企業 AI 工作台，內建 AI 生圖、Deep Research、連接器等能力，見[什麼是 MaiGPT？](https://docs.maiagent.ai/work/maigpt)                    | `enabledWindowModes: ['maigpt']` 開啟的**類 ChatGPT 完整介面**（側欄對話歷史、搜尋、設定），純前端呈現 |
| 誰能用       | 組織**成員**登入後使用（網頁、iOS App、LINE、Microsoft Teams），權限由[角色使用權限](https://docs.maiagent.ai/org/roles/maigpt-role-permissions)控制                   | 任何 Web Chat 都能套用，含匿名訪客與[聯絡人身分](/tech/serve/web-chat-sdk.md#identify-users) |
| 能不能嵌進您的系統 | **只能給組織成員用**：建立對話時要求成員身分且具備 `maigpt_access` 權限，直接用其 Web Chat ID 嵌入會得到 `400 您沒有權限使用 MaiGPT。`；要嵌給成員用，走[成員身分嵌入](#member-embed)由您的後端換發成員 token | **能**：本頁第二、三節講的就是這件事                                                       |
| 能不能客製化    | **不能**：指令、模型、工具、技能皆由平台統一設定，組織端只能透過角色權限**收窄**                                                                                               | **能**：介面下面掛的是您自己建立的 AI Agent，指令、模型、工具、知識庫全由您決定                             |

**結論**：分兩種需求。給**自家客戶、非組織成員**用，做法是**自己建立一個 AI Agent，補上需要的工具，再用 MaiGPT 視窗模式嵌入**（第二、三節）。給**組織成員**用、而且就是要 MaiGPT 產品本身的能力（生圖、Deep Research、連接器、角色權限），走[成員身分嵌入](#member-embed)（第五節），由您的後端替成員換發短效 token。

## 一、常見症狀對照 <a href="#symptoms" id="symptoms"></a>

| 您看到的現象                                               | 原因                                                      | 解法                                                                                       |
| ---------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| 介面長得像 MaiGPT，但問答像一般 Chat，要求生圖時 AI 回「我無法生成圖片」         | 嵌入的是一般 AI Agent，且（1）回答模式不是 **Agent 模式**，或（2）沒有掛上圖片生成等工具 | 依[第二節](#build-agent)切換 Agent 模式並加上工具                                                     |
| 聊天視窗打不開，顯示「建立對話失敗（HTTP 400）」，API 回 `您沒有權限使用 MaiGPT。` | 嵌入的 Web Chat ID 屬於組織內建的 MaiGPT 產品，而訪客沒有成員身分             | 給客戶用 → 改用自建 Agent 的 Web Chat ID（[第三節](#embed)）；給成員用 → 依[成員身分嵌入](#member-embed)帶入成員 token |
| 後台的 AI Agent 列表 API 找不到 MaiGPT                       | `GET /api/v1/chatbots/` 只列出組織自建的 Agent，MaiGPT 產品不在其中    | 這是預期行為；串接一律以自建 Agent 為對象                                                                 |

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-395666ae30129d6b54c4deede6fbfda478f4f635%2Fwebchat-maigpt-builtin-permission-error.png?alt=media" alt="嵌入組織內建 MaiGPT 的 Web Chat 時，聊天視窗顯示建立對話失敗"><figcaption><p>嵌入組織內建 MaiGPT 的 Web Chat：訪客不是登入成員，建立對話被拒（HTTP 400）</p></figcaption></figure>

## 二、建立能生圖、能用工具的 AI Agent <a href="#build-agent" id="build-agent"></a>

以下用「AI 生圖」為例，其他能力（網頁搜尋、網頁讀取、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` 等（勾一個即可；模型差異見[內建 AI 圖像生成工具](https://docs.maiagent.ai/build/tools/ai-image-generation-guide)）
* **網頁搜尋**：`Global_Tavily_Search_Tool`
* **網頁讀取**：`Global_Web_Fetch_Tool`
* 您自家系統的 [API 工具](/tech/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`。操作見[串接對話平台：網站](https://docs.maiagent.ai/build/choose-channel/web-chat/website)。
{% endstep %}
{% endstepper %}

### 用 API 自動化（ISV 代客建置時） <a href="#build-agent-api" id="build-agent-api"></a>

以上四步都有對應 API，適合軟體廠商在為每個客戶開通時以程式完成。認證方式與 API Key 取得見[快速上手](/tech/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": "<LLM id>",
  "embeddingModel": "<embedding model id>",
  "rerankerModel": "<reranker model id>",
  "replyMode": "agent",
  "tools": ["<Global_Image_Tool_OpenAI_GPT_Image_2 的 id>"]
}

# 3. 為 Agent 建立 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", "...": "..." }
  }
}
```

* 既有 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

## 三、用 MaiGPT 視窗模式嵌入 <a href="#embed" id="embed"></a>

拿第二節的 `webChatId`，照 [MaiGPT 模式嵌入](/tech/serve/web-chat-sdk/web-chat-maigpt-mode.md)的嵌入碼放進您的頁面：

```html
<div id="maigpt-container" style="height: 720px;"></div>
<script>
  window.maiagentChatbotConfig = {
    webChatId: '<第二節建立的 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>
```

要讓 Agent 認得登入使用者、以其權限呼叫您的 API，再依[軟體廠商整合指南](/tech/serve/vendor-integration-guide.md)加上 `contactId` 或 `auth`。

### 驗證：同一段嵌入碼，補齊能力前後 <a href="#verify" id="verify"></a>

下面兩張圖是同一個 AI Agent、同一段嵌入碼，只差「回答模式＋工具」的設定：

{% tabs %}
{% tab title="補齊前：RAG 問答模式、沒有工具" %}

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-fff3ac5078e623be9f11f236a6bfc84da898cffd%2Fwebchat-maigpt-agent-before-tools.png?alt=media" alt="MaiGPT 視窗模式下，未掛工具的 Agent 回覆無法生成圖片"><figcaption><p>介面是 MaiGPT 視窗模式，但 Agent 回「我無法生成、創建或製作圖片」</p></figcaption></figure>
{% endtab %}

{% tab title="補齊後：Agent 模式＋圖片生成工具" %}

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-bb169ef18215ee1c7aea31a29a3004458d46802f%2Fwebchat-maigpt-agent-with-image-tool.png?alt=media" alt="MaiGPT 視窗模式下，掛上圖片生成工具的 Agent 直接產出圖片"><figcaption><p>同一段嵌入碼，Agent 呼叫圖片生成工具並在對話中直接出圖</p></figcaption></figure>
{% endtab %}
{% endtabs %}

## 四、什麼時候該用 MaiGPT 產品本身 <a href="#when-to-use-maigpt-product" id="when-to-use-maigpt-product"></a>

如果需求是「讓我們公司的員工有一個 ChatGPT 等級的內部 Agent」，而不是「嵌進自家產品給自家客戶用」，直接用 MaiGPT 產品最省事：

* 員工以組織成員身分登入平台即可使用，入口有[網頁版](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

「嵌到自家系統但使用者是組織成員」→ 走第五節的成員身分嵌入。只要出現「給非成員（客戶、會員）用」「要加自家 API 工具」「要改指令或模型」其中任何一項，就走第二、三節的自建 Agent 路線。

## 五、成員身分嵌入：把 MaiGPT 產品嵌進自家系統給組織成員 <a href="#member-embed" id="member-embed"></a>

{% hint style="info" %}
想從頭到尾照著做，請看[把 MaiGPT 加進您的系統](/tech/work/maigpt-system-integration-guide.md)；本節是各參數的完整參考。
{% endhint %}

適用情境：您的系統使用者**同時是 MaiAgent 組織的成員**（例如企業入口網站、員工工作台、ISV 代管的企業內部系統），而且要的就是 MaiGPT 產品本身，不想另建 Agent。做法是由**您的後端**以組織 API Key 替登入中的成員換一顆短效 token，前端用 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: token 快到期時 iframe 通知 SDK，SDK 再呼叫 getToken 自動續期
```

### 前置條件 <a href="#member-embed-prerequisites" id="member-embed-prerequisites"></a>

* 一把**組織 API Key**，且持有者是組織擁有者或角色具「組織總覽」管理權限——只有能管理成員的人發的 Key 才能代表成員換發。API Key 取得見[快速上手](/tech/api-integration/quickstart.md)
* 要嵌入的使用者已是該組織成員，且角色具 MaiGPT 使用權限（[MaiGPT 角色使用權限](https://docs.maiagent.ai/org/roles/maigpt-role-permissions)）；成員不存在時換發會回 404，不會自動開通。人員怎麼變成成員（SCIM 開通 API、後台邀請、SSO）見[成員開通](/tech/identity-and-access/member-provisioning.md)，ISV 代管的標準接法是 SCIM 建成員＋本節換發 token
* MaiGPT 的 Web Chat ID：`GET /api/v1/web-chats/` 回傳中名稱為 `MaiGPT`、`accessType` 為 `web` 的那一筆

### 步驟一：後端換發成員 token <a href="#member-embed-issue" id="member-embed-issue"></a>

在您的後端開一支只給登入使用者呼叫的端點（例如 `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` 為 epoch 毫秒）：

```json
{
  "accessToken": "<成員短效 JWT>",
  "organizationId": "8d2f...-...",
  "expiresAt": 1789906401000,
  "member": {
    "id": "c1a4...-...",
    "userId": "5e77...-...",
    "email": "alice@acme.com",
    "name": "Alice"
  }
}
```

| 狀態碼   | 意思                                |
| ----- | --------------------------------- |
| `400` | `email` 與 `memberId` 兩個都給或都沒給     |
| `401` | 沒有以 Api-Key 認證（成員登入 token、匿名都會被拒） |
| `403` | API Key 持有者不是組織擁有者、也沒有組織管理權限      |
| `404` | 指定的成員不存在、已停用、或不屬於這把 Key 的組織       |

{% hint style="warning" %}
**token 規則**：效期固定 **15 分鐘**、不發 refresh token、不可延長；同一成員可重複換發，舊 token 到期前仍有效。這顆 token **只能用於 Web Chat 對話**（建立對話、送訊息、交接續談三個呼叫），拿去呼叫 `/api/v1/` 任何端點、其他對話管理動作或 WebSocket 一律 `401`。每次換發都會留在組織的 API 請求紀錄中供稽核（回應中的 token 不會被記錄）。
{% endhint %}

### 步驟二：前端給 SDK 一個取 token 的函式 <a href="#member-embed-frontend" id="member-embed-frontend"></a>

嵌入設定與[第三節](#embed)相同，多一個 `auth.getToken`；`webChatId` 換成 MaiGPT 的 Web Chat ID：

```html
<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 初始化時呼叫一次；之後每當 token 快到期會再呼叫一次並自動續期，您不需要計時
      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>
```

`getToken` 回傳的物件欄位：

| 欄位               | 必填 | 說明                                                                      |
| ---------------- | -- | ----------------------------------------------------------------------- |
| `accessToken`    | ✅  | 步驟一回應的 `accessToken`                                                    |
| `organizationId` | ✅  | 步驟一回應的 `organizationId`                                                 |
| `sourceId`       | 建議 | 步驟一回應的 `member.userId`；也可以改寫在 `auth.sourceId`，兩處都給時以 `auth.sourceId` 為準 |

`auth` 必須寫在 `maiagentChatbotConfig` 裡，SDK 建立聊天視窗時才知道要先等成員身分注入完成再建立第一則對話；改在 SDK 載入後才呼叫 `MaiAgent.auth.setup()` 的話，第一則對話可能在身分注入前就以匿名建立而被拒。

{% hint style="danger" %}
`sourceId` 必須是回應中的 `member.userId`，不是 `member.id`、也不是您系統的使用者編號。MaiGPT 以它把對話對應到成員；填錯會變成匿名對話、看不到該成員的 MaiGPT 歷史。
{% endhint %}

### 到期與續期怎麼運作 <a href="#member-embed-refresh" id="member-embed-refresh"></a>

* token 效期 15 分鐘。iframe 會在到期前 60 秒通知 SDK，SDK 再呼叫一次 `getToken` 取新 token 並重新注入，**同一則對話直接續用，不重載頁面或 iframe**，使用者無感。
* **`getToken` 每次都必須向 MaiAgent 換發新 token，不可回傳快取值**：SDK 依 token 自身的存活時間排程下一次續期；回傳與上一顆相同的 token 會被視為失敗，走下一條的重試流程。
* `getToken` 失敗（例如您的使用者已登出、後端回 401）時 SDK 會在 30 秒、60 秒、120 秒後各重試一次，仍失敗就停止並在 console 記錄錯誤；token 到期後下一則訊息會送出失敗並顯示既有的錯誤提示，對話與已送出的訊息不會消失。
* 使用者登出您的系統時呼叫 `MaiAgent.auth.signOut()`，SDK 會清掉身分並停止續期；已發出的 token 最多再存活 15 分鐘。換另一位使用者登入時直接再呼叫一次 `MaiAgent.auth.setup()` 即可，前一位使用者進行中的續期會被作廢。
* 該 Web Chat 若開啟了 [Source ID 簽章驗證](/tech/serve/web-chat-sdk.md#source-id-signature)：簽章是一次性的，SDK 續期時不會重用第一次的 `ts`／`sig`，請讓 `getToken` 的回傳值連新簽章一起帶回（`{ accessToken, ts, sig }`）。
* 若您不用 `getToken`、改直接給靜態的 `auth.accessToken`，SDK 不會續期，15 分鐘後要自己重新呼叫 `MaiAgent.auth.setup()`。

### 這條路與自建 Agent 怎麼選 <a href="#member-embed-vs-agent" id="member-embed-vs-agent"></a>

|         | 成員身分嵌入 MaiGPT（本節）                       | 自建 Agent＋MaiGPT 視窗模式（第二、三節） |
| ------- | --------------------------------------- | --------------------------- |
| 使用者     | 必須是組織成員                                 | 任何人（客戶、會員、匿名）               |
| 能力      | MaiGPT 全套：生圖、Deep Research、連接器、技能，依角色權限 | 您勾選的工具與知識庫                  |
| 客製指令／模型 | 不能（平台統一）                                | 能                           |
| 後端工作    | 一支轉呼叫換發 API 的端點                         | 零（可選加聯絡人身分同步）               |
| 計費歸屬    | 該成員的額度                                  | 該 Agent／Web Chat            |

## 六、常見問題 <a href="#faq" id="faq"></a>

<details>

<summary>我在後台「對話平台」看到一個叫 MaiGPT 的 Web Chat，可以拿它的嵌入碼嗎？</summary>

直接拿嵌入碼不行：那是組織內建 MaiGPT 產品的對話平台，只服務組織成員；嵌到外部頁面時訪客沒有成員身分，建立對話會被拒（HTTP 400 `您沒有權限使用 MaiGPT。`）。如果使用者本來就是組織成員，依[成員身分嵌入](#member-embed)由您的後端換發成員 token 再嵌入；否則請為自建的 AI Agent 另外新增 Web Chat。

</details>

<details>

<summary>MaiGPT 產品裡的生圖、Deep Research、連接器，自建 Agent 都能有嗎？</summary>

* **生圖、網頁搜尋、網頁讀取**等內建工具對所有 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)

</details>

<details>

<summary>回覆模式已經是 Agent、也掛了生圖工具，還是不生圖？</summary>

依序檢查：(1) 嵌入碼的 `webChatId` 是不是掛在這個 Agent 底下的 Web Chat（一個 Agent 可以有多個對話平台）；(2) 組織方案與額度是否足夠（生圖依張數扣款，額度不足時訊息會直接送不出去）；(3) 角色指令有沒有寫「只回答文字」之類限制工具使用的句子。工具設定的變更對既有對話也會生效，不需要另開新對話。

</details>

<details>

<summary>MaiGPT 視窗模式跟 floating／sidebar 差在哪？</summary>

只差介面佈局，底層都是同一個 AI Agent 與同一套聯絡人機制。詳見 [MaiGPT 模式嵌入](/tech/serve/web-chat-sdk/web-chat-maigpt-mode.md)。

</details>


---

# 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/work/maigpt-system-integration-guide/maigpt-integration.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.