已验证的支持代理

一个真实的 AI 代理，基于 Claude Agent SDK 构建，其访问后端的唯一路径是通过由 KYA-OS 保护的一个 MCP 服务器（KYA-OS 是开放的代理身份与委派标准，由 Vouched 捐赠给 Decentralized Identity Foundation）。

该场景复刻了 Vouched 自己反复使用的示例：一个支持代理可以自动处理 50 美元的退款，但任何更大的金额都需要人工批准。这里的一切都是真实的——真实的 Ed25519 签名加密身份、真实的 W3C 委派凭证、签发该凭证的真实同意 HTTP 服务器，以及真正发起工具调用的真实代理。唯一被模拟的是订单数据（见下文"为何使用模拟数据"）。

Agent calls issue_refund($30)  -> executes immediately, proof attached
Agent calls issue_refund($500) -> needs_authorization -> human approves at a real URL -> agent retries -> succeeds

为什么存在

AI 代理现在代表用户行事——查询订单状态、签发退款、转移资金——所使用的凭证使它们与所代表的人类难以区分。一个会话 cookie 将三个独立的问题压缩成一个无法区分的 HTTP 请求：谁在真正行事、依据谁的授权，以及这个具体操作是否在该授权范围之内。KYA-OS 分别回答这三个问题，因此低风险操作可以完全自动化（并附有操作者的签名证明），而高风险操作则要求代理证明自己被委派了该特定权限，通常还需要实时的人工同意步骤。

Vouched 自己的资料反复提到两个示例：一个支持/退款代理（"自动处理 50 美元的退款，但超过 5,000 美元需要批准"）和一个旅行预订代理（"查看航班状态，但未经批准不得预订航班"）。本仓库端到端地真实构建了第一个示例。

快速开始

npm install
npm run verify   # deterministic, no LLM needed - proves the whole lifecycle works
npm run agent    # the real thing - a live Claude Agent SDK agent driving 3 scripted turns

npm run verify 运行 src/verify-lifecycle.ts：一个自包含的脚本，在单个进程中演练生命周期的每个部分（证明生成、证明验证、一个必须失败的刻意篡改测试、完整的 needs_authorization -> real consent-server approval -> auto-applied retry -> success 循环），并为每项检查打印 PASS/FAIL。无需 API 密钥——它从不调用 LLM。

npm run agent 运行 src/agent.ts：一个基于 Claude Agent SDK 构建的真实代理，通过 stdio 连接到作为 MCP 工具源的 src/server.ts。它驱动三个提示——查询订单、签发 30 美元退款和签发 500 美元退款——并在第三个提示处有意停在授权链接上。这个停顿正是关键所在：代理永远不会看到证明或凭证，它只看到一个有时要求它将授权链接转达给人类的工具。需要设置 ANTHROPIC_API_KEY（或已认证的 claude CLI 会话）。

每个文件的内容

适配到你自己的 MCP 服务器

kya-tools.ts 中的模式可推广到任何 MCP 服务器：

1. 包装你服务器的身份：createKyaOsMiddleware({ identity, session: {...}, autoSession: true }, crypto)。

2. 对每个工具进行分类。只读或低风险：kyaos.wrapWithProof('tool_name', handler)——通过签名证明可追溯，不设门槛。高风险：kyaos.wrapWithDelegation('tool_name', { scopeId, consentUrl, formatChallenge }, kyaos.wrapWithProof('tool_name', handler))——在出示具有该 scope 的委派凭证之前保持阻塞。

3. 将 consentUrl 指向你自己的授权页面，或按原样复用 consent-server.ts 和 public/consent.html。

4. 将受委派门控的处理程序包装在 formatAsConsentLink() 中（参见 kya-tools.ts），这样已批准的凭证会在调用方重试时自动应用——任何人都无需手动粘贴凭证。

这已经是一份集成指南的形态，而不仅仅是这个演示能运行的证据。

为何使用模拟数据，而非真实集成

check_order_status 和 issue_refund 操作的是一个小的固定内存数据集——没有真实订单、没有真实客户、没有真实支付处理器，没有任何与 PCI/PII 相关的内容。这里要演示的是 KYA-OS 的身份与委派，而不是电子商务或支付工程，真实的集成只会增加数据处理和安全面，而对这一主题毫无益处。

本仓库刻意尚未覆盖的内容

• Checkpoint（Vouched 的代理流量检测层）——它确实有免费的自助注册，但那是个人账户创建步骤，不在本仓库范围内。

• 多种框架——Vouched 自己的文档列出了 Next.js、Express、Python、HTML 和直接 API。本仓库仅限 Node/TypeScript；鉴于 @kya-os/mcp 的 API 与传输无关，Express 变体是自然的下一步。

• IdentiClaw / KnowThat.ai——Vouched KYA 套件的另外两层；它们的公开文档仍然很单薄。

基于

@kya-os/mcp——KYA-OS 针对 Model Context Protocol 的 MIT 许可参考实现，由 Vouched 捐赠给 Decentralized Identity Foundation 的 Trusted AI Agents Working Group。