# 团队对象与请求准备

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

团队管理、成员、会话和消息分别使用自己的标识与版本。团队成员是智能体，不是工作区用户或角色成员。

<span id="prepare"></span>

## 调用前准备

从同一个环境取得产品API基地址、个人访问令牌及工作区ID。示例使用 BASE_URL、MOI_KEY、WORKSPACE_ID，BASE_URL已包含该环境产品前缀。TEAM_ID来自创建/列表；CONTEXT_ID来自团队会话；AGENT_WORKSPACE_ID和AGENT_ID来自智能体定义。

创建使用 agent_team.create；读取使用 agent_team.read；资料、成员、会话及消息提交使用 agent_team.update；删除使用 agent_team.delete。实际请求仍须经过当前身份、Role和正式权限边界；owner_user_id不是本地放行依据。

(member)=
## 成员引用

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `agent_workspace_id` | string | 智能体定义工作区，保留系统/本工作区差异。 |
| `agent_id` | string | 该定义工作区内的智能体ID。 |

同一团队只允许本工作区或系统工作区的适用智能体。组合须唯一，不能只按 agent_id 去重。成员读取另外含 team_id、created_at；data直接为数组，不分页。

<span id="responses"></span>

## 团队对象

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 团队ID。 |
| `workspace_id` | string | 团队所属工作区。 |
| `owner_user_id` | string | 保存的归属用户；不替代请求授权。 |
| `name` | string | 名称。 |
| `description` | string | 说明；空时省略。 |
| `status` | string | active、deleting或deleted。 |
| `version` | integer | 团队资料/状态版本；用于更新和删除。 |
| `membership_version` | integer | 成员目录版本；用于添加和移除成员。 |
| `created_at`、`updated_at` | string | RFC3339时间。 |

创建空团队时两个版本从1开始；每个实际初始成员加入会推进membership_version。不要把带初始成员的创建结果固定假设为membership_version=1。成员变更不等同于资料version变更；资料更新还可能因并发成员变更发生冲突。

## 会话对象

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `workspace_id`、`team_id` | string | 所属工作区和团队。 |
| `context_id` | string | 团队会话ID；用于改名、发送和读取消息。 |
| `name` | string | 会话名称，可为空。 |
| `version` | integer | 该会话的版本，重命名使用此值。 |
| `astra_session_id` | string | 已建立的提供商会话标识，空时省略。 |
| `created_via_ingress_connection_id` | string | 创建来源连接，空时省略。 |
| `created_by_external_user_id` | string | 创建来源的外部用户，空时省略。 |
| `created_by_moi_user_id` | string | MOI创建者，空时省略。 |
| `updated_via_ingress_connection_id` | string | 最近更新来源连接，空时省略。 |
| `updated_by_external_user_id` | string | 最近更新来源的外部用户，空时省略。 |
| `updated_by_moi_user_id` | string | 最近更新的MOI用户，空时省略。 |
| `active_task_id` | string | 当前活动任务，空时省略。 |
| `pending_ingress_id` | string | 待处理占用标识，空时省略；不当作消息ID。 |
| `last_answering_agent_workspace_id`、`last_answering_agent_id` | string | 最近回答者的定义工作区及ID，空时省略。 |
| `created_at`、`updated_at` | string | RFC3339时间。 |

last_completed_task_id在当前HTTP对象中不导出。会话创建不启动模型，改名不清理占用；没有据当前13路由发明会话DELETE或取消命令。

## 列表与消息

团队、会话、消息列表返回 data.items/total/limit/offset。total是当前筛选范围的总数；普通翻页在offset + items.length达到total或当前items为空时停止。成员列表的data则直接为数组。

| 消息字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 输入消息优先使用原message_id，输出可为快照标识。 |
| `conversation_id` | string | 对应团队context_id。 |
| `task_id` | string | 所属任务。 |
| `agent_workspace_id`、`agent_id` | string | 真实执行智能体身份。 |
| `role` | string | user或agent。 |
| `parts` | array（部件数组） | 公开内容投影。 |
| `state` | string | 输出任务状态，空时省略。 |
| `committed` | boolean | 快照提交标记；agent输出在completed时为true。 |
| `created_at` | string | RFC3339时间。 |

(parts)=
## 消息部件

文本示例使用 `{"kind":"text","text":"整理资料"}`。ToolPart还定义可选file/data/metadata；file使用uri、mimeType和name。文件可访问性、附件归属及其他部件联合分支另需核验，不能仅凭开放JSON字段承诺可读取任意URI。

提交metadata不得填moi.runtime.managed_turn、ingress_receipt_id或external_conversation_id；这些键由运行期管理。选择信息由服务端写入agent_team_selection，客户端不据元数据获得额外权限。

## 提交回执

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `task_id` | string | 已受理任务标识，需查询终态。 |
| `selection.member` | object | |
| `selection.reason` | string | explicit、single_member、continuity、default、clarify或delegate。 |
| `selection.membership_version` | integer | 选择时的成员版本。 |
| `selection.snapshot` | object | 选择时保存的策略及模型/能力摘要，内容随选择路径变化。 |
