Team versions, tasks, and deletion

After managing a team, confirm member, conversation, and task states separately. One successful HTTP response cannot replace subsequent run results.

Versions and concurrency

Task

Version input

Location

Update team

Team version

JSON expected_version。

Delete team

Team version

Query expected_version.

Add/remove members

Team membership_version

Query expected_membership_version.

Rename conversation

Conversation version

JSON expected_version。

On a version conflict, reread the corresponding object and confirm the intended change still applies before resubmitting. Do not blindly increment the version or treat the CLI’s unified –expected-version as a uniform HTTP field.

Message selection and idempotency

An empty team can be saved and can have conversations, but selecting a runner requires members. Explicit requested_member selection remains subject to membership and runtime admission. One member allows deterministic selection; multiple members may use a selector. Member version, occupancy, and actual Agent admission are rechecked. Configured members do not establish readiness of every runtime dependency.

Use the same idempotency_key for the same submission. Replay reads the frozen selection and task_id without selecting again, while still requiring matching context, team, and caller identity. Current implementation does not compare old and new message content field by field, so new content needs a new key. The key is queried within a Workspace, not uniquely within one team only.

Confirm task results

HTTP202 from submission means accepted only. Save task_id. Read the actual state using GET /workspaces/{workspace_id}/agent-runtime-tasks/{task_id}, and corresponding events when needed. Team messages supplement the conversation’s public inputs/outputs.

For input_required or auth_required, follow the actual interaction requirements returned. selection, a successful conversation rename, or empty occupancy fields do not establish task completion. Consult the corresponding operation pages for complete part, interaction, and artifact contracts.

Deletion effects

Deleting with the current team version returns a deleted team record. The inspected transaction chain cleans up member references, all target incoming connections, and their managed credentials, with the formal lifecycle boundary handling team and child-connection Ownership. Receiver shutdown advances through persisted work markers; the HTTP response does not establish immediate external disconnection.

Deletion does not cancel active tasks, and these 13 operations provide no contract for clearing all historical conversations. Identify associated entry points and tasks before deletion. Afterward, check team state, members/entry points, and run states.

Errors and recovery

Domain errors use numeric code/message/details, with details.reason providing stable classification. The formal IAM layer may return a different framework error beforehand.

Symptom

Verified current mapping

Task

Missing parameters, nonpositive versions, or member Workspace mismatch

400; code=2. Workspace mismatch may include team_member_workspace_mismatch.

Correct inputs and ID sources.

Team, member, or conversation not found

404;code=3,channel_target_not_found。

Query the corresponding object again.

Profile/member/conversation version conflict

409;code=4,channel_target_version_conflict。

Read the corresponding version again.

Team/member unavailable or conversation occupied

409;code=15,channel_target_unavailable。

Check status and existing tasks; do not automatically resubmit.

Complete mappings for empty-team selection errors, selector failures, and downstream runtime errors still require retesting. Do not classify all as 400 or retryable. Dependency errors, unknown timeout outcomes, and zero-change-on-failure claims require real business evidence.

Last updated on