# 提交团队消息

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

向团队会话提交一轮消息并取得任务标识。


```http
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agent-teams/{team_id}/sessions/{context_id}/messages
```

## 调用前准备

`BASE_URL` 使用产品 API 前缀 `https://api.moi.matrixorigin.cn/v5`；专有部署填写对应的产品 API 地址。

[准备同环境产品身份与对象标识](objects.md#prepare)。

## 请求

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl --request POST \
  "$BASE_URL/workspaces/$WORKSPACE_ID/agent-teams/$TEAM_ID/sessions/$CONTEXT_ID/messages" \
  --header "X-API-Key: $MOI_KEY" \
  --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data '{"message_id":"message-example","parts":[{"kind":"text","text":"整理资料"}],"requested_member":{"agent_workspace_id":"workspace-example","agent_id":"agent-example"},"idempotency_key":"team-turn-example"}'
```

:::::
:::::{tab-item} 参数说明

| 参数 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `workspace_id` | 路径 | string | 是 | 当前工作区ID，与产品身份和请求头保持同环境一致。 |
| `team_id` | 路径 | string | 是 | 团队ID，来自团队列表或创建响应。 |
| `context_id` | 路径 | string | 是 | 团队会话ID，来自会话创建或列表。 |
| `message_id` | 请求体 | string | 是 | 非空且无首尾空白的消息标识。 |
| `parts` | 请求体 | array（消息部件数组） | 是 | 非空数组；[文本部件](objects.md#parts)示例。 |
| `requested_member` | 请求体 | object | 否 | 明确选择的成员引用。 |
| `idempotency_key` | 请求体 | string | 是 | 本次提交的唯一键；同次重试保持，新内容换新键。 |
| `metadata` | 请求体 | object | 否 | 业务元数据；运行期保留键不可填写。 |

202表示已受理。保存 task_id，通过[任务结果确认](lifecycle.md#task)读取最终状态；selection 是该轮冻结的选择，不是回答。requested_member须是当前合法成员；省略时按成员/选择器决定。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": 0,
  "data": {
    "task_id": "task-example",
    "selection": {
      "member": {
        "agent_workspace_id": "workspace-example",
        "agent_id": "agent-example"
      },
      "reason": "explicit",
      "membership_version": 2,
      "snapshot": {
        "strategy": "explicit"
      }
    }
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 成功为0。 |
| `data` | object | [对应返回对象](objects.md#responses)。 |

HTTP202；返回[对应对象](objects.md#responses)，写后使用对应读取动作确认。

:::::
::::::
:::::::

## 错误响应

[错误与并发处理](lifecycle.md#errors)区分参数、版本、成员/会话状态及准入失败。
