个人 Agent 接入:身份、会话与账号能力

个人 Agent 接入:身份、会话与账号能力

企业接入向导回答"企业要提供什么";本页回答个人 Agent 开发者要准备什么。两者合起来才是完整链路;字段与算法以1.0 规范源文件为准。

你要发布什么

  • 客户端元数据与公钥:个人 Agent 通过 HTTPS 提供自己的元数据与公钥,供企业校验你的请求身份。
  • 每企业独立的 User ID:每个用户在每家企业使用独立、稳定、不含个人信息的 User ID。不要直接使用邮箱或邮箱散列——它跨企业可关联。

发现与身份

请求企业发现文档时先安全获取(HTTPS、固定来源),再做双向校验:企业元数据与 issuer 元数据相互印证,确认你面对的确实是该企业。校验细节见发现文档与企业身份校验。

会话是你的身份线

正式 1.0 把会话与账号分开。Session 由你标识:

  • 为每个会话生成随机会话 ID;
  • 每个请求都用委托密钥新签一个会话 JWT(声明会话 ID、用户 ID、请求方法与地址),放在 Poppy-Session 头中,并携带 Poppy-Version;
  • 会话 JWT 是每请求一次的证明,不复用旧签名。

未登录的会话请求同样是合法请求;会话与账号登录是两条独立的线。

账号能力按需接入

只有当任务确实需要账号能力时才引导用户登录:

  • 登录走 Direct Sign-In(授权码 + PKCE);issuer 元数据需支持 ES256 与 PS384、refresh_token 授权与撤销端点。
  • 安全保存 refresh token,按需换取 access token;刷新时必须使用取得该 refresh token 的同一 DPoP 密钥。
  • 撤销语义有三种且互不替代(refresh token 撤销、会话停用、账号登出),排障见身份与授权。

验证顺序

阶段成功依据
发现域名与 issuer 双向校验通过
开始会话自签会话 JWT 被企业接受;被拒时收到明确的 invalid_session
登录Direct Sign-In 完成,用户批准的 scope 与令牌内容对应
执行一个带 access token 的只读请求返回预期结果
撤销撤销 refresh token 后无法再换取 access token;会话请求以未登录方式继续

先用只读任务走通全链,再扩展写操作。失败处理与重试边界见凭据、撤销与安全重试。

边界

  • 本站未运行任何真实登录、拒绝或撤销流程;上述顺序是静态核对官方 1.0 后的组织建议,不是实测结论。
  • 官方 kit/company 的 Validator 可做发现文档静态校验;通过静态校验不等于登录、会话或撤销可用。
最后更新于