> 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/authorization-integration/role-vs-contact.md).

# 角色(Role) 和 聯絡人(Contact) 的差異

內部成員用角色（Role）管理平台權限，外部使用者用聯絡人（Contact）識別身份——兩者的定義、差異與選擇方式

MaiAgent 中有兩種「人」：**成員（Member）**——登入 MaiAgent 平台操作後台的帳號，權限由\*\*角色（Role）\*\*決定；**聯絡人（Contact）**——跟 AI 助理對話的終端使用者，不需要 MaiAgent 帳號。串接時最常見的混淆就是把兩者搞混，本頁把差異一次講清楚。

## 定義 <a href="#definitions" id="definitions"></a>

### 聯絡人（Contact） <a href="#contact-definition" id="contact-definition"></a>

代表「跟 AI 助理對話的終端使用者」：您網站上的訪客、會員系統的使用者、LINE 好友都是聯絡人。聯絡人不登入 MaiAgent，由系統在對話時自動建立，或由您的系統透過 API 建立並與自家帳號對應。對話歷史、個人化屬性、知識查詢範圍、工具憑證都掛在聯絡人上。

{% hint style="info" %}
聯絡人的資料模型與串接方式請參考[聯絡人 (Contact) 介紹及串接](/tech/authorization-integration/contacts.md)。
{% endhint %}

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-014415472288f559f650849304a7b45e5d2cb89d%2F%E6%88%AA%E5%9C%96%202025-07-07%20%E4%B8%8B%E5%8D%886.29.05%20(1).png?alt=media" alt=""><figcaption><p>未設定姓名的聯絡人預設顯示為匿名</p></figcaption></figure>

### 角色（Role） <a href="#role-definition" id="role-definition"></a>

角色是**成員的權限模板**：定義登入 MaiAgent 後台的成員可以操作哪些功能、存取哪些資源（AI 助理、知識庫、收件匣等）。企業可預先定義「客服人員」「行政人員」「實習生」等角色，成員加入組織時直接套用，不必逐人設定。

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-3ee9233a19709cbeb9d408d978d2b331b2f8e898%2F%E6%88%AA%E5%9C%96%202025-07-07%20%E4%B8%8B%E5%8D%886.36.55.png?alt=media" alt=""><figcaption><p>成員基本資料中的角色設定</p></figcaption></figure>

## 差異對照 <a href="#comparison" id="comparison"></a>

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-bb81392bc29a9771001ca21c0572cd2a94c123fc%2F%E6%88%AA%E5%9C%96%202025-07-07%20%E4%B8%8B%E5%8D%886.32.19.png?alt=media" alt=""><figcaption><p>AI 助理嵌入畫面</p></figcaption></figure>

|        比較項目        |                 聯絡人（Contact）                 |      角色（Role）     |
| :----------------: | :------------------------------------------: | :---------------: |
|      🎯 **對象**     |               外部終端使用者（訪客、會員、客戶）              |    內部成員（員工、管理者）   |
| 👤 **MaiAgent 帳號** |                     ❌ 不需要                    |    ✅ 需要（成員登入平台）   |
|     📋 **建立方式**    |             對話時自動建立、API 建立、後台手動建立            |   後台預先定義角色，成員套用   |
|     🎯 **控制什麼**    | 該使用者的對話歷史、個人化屬性、知識查詢範圍（query\_metadata）、工具憑證 | 成員在後台的操作權限與資源存取範圍 |
|     ⚙️ **管理入口**    |                API 串接或後台「聯絡人」                |     後台「角色權限管理」    |

## 知識範圍控制的分工 <a href="#knowledge-scope" id="knowledge-scope"></a>

兩者都能影響「查得到哪些知識」，但機制不同：

* **聯絡人**：在聯絡人上設定 [Query Metadata](/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md)，限制該使用者對話時 AI 可檢索的知識庫／文件／標籤範圍
* **角色**：控制成員在平台內**看得到、管得到**哪些資源（詳見使用者手冊的[角色權限管理](https://docs.maiagent.ai/org/role-permission)）；成員在內部問答中則可逐訊息選擇要參考的知識範圍

## 怎麼選 <a href="#how-to-choose" id="how-to-choose"></a>

* **對外服務**（官網客服、會員中心、嵌入自家產品）：使用者不需要也不該有 MaiAgent 帳號 → 用**聯絡人**，依身份掛 query\_metadata 或自訂屬性做差異化
* **對內使用**（員工用內部問答、團隊維運 AI 助理）：成員登入平台 → 用**角色**統一發放權限
* 兩者可並存：同一個企業通常同時有「管後台的成員」與「跟 AI 對話的聯絡人」，各走各的機制，互不重疊

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-53645aaed37bd279cd5330b940b591e287bba444%2Fimage%20(34).png?alt=media" alt=""><figcaption><p>Contact 與 Role 授權使用建議</p></figcaption></figure>


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/tech/authorization-integration/role-vs-contact.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.