团队版本、任务与删除¶
管理团队后,分别确认成员、会话和任务状态。一次HTTP成功不能代替后续运行结果。
版本与并发¶
操作 |
版本输入 |
位置 |
|---|---|---|
更新团队 |
团队version |
JSON expected_version。 |
删除团队 |
团队version |
查询expected_version。 |
添加/移除成员 |
团队membership_version |
查询expected_membership_version。 |
重命名会话 |
会话version |
JSON expected_version。 |
版本冲突后重新读取相应对象,确认目标改动仍适用后再提交。不能机械加一重试,也不能把CLI统一的–expected-version当作HTTP字段统一。
消息选择与幂等¶
空团队可保存和创建会话,实际选人时需要成员。requested_member显式选择仍受成员与运行准入限制;单成员可确定选择,多成员可调用选择器,并重新检查成员版本、占用及真实Agent准入。配置成员不代表所有运行依赖已准备好。
同次提交使用相同idempotency_key。重放读取已冻结选择及task_id,不重新选人;仍要求上下文、团队、调用身份相符。当前实现不逐字段比较新旧消息内容,因此新内容须用新键。该键按工作区查询,不当作仅在一个团队内唯一。
任务结果确认¶
提交响应HTTP202只表示已受理,保存task_id。使用 GET /workspaces/{workspace_id}/agent-runtime-tasks/{task_id} 读取真实状态,必要时读取对应events;团队消息列表补充该会话的公开输入/输出。
遇到input_required或auth_required,按返回的真实交互要求处理。不能以selection、会话改名成功或占用字段为空代替任务完成。完整部件、交互和产物合同仍需对应动作页配合。
删除影响¶
使用团队当前version删除后,响应是deleted团队记录。所查事务链清理成员引用、全部目标入站连接及其托管凭据,并由正式生命周期边界处理团队和子连接Ownership。接收器停用通过持久工作标记推进;不能由HTTP返回推断外部连接已经即时断开。
删除不等于取消活动任务,也没有在这13动作中清除全部历史会话的合同。删除前识别关联入口与任务;删除后核对团队状态、成员/入口及运行状态。
错误与恢复¶
领域错误经数值code/message/details返回,details.reason为稳定分类;正式IAM层可在此前返回另一种框架错误。
现象 |
已核对的当前映射 |
操作 |
|---|---|---|
参数缺失、版本非正、成员工作区不符 |
400;code=2,工作区错配可有team_member_workspace_mismatch。 |
修正输入和ID来源。 |
团队、成员或会话不存在 |
404;code=3,channel_target_not_found。 |
回查对应对象。 |
资料/成员/会话版本冲突 |
409;code=4,channel_target_version_conflict。 |
重新读取相应版本。 |
团队/成员不可用或会话占用 |
409;code=15,channel_target_unavailable。 |
查看状态和已有任务;不自动重复提交。 |
空团队选人错误、选择器失败和下游运行错误的完整映射仍需复测,不把它们全部写成400或可重试。依赖错误、超时结果未知与失败零变更需要真实业务证据。