Agent API

机器客户端通过 API Catalog 和 OpenAPI 合同发现 EchoScan，并在开始 Agent Trial 购买前检查实时产品目录。

发现合同

• /.well-known/api-catalog 是 RFC 9727 API Catalog。
• /openapi.json 定义 Agent Trial、x402 Header、Schema、状态与正式 Report 合同。
• /llms.txt 是精简发现索引。
• Developer API 文档 说明 Browser Verifier 与 Report API v1。
• Production MCP 文档 说明人工 Workspace 的 OAuth 访问方式。

检查可购买状态

调用 GET https://api.echoscan.org/api/v1/agent/products。只有 agent_trial_lite_100 的 available 为 true 时才继续。响应中的产品快照是价格、资产、网络、有效期、Capability 与限制的正式事实。

Agent Trial Capability 为 fingerprint.submit、fingerprint.report.lite 和 agent.trial.status。

购买与激活

1. 为一个精确 HTTP 或 HTTPS Origin 创建 Intent，保留 intent_id、一次性 claim token、activate_url 与 status_url。
2. claim token 只保留在进程内，并且只作为 Bearer 凭证发送。
3. 请求 activate_url，读取 HTTP 402 PAYMENT-REQUIRED 挑战。
4. 对照锁定的产品快照和客户端预算策略验证挑战。
5. 使用 x402 v2 exact-payment 客户端携带 PAYMENT-SIGNATURE 重试激活请求。
6. 读取 PAYMENT-RESPONSE，并轮询 status_url 完成恢复和凭证领取。
7. 在交付窗口内，把返回的 Environment ID 与 Agent Trial API Key 分别保存到正确的浏览器和服务端边界。

GET /api/v1/agent/trial 使用 Agent Trial API Key 返回当前 Grant、购买时锁定的限制、用量、剩余额度、Capability 与过期时间。

凭证边界

Environment ID 可以公开，并由 Browser Verifier 在精确 Allowed Origin 使用。claim token、付款凭证与 Agent Trial API Key 都是秘密，不得进入 URL、提示词、浏览器持久存储、日志、Metric 或代码仓库。

Agent Trial API Key 按实时产品合同仅用于读取正式 Report 与 Agent Trial 状态。

解读 Report

客户应把 risk.status、risk.reasons 与 risk.findings 用作自身 allow、challenge、review 或 deny 策略的输入。Report 描述设备及访问风险证据，不证明个人的法定身份或意图。