> 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/build/integrate/google-workspace-connector.md).

# Google Workspace 連接器

用平台內建的 Google Workspace 連接器（MCP），讓 Agent 查詢 Gmail 信件、Google 日曆行程與雲端硬碟文件

## 應用情境：會查信、查行程、找文件的工作 Agent <a href="#use-case" id="use-case"></a>

許多日常工作其實是「找東西」：客戶上週寄來的報價單附件在哪、下午的會議是幾點、共用雲端硬碟裡那份 SOP 的最新版本是哪一份。這些資料分散在 Gmail、Google 日曆與 Google 雲端硬碟，員工需要在多個分頁之間切換搜尋。

透過 MaiAgent 內建的 **Google Workspace 連接器**，Agent 可以用授權過的 Google 帳號存取這些服務，一句話完成查詢與整理，例如：

* 「幫我找上週供應商寄來、附件有報價單的信，把金額整理成表格」
* 「我明天下午有哪些會議？有沒有和客戶的視訊？」
* 「雲端硬碟裡有沒有新人教育訓練的簡報？給我連結」

{% hint style="info" %}
**這頁在講什麼**

本頁示範把 Google Workspace 連接器以 <mark style="color:blue;">MCP</mark> 工具掛到自建的 Agent 上。工具欄位與 OAuth 授權流程的完整說明見 [建立 MCP 工具](/build/tools/mcp-setup.md#oauth-connector)；成員在 MaiGPT 自己連接見 [連接器](/work/maigpt/connectors.md)；官方內建 Agent 的連接器見 [啟用與管理 › 連接器](/work/built-in-agents/management.md#connectors)。
{% endhint %}

## 運作方式 <a href="#how-it-works" id="how-it-works"></a>

Google Workspace 連接器是 MaiAgent 維護的 Remote MCP 伺服器，已登錄在平台的連接器清單中（來源標示為「系統內建」），不需要自行架設或填寫伺服器網址。它採用 OAuth 2.0 授權：

1. 點擊授權後，跳轉到 Google 的登入與同意畫面
2. 選擇 Google 帳號，確認畫面列出的權限後同意
3. 回到 MaiAgent，憑證由後端加密保存，不會存在瀏覽器
4. Agent 之後以這個 Google 帳號的身分呼叫 Gmail、日曆、雲端硬碟等服務

### 可授權的服務與存取層級 <a href="#scopes" id="scopes"></a>

成員在 MaiGPT 授權 Google Workspace 連接器時，會先出現「<mark style="color:blue;">選擇授權範圍</mark>」視窗，可依「最小必要」原則調整各服務的存取層級：

| 服務                              | 可選的存取層級（預設值）                  |
| ------------------------------- | ----------------------------- |
| Google Drive                    | 唯讀／僅限本應用程式建立的檔案／完整存取（預設：完整存取） |
| Gmail                           | 僅傳送／傳送與管理（預設：傳送與管理）           |
| Google Calendar                 | 唯讀／完整存取（預設：完整存取）              |
| Google Sheets、Docs、Slides、Forms | 各自開啟或關閉（預設皆開啟）                |

Gmail 選「僅傳送」時只能寄信，無法搜尋或讀取信件；要讓 Agent 查信，請保留「傳送與管理」。

以工具方式授權（下方的「組織共用」或「聯絡人個別授權」）時，請在 Google 的同意畫面確認這次要授予的權限。

{% hint style="warning" %}
**實際能做的事以取得的工具清單為準**

Agent 能執行哪些動作，取決於授權完成後平台從 MCP 伺服器取得的工具清單（例如搜尋信件、讀取附件內容、取得下載連結）。不同的授權範圍會拿到不同的工具；請在工具的「<mark style="color:blue;">允許的工具</mark>」確認清單，**不要在角色指令中承諾清單裡沒有的動作**（例如清單沒有寄信工具，就不要讓 Agent 答應「幫你寄出」）。
{% endhint %}

## 事前準備 <a href="#prerequisites" id="prerequisites"></a>

* 你的角色具備 <mark style="color:blue;">工具權限</mark>，可以建立與編輯工具（請組織管理者在 [角色權限管理](/org/roles/role-permission.md) 確認）
* 一個用來授權的 Google 帳號，且該帳號所屬的 Google Workspace 允許第三方應用程式存取。若 Workspace 管理員限制了第三方 OAuth 應用程式，授權會在 Google 端被拒絕，需請管理員放行
* 決定好「授權對象」：這個 Agent 要以**組織共用的一個帳號**操作，還是讓**每位使用者各自登入自己的帳號**（見下方說明）

## 應用流程 <a href="#workflow" id="workflow"></a>

### 1. 建立 Google Workspace 工具 <a href="#step1-create-tool" id="step1-create-tool"></a>

#### 進入工具管理並選擇 MCP 類型 <a href="#open-tool-form" id="open-tool-form"></a>

從左側選單進入 <mark style="color:blue;">AI 功能</mark> → <mark style="color:blue;">工具</mark>，點擊右上角 <mark style="color:blue;">新增工具</mark>。工具類型選擇 <mark style="color:blue;">MCP</mark>，填入顯示名稱（例如 `Google Workspace 工作助理`）與工具描述。

#### 從連接器卡片選擇 Google Workspace <a href="#pick-connector" id="pick-connector"></a>

在「<mark style="color:blue;">選擇要連接的服務</mark>」點選 **Google Workspace** 卡片，系統會自動帶入 MCP 伺服器網址，驗證也由 OAuth 自動處理，不需要在標頭填寫金鑰。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-8c46200f2a5265891f745d958d24cc7a1b28097e%2Fgoogle-workspace-connector-picker.png?alt=media" alt="Google Workspace 連接器卡片已選取，卡片標示 OAuth 2.0 與「搜尋 Gmail 郵件、查詢日曆行程、讀取 Drive 文件」"><figcaption><p>選取 Google Workspace 卡片</p></figcaption></figure>

#### 選擇授權對象 <a href="#choose-auth-subject" id="choose-auth-subject"></a>

選定卡片後，在「<mark style="color:blue;">授權對象</mark>」決定 Agent 要用「誰的 Google 帳號」操作。兩種授權對象的通用規則見 [建立 MCP 工具：選擇授權對象](/build/tools/mcp-setup.md#oauth-auth-subject)；套用到 Google Workspace 時：

| 授權對象                                     | 適合情境                                               | 注意                                       |
| ---------------------------------------- | -------------------------------------------------- | ---------------------------------------- |
| <mark style="color:blue;">組織共用</mark>    | 查共用信箱、共用行事曆、部門共用雲端硬碟；開放給 LINE、Web Chat 匿名訪客的 Agent | 所有使用者都會以「授權者的帳號」存取資料，**不要拿個人信箱做共用授權**    |
| <mark style="color:blue;">聯絡人個別授權</mark> | 員工查自己的信件、行程與檔案                                     | 需要已登入的使用者；**未登入的匿名訪客對話中，Agent 不會取得這個工具** |

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-ab9f1e357542632edf59cbaab6f295ad2a0b56b2%2Fgoogle-workspace-contact-auth.png?alt=media" alt="授權對象選為聯絡人個別授權，提示個別授權需要已登入的使用者"><figcaption><p>選擇「聯絡人個別授權」時，畫面提醒匿名訪客不會取得這個工具</p></figcaption></figure>

#### 完成授權並挑選工具 <a href="#authorize-and-fetch" id="authorize-and-fetch"></a>

* **組織共用**：點擊「<mark style="color:blue;">前往授權</mark>」，在 Google 視窗登入並同意。完成後畫面顯示「<mark style="color:blue;">已授權</mark>」，系統會自動取得工具清單並儲存。再次開啟這個工具，在「<mark style="color:blue;">允許的工具</mark>」只開啟這個 Agent 真正需要的工具，再點擊「<mark style="color:blue;">確認</mark>」。
* **聯絡人個別授權**：這裡不需要授權。聯絡人第一次在對話中用到工具時，對話裡會出現授權卡片，由他用自己的 Google 帳號完成授權。Web Chat 的使用者之後可在 [已連接的服務](/build/choose-channel/web-chat/connected-services.md) 查看或解除連接；管理員可在「<mark style="color:blue;">聯絡人</mark>」編輯視窗的「<mark style="color:blue;">Connector 授權</mark>」分頁查看、撤銷或觸發重新授權。

{% hint style="warning" %}
授權視窗以彈出式視窗開啟。瀏覽器封鎖彈出式視窗時，請允許此網站開啟彈出式視窗後再點一次「<mark style="color:blue;">前往授權</mark>」。
{% endhint %}

### 2. 建立 Agent 並配置工具 <a href="#step2-create-assistant" id="step2-create-assistant"></a>

建立新的 Agent（或編輯既有 Agent），在「<mark style="color:blue;">回答模式設定</mark>」將回答模式切換為 <mark style="color:blue;">Agent</mark>，再到「<mark style="color:blue;">工具</mark>」分頁勾選剛建立的 Google Workspace 工具。詳細步驟見 [為 Agent 配置工具](/build/tools/configure_tools.md)。

角色指令可參考以下寫法，重點是把「授權前怎麼辦」和「不要假裝有做」講清楚：

```
你是公司內部的工作助理，可以透過 Google Workspace 工具搜尋使用者的 Gmail 信件與附件、查詢 Google 日曆行程、搜尋雲端硬碟中的文件。

原則：
1. 查詢前先確認時間範圍與關鍵字，模糊時反問一次再查。
2. 回答只根據工具回傳的內容，附上信件主旨／寄件人／日期或檔案名稱與連結；查不到就直接說查不到，不要猜。
3. 如果工具回應顯示尚未授權或授權過期，說明需要先完成 Google 授權，並請使用者依畫面指示操作；不要重複嘗試呼叫工具。
4. 不要向使用者索取帳號密碼或任何憑證。
5. 涉及信件內容時只摘要與任務相關的部分，不要整封轉貼。
```

{% hint style="info" %}
這個 Agent 若是給**組織成員**在 MaiGPT 或內部問答使用，除了掛工具之外，也可以在 Agent 設定的「<mark style="color:blue;">MaiGPT 連接器</mark>」分頁綁定組織已啟用的連接器（Agent 模式限定），由成員各自授權。組織啟用連接器的方式見 [管理連接器（管理員）](/work/maigpt/connectors/connectors-admin.md)。
{% endhint %}

### 3. 上線應用 <a href="#step3-go-live" id="step3-go-live"></a>

完成後即可在 Agent 的對話介面測試。以下是幾個常見的提問與 Agent 的處理方式：

| 使用者提問                   | Agent 會做的事                    |
| ----------------------- | ----------------------------- |
| 「找上週財務部寄來、附件是 Excel 的信」 | 以寄件人、時間與附件條件搜尋信件，列出主旨、日期與附件名稱 |
| 「這封信的附件在講什麼？幫我摘要」       | 讀取附件內文並摘要重點                   |
| 「我這週還有哪些空檔可以排 1 小時會議？」  | 讀取日曆行程，整理可用時段                 |
| 「雲端硬碟裡有沒有『年度預算』相關的試算表？」 | 搜尋雲端硬碟，回傳檔案名稱與連結              |

每次工具呼叫的參數與回傳內容可到 [工具執行紀錄](/build/agent-ops/tool-execution-records.md) 查看，確認 Agent 是否用對工具、授權是否仍有效。

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

**Q：授權時 Google 顯示「這個應用程式已遭封鎖」，或無法選擇公司帳號？**\
A：代表貴公司的 Google Workspace 管理員限制了第三方 OAuth 應用程式。請 Workspace 管理員在管理控制台放行 MaiAgent 的應用程式後再授權。

**Q：之前可以用，現在 Agent 說授權失效？**\
A：Google 的授權權杖可能過期或被撤銷。組織共用授權請開啟該工具，點「<mark style="color:blue;">註銷</mark>」後重新「<mark style="color:blue;">前往授權</mark>」；聯絡人個別授權可由本人在 [已連接的服務](/build/choose-channel/web-chat/connected-services.md) 點「<mark style="color:blue;">重新授權</mark>」，或由管理員在「<mark style="color:blue;">聯絡人</mark>」編輯視窗的「<mark style="color:blue;">Connector 授權</mark>」分頁觸發重新授權。

**Q：如何收回授權？**\
A：組織共用授權在工具設定點「<mark style="color:blue;">註銷</mark>」；聯絡人個別授權由本人在 [已連接的服務](/build/choose-channel/web-chat/connected-services.md) 解除連接，管理員也能在「<mark style="color:blue;">聯絡人</mark>」編輯視窗的「<mark style="color:blue;">Connector 授權</mark>」分頁撤銷。若要連 Google 端的紀錄一併移除，再到 Google 帳戶的「第三方應用程式與服務」移除 MaiAgent 的存取權。

**Q：可以讓 Agent 代替使用者寄信、建立行程或寫入檔案嗎？**\
A：取決於授權範圍與取得的工具清單。先確認「<mark style="color:blue;">允許的工具</mark>」裡確實有對應的工具（例如寄信、建立行程），再寫進角色指令；成員在 MaiGPT 授權時，Gmail 要選「傳送與管理」、日曆要選「完整存取」。

## 延伸閱讀 <a href="#further-reading" id="further-reading"></a>

* [建立 MCP 工具](/build/tools/mcp-setup.md)：MCP 工具欄位與 OAuth 連接器的完整說明
* [為 Agent 配置工具](/build/tools/configure_tools.md)
* [工具執行紀錄](/build/agent-ops/tool-execution-records.md)
* [已連接的服務](/build/choose-channel/web-chat/connected-services.md)：使用者自助管理個人授權
* [連接器](/work/maigpt/connectors.md)：成員在 MaiGPT 自助授權
* [啟用與管理 › 連接器](/work/built-in-agents/management.md#connectors)：官方內建 Agent 的連接器授權方式


---

# 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/build/integrate/google-workspace-connector.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.