企业与个人 Agent 的接入路线
Poppy 官网本身是文档站,不是可以直接调用的协议服务。实现由企业与个人 Agent 各自提供,示例域名也不能当作真实生产端点。
企业侧
先确定支持的执行入口:agent.protocols 列出对话端点及其能力描述(正式 1.0 必填),apis 列出 OpenAPI 或 MCP 服务,web 决定是否提供浏览器会话端点。无 issuer 的企业也能提供完整的未登录服务;需要账号能力时选择独立 OAuth issuer,并让 protected resource metadata 与 issuer 元数据相互校验。
登录建议以 Direct Sign-In(授权码 + PKCE)为主,issuer 元数据要支持 ES256 与 PS384 两种签名、refresh_token 授权与撤销端点;可以要求 PAR。同意页需要列出将授予的全部 scope,即使用户此前已授权过其中一部分。
随后按规范校验每个请求的会话头:验证密钥委托链、会话 JWT 的方法与地址绑定,需要账号能力的请求再验 access token。tasks.endpoint 按 Session 提供排除任务、技能索引与反馈入口。
个人 Agent 侧
发布自己的 HTTPS 客户端元数据与公钥;安全获取企业发现文档并验证身份。每个用户在每家企业使用独立、稳定、不含个人信息的 User ID,不能直接使用邮箱或邮箱散列。
为自己生成随机会话 ID,用委托密钥为每个请求新签会话 JWT,并带上 Poppy-Version。确实需要账号能力时再让用户通过 Direct Sign-In 登录,安全保存 refresh token,按需换取 access token;刷新时必须使用取得该 refresh token 的同一 DPoP 密钥。
一个可验收闭环
| 阶段 | 成功依据 |
|---|---|
| 发现 | 域名与 issuer 双向校验通过 |
| 开始会话 | 自签会话 JWT 被企业接受;被拒绝时收到明确的 invalid_session |
| 登录 | Direct Sign-In 完成,用户批准的 scope 与令牌内容对应 |
| 执行 | 一个带 access token 的只读请求返回预期结果 |
| 撤销 | 撤销 refresh token 后无法再换取 access token;会话请求以未登录方式继续 |
先选择只读任务验证整条链,再扩展写操作、浏览器加入与对话。具体请求字段、算法与错误码请使用1.0 规范源文件,不要从概念流程推导消息格式。