公开链接与访客身份

公开 Web 应用在发布记录允许的范围内为匿名访客提供会话。发布 token、访客 session 和登录用户的产品凭据分别有各自用途。

调用前准备

内部源码或前端代码中的历史 /api/v1 字符串不能直接作为部署地址。WEBAPP_SHORT_CODE是链接中的22字符短码;AGENT_ID、WEBAPP_TOKEN 来自发布链接或解析结果,WEBAPP_SESSION 来自 session 响应。示例均使用占位值,不填写真实凭据到维护记录。

  1. 对 ?k=... 链接,向 resolve 提交 k,取得 agent_id,随后以短码作为 t。旧式链接使用 webapp 与 t;不能混合两种解析输入。

  2. 首次访问创建 session。保存 session_token 及 expires_in;后续数据请求使用查询参数 s,刷新接口则使用 JSON 字段 session。

  3. 使用同一身份创建会话,保存 data.id。消息、事件、附件、反馈和 MCP 应用操作继续携带当前链接及该身份,并引用自己的会话/任务。

  4. 返回访问时刷新尚有效的 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、前端实际分支不一致;

最后更新于