# Team objects and request preparation

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

Team management, members, conversations, and messages use their own identifiers and versions. Team members are agents, not Workspace users or role members.

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

## Before you call this API

Obtain the product API base URL, personal access token, and Workspace ID from the same environment. Examples use BASE_URL, MOI_KEY, and WORKSPACE_ID; BASE_URL includes the environment's product prefix. TEAM_ID comes from creation/list; CONTEXT_ID from team conversations; AGENT_WORKSPACE_ID and AGENT_ID from agent definitions.

Creation uses agent_team.create; reads use agent_team.read; profile, member, conversation, and message submission use agent_team.update; deletion uses agent_team.delete. Actual requests still pass current identity, Role, and formal authorization boundaries. owner_user_id does not locally bypass authorization.

(member)=
## Member references

| Field | Type | Description |
| --- | --- | --- |
| `agent_workspace_id` | string | Agent definition Workspace; preserve the distinction between system and current Workspaces. |
| `agent_id` | string | Agent ID within that definition Workspace. |

A team accepts applicable agents only from the current or system Workspace. Pairs must be unique; do not deduplicate by agent_id alone. Member reads also include team_id and created_at. data is directly an array without pagination.

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

## Team object

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Team ID. |
| `workspace_id` | string | Workspace owning the team. |
| `owner_user_id` | string | Saved owning user; does not replace request authorization. |
| `name` | string | Name. |
| `description` | string | Description; omitted when empty. |
| `status` | string | active, deleting, or deleted. |
| `version` | integer | Team profile/state version; used for updates and deletion. |
| `membership_version` | integer | Member directory version; used to add and remove members. |
| `created_at`、`updated_at` | string | RFC3339 timestamp. |

Both versions start at 1 for an empty team. Each actual initial member addition advances membership_version. Do not assume creation with initial members returns membership_version=1. Member changes are distinct from profile version changes; profile updates may also conflict with concurrent member changes.

## Conversation object

| Field | Type | Description |
| --- | --- | --- |
| `workspace_id`、`team_id` | string | Owning Workspace and team. |
| `context_id` | string | Team context ID; used for renaming, sending, and reading messages. |
| `name` | string | Conversation name; may be empty. |
| `version` | integer | Conversation version, used for renaming. |
| `astra_session_id` | string | Established provider session identifier; omitted when empty. |
| `created_via_ingress_connection_id` | string | Source connection at creation; omitted when empty. |
| `created_by_external_user_id` | string | External user responsible for creation; omitted when empty. |
| `created_by_moi_user_id` | string | MOI creator; omitted when empty. |
| `updated_via_ingress_connection_id` | string | Source connection for the latest update; omitted when empty. |
| `updated_by_external_user_id` | string | External user responsible for the latest update; omitted when empty. |
| `updated_by_moi_user_id` | string | MOI user responsible for the latest update; omitted when empty. |
| `active_task_id` | string | Current active task; omitted when empty. |
| `pending_ingress_id` | string | Pending occupancy identifier; omitted when empty. Not a message ID. |
| `last_answering_agent_workspace_id`、`last_answering_agent_id` | string | Definition Workspace and ID of the latest responder; omitted when empty. |
| `created_at`、`updated_at` | string | RFC3339 timestamp. |

last_completed_task_id is not exported in the current HTTP object. Conversation creation does not start a model; renaming does not clear occupancy. The current 13 routes provide no basis for a conversation DELETE or cancellation command.

## Lists and messages

Team, conversation, and message lists return data.items/total/limit/offset. total counts the current filtered scope. Stop normal pagination when offset + items.length reaches total or items is empty. Member-list data is directly an array.

| Message field | Type | Description |
| --- | --- | --- |
| `id` | string | Input messages prefer the original message_id; outputs may use snapshot identifiers. |
| `conversation_id` | string | Corresponding team context_id. |
| `task_id` | string | Owning task. |
| `agent_workspace_id`、`agent_id` | string | Actual executing agent identity. |
| `role` | string | user or agent. |
| `parts` | array (parts) | Public content projection. |
| `state` | string | Output task state; omitted when empty. |
| `committed` | boolean | Snapshot commit marker; true for agent output at completed. |
| `created_at` | string | RFC3339 timestamp. |

(parts)=
## Message parts

The text example uses `{"kind":"text","text":"整理资料"}`. ToolPart also defines optional file/data/metadata; file uses uri, mimeType, and name. File accessibility, attachment ownership, and other part-union branches require separate verification. Open JSON fields do not guarantee reading arbitrary URIs.

Do not submit moi.runtime.managed_turn, ingress_receipt_id, or external_conversation_id in metadata; runtime manages these keys. The server writes selection information to agent_team_selection. Metadata does not grant additional client privileges.

## Submission receipt

| Field | Type | Description |
| --- | --- | --- |
| `task_id` | string | Accepted task identifier; query its terminal state. |
| `selection.member` | object | |
| `selection.reason` | string | explicit, single_member, continuity, default, clarify, or delegate. |
| `selection.membership_version` | integer | Membership version at selection. |
| `selection.snapshot` | object | Policy and model/capability summary saved at selection; contents vary by selection path. |
