公开链接与访客身份¶
公开 Web 应用在发布记录允许的范围内为匿名访客提供会话。发布 token、访客 session 和登录用户的产品凭据分别有各自用途。
调用前准备¶
内部源码或前端代码中的历史 /api/v1 字符串不能直接作为部署地址。WEBAPP_SHORT_CODE是链接中的22字符短码;AGENT_ID、WEBAPP_TOKEN 来自发布链接或解析结果,WEBAPP_SESSION 来自 session 响应。示例均使用占位值,不填写真实凭据到维护记录。
对
?k=...链接,向 resolve 提交k,取得agent_id,随后以短码作为t。旧式链接使用webapp与t;不能混合两种解析输入。首次访问创建 session。保存
session_token及expires_in;后续数据请求使用查询参数s,刷新接口则使用 JSON 字段session。使用同一身份创建会话,保存
data.id。消息、事件、附件、反馈和 MCP 应用操作继续携带当前链接及该身份,并引用自己的会话/任务。返回访问时刷新尚有效的 session。明确失效后才创建新身份;依赖故障应保留原身份并重试。
这些接口 handler 不读取产品 PAT、登录 Cookie 或 CSRF 参数作为访客凭据。部署网关的跨域和 Cookie 策略仍需环境核对,不能由 handler 推断线上策略。
生命周期¶
session 有效期固定 604800 秒。刷新签发新凭据并延续同一访客,旧凭据仍可用到自身到期;重新创建 session 则是新访客,不能列出旧身份的会话。
session 签名绑定发布工作区、智能体及访客身份,不直接绑定链接 token。轮换链接后,旧链接不能继续通过准入;取得新链接且原 session 仍有效时,不能声称原 session 已被密码学吊销。停用或轮换会在后续公开请求和流的重读时重新校验,不等于立即取消已经准入的后台任务。
同一智能体在不同工作区有独立发布记录。公开会话必须属于本访客、目标智能体、purpose=webapp 且为 active。归档后消息、事件、反馈和任务产物等公开访问同样不再准入。发布方管理历史的可见性使用另一组接口。
新 session 绑定发布记录的创建代次,删除再创建的发布不能继承原代次身份;旧记录兼容及依赖故障分别保留明确错误。resolve 只检查链接及展示事实,不证明智能体当前 active、发布身份可执行或模型任务一定成功。
错误与身份处理¶
普通成功响应使用数值 code=0 和 data;错误使用 code/message。下载、预览及 A2A 流按各自响应处理。
HTTP/代码 |
含义与处理 |
|---|---|
404 / 3 |
公开准入不可用,包括链接、session、会话或任务绑定不匹配;不要据此判定对象全局不存在。 |
404 / 16 |
匹配的链接已停用;无需丢弃已存访客身份。 |
404 / 17 |
刷新接口确认 session 无效;新身份将不具有旧身份的历史。 |
400 / 2 |
可修正输入,包括标题、反馈及文件等参数。 |
409 / 2 |
会话忙等冲突;不能当成不存在。 |
429 / 18 |
发布共享上传预算不足。 |
500 / 1 |
存储或运行依赖故障;保留访客身份,不以新建 session 掩盖故障。 |
预览另有 415、413/19、422/20;MCP 应用另有 400、404、409、503/15 等结果。A2A 在打开流前还可返回 JSON-RPC 错误,流打开后检查错误帧,不能只看 HTTP 状态。
权限规范仍有旧“全部失败404”和“刷新失败code3”的描述,与当前 handler/service、前端实际分支不一致;