发布记录、链接与历史¶
管理API只修改发布记录和读取历史;公开访客的准入、会话刷新及调用分别使用公开数据面。
首次读取与默认状态¶
当前创建智能体的链路可自动创建enabled=true的发布记录。对没有记录的旧智能体,管理GET会先证明本工作区或系统定义存在,再创建enabled=false记录及token;并发首次读取会回读已有记录。
因此GET不是所有情况下都没有持久副作用,不能将新建智能体的默认状态套到旧对象。启停/轮换要求已有发布记录,未知Agent不能通过GET造出孤立发布记录。
启停与轮换¶
PATCH必须给明确boolean;false不能省略为“无改动”。重复当前enabled状态成功但不重写记录,保留token与时间;也不能据此声称已刷新旧发布身份。
停用保留token,重新启用恢复相同链接;轮换更换token/短码并更新last_rotated_at,enabled状态保留。轮换不是返回同token的幂等重试。结果未知时先GET核对当前链接,再决定后续动作。
启用时保存的发布身份来自当前工作区owner快照,轮换也重新捕获;内部publisher字段不在响应DTO中。旧记录或owner变化能否继续准入、已经打开的访客会话及正在进行的流何时失效,须按公开会话协议和真实环境验证,不能只由管理PATCH成功推断。
历史查询¶
管理方按Agent读取Web应用purpose的会话、消息和反馈,权限复用agent.read。它不按当前登录管理者创建的访客来过滤,也不因链接停用就隐藏历史。
会话列表status默认active,all包含active和archived;消息读取另确认会话属于当前Agent定义、purpose=webapp且可见。所有列表默认50、最大200,负offset按0;按当前返回总数和空页停止,不能当跨请求固定快照。
错误与回读¶
管理入口使用数值code/message:参数不合法可400、对象/会话不存在可404、权限拒绝403、授权依赖不可用503,其余按具体错误映射。站点配置使用另一套字符串code/msg,不复用管理错误表。
启停/轮换的业务写入与操作审计分在后续事务;审计写入失败可使请求报错,而发布记录已经改变。遇到整体错误或响应未知先GET回读,不承诺失败一定恢复原状态;
当前管理操作没有expected_version请求参数;服务端内部使用旧token及创建时间比较保护记录,不能由此发明客户端CAS字段。也不要给这些接口增加没有注册的Web应用DELETE、固定版本发布或upgrade动作。