> 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/identity-and-access/agent-team-permissions.md).

# Agent Teams：角色資源授權

串接 Agent Teams 的角色資源授權，區分使用、查看對話紀錄、編輯與刪除，避免把團隊平台當成獨立授權來源。

整合系統替角色分配 Agent Team 時，授權單位是團隊。團隊的入口 Agent 與入口 Agent 的對話平台會沿用團隊授權，不需要替每個平台另配一份權限。

例如，企業整合管理員希望客服角色可以使用指定團隊，但不能查看其他人的對話或修改團隊。先把該團隊分配給角色，保留預設的「使用」權限即可；需要主管檢視歷史時，再另外授予「查看對話紀錄」。

後台操作方式請看使用者手冊的 [Agent Teams](https://docs.maiagent.ai/build/teams)。

## 四項權限 <a href="#permission-flags" id="permission-flags"></a>

| 授權欄位                   | 用途                         | 新分配時的預設值 |
| ---------------------- | -------------------------- | -------- |
| `canRead`              | 使用團隊，並在入口 Agent 的對話平台與團隊對話 | `true`   |
| `canViewConversations` | 查看團隊的對話紀錄及執行記錄             | `false`  |
| `canUpdate`            | 修改團隊畫布、成員及入口設定             | `false`  |
| `canDelete`            | 刪除團隊                       | `false`  |

{% hint style="warning" %}
查看對話紀錄、編輯與刪除都依附「使用」。更新權限時，若要把 `canRead` 關閉，必須同時關閉其餘三項，否則請求會被拒絕。
{% endhint %}

成員屬於多個角色時，各角色對同一團隊的四項權限分別取聯集。移除一個角色的授權，不代表成員一定失去存取權，還要檢查其他角色；組織擁有者具有全部四項權限。

## 分配與更新 <a href="#assign-and-update" id="assign-and-update"></a>

以下路徑位於 `/api/organizations/{organizationId}/groups/{groupId}/group-teams/` 底下，`{grantId}` 是授權紀錄的 ID，與團隊 ID 不同。

| 方法       | 相對路徑           | 用途                                        |
| -------- | -------------- | ----------------------------------------- |
| `GET`    | 根路徑            | 列出角色的團隊授權                                 |
| `POST`   | `bulk-create/` | 以 `{"teams":["<teamId>"]}` 分配團隊；已分配的團隊會略過 |
| `PATCH`  | `{grantId}/`   | 更新該筆授權的四項權限                               |
| `DELETE` | `{grantId}/`   | 移除該筆角色授權                                  |

回應中的 `team` 包含團隊的 `id`、`name` 與入口 Agent 的 `inboxes`，可用來顯示這筆團隊授權涵蓋哪些對話平台。請使用回傳的授權 `id` 更新或移除授權，不要把 `team.id` 當成授權 ID。

分配時只能指定同組織內可分配的團隊。角色會先依呼叫者目前的組織查找，跨組織角色回 `404`；不能修改擁有者角色的授權。授權列表與寫入另受「組織概覽」權限檢查。

## 團隊操作仍有功能與方案檢查 <a href="#feature-and-plan-gates" id="feature-and-plan-gates"></a>

資源授權決定「哪個團隊能做什麼」，不會取代功能開關或方案資格。管理團隊仍受平台的 Agent Teams 開關與團隊功能權限控制；建立團隊還需角色允許新增團隊。建立或刪除團隊、修改或升級入口，還須通過 Agent Builder 的方案檢查。

讀取執行記錄時，須先通過平台功能開關與執行記錄入口的功能權限檢查。通過後，沒有團隊使用授權時回 `404`；有使用授權、但沒有查看對話紀錄授權時，回 `403`。

既有的一般 Agent／對話平台授權，不會替團隊入口 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/tech/identity-and-access/agent-team-permissions.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.
