SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场agents-pay

agents-pay

智能体与模型

查看项目

更新于 10-15 14:10

技能介绍

用途

agents-pay 用于让智能体在运行时为 x402 保护的内容付费：当智能体在任务中途遇到付费墙（HTTP 402），通过 AgentCore Payments 完成结算。它强调一个核心原则：支付决策在代码中、依据策略文件、在任何签名之前做出，模型所说的话以及抓取内容中的任何信息都不能授权支付或提高限额。对模型的指令不是访问控制，控制必须在授权支付的位置由代码强制执行。

主要能力

该技能将支付分为两条互不接触的路径：

  • 管理路径（仅人类，在终端操作，持有凭据）：通过 agentcore CLI 添加 payment-manager / payment-connector，用 agents_pay_admin.py 执行 init-config、create-instrument、new-session 等操作，创建受预算约束的会话。
  • 运行时路径（仅消费，不能创建）：智能体可调用 x402_fetch(url) 付费并获取内容、payment_session_status() 只读检查会话是否仍可用、prepare_browser_payment(url) 为浏览器导航获取不透明句柄。

工具清单中，模型可见的工具包括 x402_fetch、payment_session_status、prepare_browser_payment；attach_browser_payment 由可信胶水代码调用，不暴露给模型；new-session 和基础设施配置由人类在 TTY 执行。

浏览器/仅头部支付采用句柄流程：prepare_browser_payment 返回句柄和脱敏回执（不含证明），attach_browser_payment 在导航时兑换句柄并返回真实头部。句柄一次性使用、90 秒过期、绑定单一来源和路径。

使用方式

前置条件：Python 3.9+、创建虚拟环境并安装 requirements.txt、agentcore 可用，且 bedrock_agentcore.payments 可导入。

步骤 1：由人类在 LLM 循环之外配置支付资源（npm install -g @aws/agentcore；agentcore add payment-manager；agentcore add payment-connector；agentcore deploy），均使用交互式向导，不加标志。

步骤 2：由人类编写支付策略，例如： python3 scripts/agents_pay_admin.py init-config --max-per-payment-usd 0.05 --network eip155:84532 --recipient 0xMerchantWalletAddress 策略写入 ~/.agents-pay/config.json（权限 0600），包含 max_per_payment_usd、allowed_networks、allowed_assets、allowed_recipients、allow_any_recipient、allowed_origins、allowed_schemes 等键。缺少收款方模式即拒绝，两种收款方模式互斥，没有隐式通配符。

步骤 3：由人类创建按用户的支付工具：python3 scripts/agents_pay_admin.py create-instrument --email you@example.com

步骤 4：由人类批准受预算约束的会话：python3 scripts/agents_pay_admin.py new-session --budget 1.00 --expiry-minutes 60，需要在 TTY 输入 approve，没有 --yes 标志。

步骤 5：由人类在本地完成运行时接线（导出 PAYMENT_MANAGER_ARN、PAYMENT_INSTRUMENT_ID、PAYMENT_SESSION_ID、PAYMENT_USER_ID、AWS_REGION，并运行 preflight）。

智能体调用方式为命令行：python3 scripts/x402_fetch_cli.py https://merchant.example/paid，输出 JSON 或 {"refused": true, "reason": "..."}。支持 --status、--browser-handle URL、--method GET|HEAD、--purchase-id ID 等标志。退出码：0 已支付或无需支付，2 拒绝或未配置，1 意外失败。

适用场景

  • 智能体遇到 x402 付费墙（HTTP 402）需要获取内容。
  • 需要对智能体支付设置硬性支出上限（每次支付和每会话）。
  • 支付被拒绝，需要知道是哪条规则拒绝的。

限制

  • 不适用于构建具备支付能力的智能体（应使用 agents-build 及其 references/payments.md）。
  • 不适用于非付费外部 API 或工具（agents-connect）、入站鉴权（agents-harden）、项目创建或框架选择（agents-get-started）。
  • 钱包托管、法币出金或拒付处理不在范围内。
  • 安全模型依赖角色分离：智能体不得拥有 ManagementRole，不得运行管理 CLI。运行时角色必须排除 CreatePaymentSession 及所有 Create* 设置操作。
  • 管理 CLI 拒绝无头运行，new-session 需要人类在 TTY 输入 approve，且没有 --yes 标志。
  • 请求体类动词被拒绝，因为请求体可能让智能体向任意来源发送数据。
  • 测试网上链结算可能滞后，工具会重放同一授权最多 X402_MAX_PAYMENT_ATTEMPTS 次（默认 5，范围 1–10），令牌相同保证幂等，不会重复扣费。
  • 若使用框架原生支付集成（Strands、LangGraph、OpenAI Agents SDK 等），支付在框架内结算，本技能的策略门不在路径中。

文件

scripts/x402_policy.py（可信决策点）、scripts/x402_fetch_cli.py（命令行入口）、scripts/x402_fetch.py（加固抓取与结算）、scripts/agents_pay_admin.py（人类管理 CLI）、scripts/test_x402_policy.py（安全回归测试）、references/operator-guide.md、references/security-model.md、references/setup.md、references/troubleshooting.md。所有路径均在该技能目录内。