Team objects and request preparation

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

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 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.

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.

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.

Last updated on