尧图网站建设 
在实际 AI 应用开发中智能体Agent与外部服务交互时一个核心且棘手的挑战是支付与计费。无论是调用大模型 API、使用云服务还是进行链上交易都需要一个安全、可靠且可编程的支付凭证管理机制。手动处理 API 密钥、管理订阅状态或处理小额支付不仅繁琐更带来了密钥泄露、权限失控和财务对账困难等风险。Cloudflare 近期推出的 Wallet 服务正是瞄准了这一痛点它并非面向普通用户的消费钱包而是一个专为 AI 智能体设计的、可通过代码完全控制的可编程钱包基础设施。本文将深入解析 Cloudflare Wallet 的核心概念、工作机制并通过一个完整的示例项目演示如何为一个 AI 翻译智能体配置和使用 Wallet使其能够自动、安全地调用付费翻译 API。我们将从环境准备开始逐步完成依赖配置、钱包创建、资金充值、API 调用扣费以及状态查询的全流程。文章最后会详细讨论在生产环境中部署此类方案时的安全策略、错误处理、监控和成本控制等最佳实践。无论你是正在构建 AI 应用的开发者还是对自动化运维和微支付架构感兴趣的技术人员都能通过本文掌握一套可落地的、服务级别的支付自动化方案。1. 理解 Cloudflare Wallet为机器设计的支付层在深入代码之前必须厘清 Cloudflare Wallet 的定位。它不是一个存储加密货币的 Web3 钱包也不是一个面向终端用户的支付应用。其核心设计目标是成为云原生应用和自动化程序如 AI 智能体的一个“财务执行单元”。1.1 核心设计理念可编程性与隔离性传统的支付集成无论是 Stripe、支付宝还是微信支付其 API 主要服务于由人类发起的交易流程创建订单、支付、回调。而 AI 智能体的行为是持续、自动且可能高频的例如一个客服机器人可能需要根据对话内容动态决定是否调用一次昂贵的图像识别 API。Cloudflare Wallet 将支付能力抽象为一段可编程的逻辑以代码为中心钱包的创建、充值、扣款、查询全部通过 RESTful API 或 SDK 完成完美融入 CI/CD 和自动化工作流。资源隔离每个智能体、每个项目、甚至每个环境开发、测试、生产都可以拥有独立且隔离的钱包。这实现了财务上的“微服务化”一个智能体的预算超支或密钥泄露不会波及其他服务。策略驱动扣费策略可以通过代码动态定义。例如可以为翻译 API 设置单次调用成本上限或为测试环境钱包设置每日消费限额。1.2 关键组件与工作流程一个典型的 Cloudflare Wallet 集成涉及以下组件和流程钱包Wallet核心实体拥有一个唯一的标识符ID和余额。它隶属于一个 Cloudflare 账户。API 令牌API Token用于认证对 Wallet API 的调用。需要谨慎保管并遵循最小权限原则。资金源Funding Source为钱包充值的渠道通常绑定 Cloudflare 账户的支付方式如信用卡。交易Transaction从钱包中扣除资金的操作。每次 AI 智能体调用外部付费服务时你的后端代码会代表该智能体发起一笔交易。服务集成Service IntegrationCloudflare 可能提供与部分合作伙伴服务如某些 AI 模型提供商的直接计费集成简化流程。但通用模式仍是“先调用服务后通过 Wallet API 扣款”。其工作流可以概括为开发者通过 Cloudflare 仪表板或 API 创建钱包并充值 - AI 智能体执行任务需调用付费 API - 你的后端服务在调用付费 API 前后调用 Wallet API 扣除相应费用 - 所有交易记录可查用于对账和成本分析。1.3 与常见 API 密钥管理模式的对比为了更清晰地理解其价值我们将其与两种常见模式进行对比管理模式实现方式优点缺点适用场景全局共享密钥将一个 API 密钥硬编码在环境变量或配置文件中所有服务共用。配置简单。密钥泄露风险极高无法区分不同服务或环境的用量难以进行细粒度成本控制。快速原型验证内部非关键服务。密钥分发服务构建一个内部服务来动态分发和轮换密钥。提升了密钥安全性可以审计使用记录。架构复杂仍需一个“根密钥”来保护分发服务本身扣费与调用在逻辑上分离对账复杂。中大型企业对安全有较高要求。Cloudflare Wallet每个智能体拥有独立钱包通过 Wallet API 进行支付授权和扣费。天然隔离泄露影响范围小扣费即日志财务可追溯支持编程控制预算和策略。引入新的依赖Cloudflare需要设计“调用-扣费”的原子性或补偿逻辑。AI 智能体、微服务、Serverless 函数等需要自动化、细粒度计费的场景。通过对比可以看出Wallet 模式在安全性、可审计性和自动化方面提供了更优的解决方案特别适合云原生和 AI 驱动的应用架构。2. 环境准备与项目初始化我们将构建一个简单的 AI 翻译智能体示例。该智能体接收一段中文文本调用一个模拟的付费翻译 API我们将用本地服务模拟将其译为英文并使用 Cloudflare Wallet 支付本次翻译费用。2.1 前置条件与工具确保你拥有以下环境Cloudflare 账户需要一个已注册并验证的 Cloudflare 账户。如果没有请前往 Cloudflare 官网注册。Node.js 环境本文示例使用 Node.js (版本 18 或更高) 和 JavaScript。确保已安装 Node.js 和 npm。代码编辑器如 VS Code。命令行工具如 Terminal (macOS/Linux) 或 PowerShell/CMD (Windows)。2.2 创建 Cloudflare API 令牌Wallet API 的调用需要认证。我们将创建一个具有适当权限的 API 令牌。登录 Cloudflare 仪表板 。点击右上角头像选择 “My Profile”。在左侧菜单栏选择 “API Tokens”。点击 “Create Token”。为了安全我们选择自定义模板。在Permissions部分为 Wallet 服务添加权限。搜索并选择Account Wallet EditAccount Wallet Read注意权限名称可能随产品更新而变化请以仪表板实际选项为准。在Account Resources部分选择你的目标账户。点击 “Continue to summary”确认权限无误后为令牌命名如AI-Agent-Wallet-Manager然后点击 “Create Token”。至关重要立即复制生成的令牌字符串并妥善保存。它只显示一次。将令牌设置为环境变量避免硬编码在代码中# 在终端中执行 (Linux/macOS) export CLOUDFLARE_API_TOKEN你的_API_令牌_字符串 # 在终端中执行 (Windows PowerShell) $env:CLOUDFLARE_API_TOKEN你的_API_令牌_字符串2.3 初始化 Node.js 项目创建一个新的项目目录并初始化mkdir ai-translator-agent cd ai-translator-agent npm init -y安装必要的依赖库。我们将使用axios进行 HTTP 请求dotenv管理环境变量express搭建一个简单的模拟服务器。npm install axios dotenv express创建项目核心文件touch .env .env.example index.js wallet-service.js mock-translation-api.js项目结构如下ai-translator-agent/ ├── .env # 存储敏感信息API令牌、账户ID等 ├── .env.example # 环境变量示例模板 ├── package.json ├── index.js # 主应用入口模拟AI智能体工作流 ├── wallet-service.js # 封装所有Cloudflare Wallet相关操作 └── mock-translation-api.js # 模拟一个付费翻译API服务3. 构建可编程钱包服务模块我们将首先实现wallet-service.js这是一个封装了 Wallet API 调用的服务类。这样在主逻辑中我们可以清晰地调用walletService.debit(amount, description)来完成扣费。3.1 配置环境变量在.env文件中填入你的敏感信息在.env.example中只保留键名作为模板# .env CLOUDFLARE_ACCOUNT_IDyour_cloudflare_account_id_here CLOUDFLARE_API_TOKENyour_api_token_here WALLET_NAMEai_translator_agent_prod # 钱包名称如何获取CLOUDFLARE_ACCOUNT_ID登录 Cloudflare 仪表板在主页或侧边栏底部可以看到你的账户 ID。3.2 实现 WalletService 类wallet-service.js的完整代码如下我们分段解释// wallet-service.js require(dotenv).config(); // 加载 .env 文件 const axios require(axios); class WalletService { constructor() { // 从环境变量读取配置 this.accountId process.env.CLOUDFLARE_ACCOUNT_ID; this.apiToken process.env.CLOUDFLARE_API_TOKEN; this.walletName process.env.WALLET_NAME; // 验证必要配置是否存在 if (!this.accountId || !this.apiToken) { throw new Error(Missing required environment variables: CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN); } // 配置 axios 实例统一设置认证头和基础URL this.client axios.create({ baseURL: https://api.cloudflare.com/client/v4/accounts/${this.accountId}/wallet, headers: { Authorization: Bearer ${this.apiToken}, Content-Type: application/json, }, }); } /** * 获取或创建钱包。如果指定名称的钱包不存在则创建它。 * returns {PromiseObject} 钱包对象包含 id, name, balance 等信息。 */ async getOrCreateWallet() { try { // 首先尝试列出所有钱包并查找指定名称的钱包 const listResponse await this.client.get(/wallets); const wallets listResponse.data.result || []; const existingWallet wallets.find(w w.name this.walletName); if (existingWallet) { console.log(Wallet ${this.walletName} already exists. ID: ${existingWallet.id}); return existingWallet; } // 如果不存在则创建新钱包 console.log(Creating new wallet: ${this.walletName}); const createResponse await this.client.post(/wallets, { name: this.walletName, // 可以在此处设置初始元数据如关联的项目ID、环境等 metadata: { project: ai-translator, environment: production, createdBy: wallet-service } }); return createResponse.data.result; } catch (error) { console.error(Failed to get or create wallet:, error.response?.data || error.message); throw error; } } /** * 从钱包中扣除指定金额。 * param {number} amount - 扣除的金额单位美分/分取决于Cloudflare的货币单位。 * param {string} description - 交易描述用于对账。 * param {string} [walletId] - 钱包ID。如果未提供将使用 getOrCreateWallet 获取。 * returns {PromiseObject} 交易结果对象。 */ async debit(amount, description, walletId null) { try { let targetWalletId walletId; if (!targetWalletId) { const wallet await this.getOrCreateWallet(); targetWalletId wallet.id; } if (!targetWalletId) { throw new Error(Wallet ID is required to perform a debit transaction.); } const response await this.client.post(/wallets/${targetWalletId}/debit, { amount: { // 假设金额单位为美分 (USD cents)。请根据Cloudflare API文档确认。 currency: USD, value: amount, // 例如100 代表 1.00 USD }, description: description, // 可以添加更多元数据如本次调用的请求ID、用户ID等便于追踪 metadata: { service: mock-translation-api, timestamp: new Date().toISOString(), } }); console.log(Debit successful. Transaction ID: ${response.data.result?.id}. New balance (if provided): ${response.data.result?.balance}); return response.data.result; } catch (error) { // 这里需要特别处理余额不足等错误 const errorData error.response?.data; console.error(Debit transaction failed:, errorData || error.message); // 示例根据错误码进行特定处理 if (errorData errorData.errors errorData.errors.some(e e.code 10009)) { // 假设10009是余额不足错误码 throw new Error(INSUFFICIENT_FUNDS); } // 抛出其他错误 throw new Error(WALLET_ERROR: ${errorData?.errors?.[0]?.message || error.message}); } } /** * 查询钱包余额和详情。 * param {string} [walletId] - 钱包ID。 * returns {PromiseObject} 钱包详情对象。 */ async getWalletDetails(walletId null) { try { let targetWalletId walletId; if (!targetWalletId) { const wallet await this.getOrCreateWallet(); targetWalletId wallet.id; } const response await this.client.get(/wallets/${targetWalletId}); return response.data.result; } catch (error) { console.error(Failed to get wallet details:, error.response?.data || error.message); throw error; } } } module.exports WalletService;关键代码解释构造函数与配置类初始化时从环境变量加载关键配置并创建一个预配置的axios实例。这保证了所有请求都带有正确的认证头和基础 URL。getOrCreateWallet方法这是幂等性设计的体现。先尝试查找现有钱包如果不存在则创建。这确保了脚本可以安全地多次运行。创建钱包时可以附加metadata这对于后续按项目或环境筛选钱包非常有用。debit方法这是核心扣费方法。金额表示示例中假设金额以美分USD cents为单位。在实际使用前务必查阅最新的 Cloudflare Wallet API 文档确认货币单位和精度。错误处理特别捕获了 HTTP 错误并尝试解析错误码。例如我们假设错误码10009代表余额不足INSUFFICIENT_FUNDS并在上层逻辑中可以根据此特定错误类型采取不同策略如暂停服务、发送告警。元数据Metadata在交易描述之外附加了metadata字段。这是可编程钱包的强大之处你可以将任何有助于追踪的上下文信息如请求 ID、会话 ID、资源 ID存入便于后期进行精细的财务分析和审计。getWalletDetails方法用于查询钱包当前状态主要是余额。4. 模拟付费翻译 API 与智能体工作流接下来我们构建一个模拟的付费翻译 API 服务以及一个使用 Wallet 来支付调用费用的 AI 智能体主逻辑。4.1 创建模拟付费翻译 APImock-translation-api.js模拟了一个按次收费的外部翻译服务。// mock-translation-api.js const express require(express); const app express(); app.use(express.json()); // 模拟的翻译函数实际项目中会调用如 Google Translate、DeepL 等 API function translateText(text) { // 这里是一个简单的模拟 const translations { 你好世界: Hello, World, 人工智能: Artificial Intelligence, 可编程钱包: Programmable Wallet, 今天天气很好: The weather is nice today }; return translations[text] || [Translated]: ${text}; } // 定价每翻译一个字符按中文字符算收费 0.1 美分 (0.001 USD) // 最低消费 10 美分 (0.10 USD) function calculateCost(text) { const charCount text.length; const costInCents Math.max(10, Math.ceil(charCount * 0.1)); // 单位美分 return costInCents; } // 翻译 API 端点 app.post(/api/v1/translate, (req, res) { const { text, authToken } req.body; // 实际场景中authToken 可能是你的付费 API Key if (!text) { return res.status(400).json({ error: Missing text to translate }); } // 模拟认证在实际集成中这里会验证 authToken if (!authToken) { return res.status(401).json({ error: Invalid or missing authentication token }); } console.log([Translation API] Received request to translate: ${text.substring(0, 50)}...); const translation translateText(text); const costInCents calculateCost(text); // 模拟处理延迟 setTimeout(() { res.json({ success: true, original: text, translated: translation, cost: { currency: USD, value: costInCents, // 返回成本单位美分 formatted: $${(costInCents / 100).toFixed(2)} }, requestId: req_${Date.now()} }); }, 100); // 100ms 延迟 }); // 健康检查端点 app.get(/health, (req, res) { res.json({ status: ok, service: mock-translation-api }); }); const PORT process.env.MOCK_API_PORT || 3001; app.listen(PORT, () { console.log(Mock Translation API server running on http://localhost:${PORT}); });这个模拟 API 有两个关键点成本计算它根据输入文本长度计算本次调用的成本以美分为单位并在响应中返回。这模拟了真实付费 API 的计费模式。认证它期望一个authToken。在真实场景中这可能是你从服务商处获得的 API 密钥。在我们的智能体工作流中我们将用 Wallet 支付来代替直接传递这个密钥或者将其与 Wallet 支付关联。4.2 实现 AI 翻译智能体主逻辑index.js文件将整合 Wallet 服务和翻译 API形成完整的智能体工作流。// index.js require(dotenv).config(); const axios require(axios); const WalletService require(./wallet-service); // 初始化服务 const walletService new WalletService(); const TRANSLATION_API_URL http://localhost:3001/api/v1/translate; // 注意这里我们仍然需要一个 token 来调用模拟API但在 Wallet 集成理想状态下 // 这个 token 可能是一个通用网关令牌其背后关联着你的 Wallet 账户。 const MOCK_API_AUTH_TOKEN dummy_token_for_mock_api; async function translateWithAI(text) { console.log(\n AI Translator Agent Starting ); console.log(Input: ${text}); // 步骤 1: 查询钱包余额确保有足够资金可选但推荐 try { const walletDetails await walletService.getWalletDetails(); console.log(Current wallet balance: ${walletDetails.balance?.value || N/A} ${walletDetails.balance?.currency || USD}); // 这里可以添加逻辑如果余额低于阈值发送告警或暂停服务。 } catch (error) { console.warn(Could not check wallet balance: ${error.message}. Proceeding anyway...); } // 步骤 2: 调用付费翻译 API let apiResponse; try { console.log(Calling translation API...); apiResponse await axios.post(TRANSLATION_API_URL, { text: text, authToken: MOCK_API_AUTH_TOKEN, }); console.log(Translation API call successful. Cost: ${apiResponse.data.cost.formatted}); } catch (apiError) { console.error(Translation API call failed:, apiError.response?.data || apiError.message); // 如果 API 调用失败则不应该扣费 throw new Error(TRANSLATION_API_FAILED: ${apiError.message}); } const costInCents apiResponse.data.cost.value; const requestId apiResponse.data.requestId; // 步骤 3: 从 Wallet 中扣除本次 API 调用费用 try { console.log(Attempting to debit ${costInCents} cents from wallet...); const debitResult await walletService.debit( costInCents, Translation service charge for: ${text.substring(0, 30)}..., // 描述 // 可以传递 walletId如果为空则使用环境变量中名称对应的钱包 ); console.log(Payment successful. Transaction ID: ${debitResult.id}); } catch (debitError) { // 特别处理余额不足错误 if (debitError.message INSUFFICIENT_FUNDS) { console.error(PAYMENT FAILED: Insufficient funds in wallet. Service suspended.); // 在实际场景中这里应该触发告警、暂停任务队列、通知管理员等。 // 由于支付失败可以考虑是否要回滚或标记此次翻译为“未付费”。 throw new Error(INSUFFICIENT_FUNDS); } else { console.error(PAYMENT FAILED due to wallet error: ${debitError.message}); // 其他 Wallet 错误如网络问题、权限问题。这是一个关键故障。 // 需要决定是否重试扣款或者将此次交易标记为“待处理”由后台对账系统处理。 throw new Error(WALLET_DEBIT_FAILED: ${debitError.message}); } } // 步骤 4: 返回最终结果 console.log( AI Translator Agent Finished \n); return { success: true, translation: apiResponse.data.translated, financial: { cost: apiResponse.data.cost, transactionId: debitResult.id, // 假设 debitResult 在上一步已定义 }, requestId: requestId, }; } // 主执行函数 async function main() { try { // 示例翻译几句话 const textsToTranslate [ 你好世界, 人工智能和可编程钱包是云原生的重要部分, 今天天气很好 ]; for (const text of textsToTranslate) { try { const result await translateWithAI(text); console.log(Translated: ${text} - ${result.translation}); console.log(---); } catch (agentError) { console.error(Agent failed for text ${text}:, agentError.message); // 根据错误类型决定是否继续处理下一个任务 if (agentError.message INSUFFICIENT_FUNDS) { console.log(Stopping further processing due to insufficient funds.); break; } } } // 最终检查钱包余额 const finalBalance await walletService.getWalletDetails(); console.log(\nFinal wallet balance: ${finalBalance.balance?.value || N/A} ${finalBalance.balance?.currency}); } catch (error) { console.error(Unexpected error in main process:, error); } } // 启动模拟 API 服务器和智能体 if (require.main module) { // 你可以选择在一个进程中同时启动 API 和 Agent或者分开运行。 // 这里我们假设先启动 mock-translation-api.js (node mock-translation-api.js) // 然后在另一个终端运行 node index.js console.log(Please ensure the Mock Translation API is running on port 3001.); console.log(Run: node mock-translation-api.js); console.log(Then in another terminal, run: node index.js); // 为了演示我们直接调用 main但需要 API 服务已启动。 // 在实际运行前请先启动模拟API。 // main(); } module.exports { translateWithAI };工作流详解余额预检可选但推荐智能体在开始工作前先查询钱包余额。这可以作为一道简单的防护避免在明显资金不足时仍发起大量 API 调用产生大量失败的支付请求。调用外部服务智能体调用模拟的付费翻译 API。注意此时服务调用已经发生成本已经产生在真实场景中服务提供商会在你调用时计费无论你后续支付是否成功。因此步骤 3 的支付必须非常可靠。支付扣款收到翻译结果和费用后智能体立即调用walletService.debit()进行支付。这是整个流程最关键的环节需要处理INSUFFICIENT_FUNDS等错误。错误处理与补偿API 调用失败如果翻译 API 本身失败则不应扣款。代码在catch块中直接抛出错误跳过扣费步骤。支付失败余额不足这是业务逻辑错误。代码捕获特定的INSUFFICIENT_FUNDS错误并可能暂停整个智能体的后续任务同时触发告警。这里存在一个业务问题服务已调用但支付失败。在生产环境中你需要与 API 提供商约定如何处理这类“后付费”失败的情况例如是否有赊账额度、是否允许事后补缴、还是直接停止服务。支付失败其他原因如网络超时、Wallet 服务异常等。这类错误需要重试机制和事后对账系统来处理确保最终一致性。5. 运行验证与结果分析现在让我们运行整个系统观察 Wallet 如何工作。5.1 启动服务并执行首先在一个终端启动模拟翻译 API 服务器node mock-translation-api.js你应该看到输出Mock Translation API server running on http://localhost:3001然后在另一个终端运行 AI 智能体主程序node index.js为了演示我们需要修改index.js的最后部分直接调用main()函数。将最后几行注释掉改为// 注释掉原来的提示直接运行 main确保你已理解步骤 // if (require.main module) { // console.log(Please ensure the Mock Translation API is running on port 3001.); // console.log(Run: node mock-translation-api.js); // console.log(Then in another terminal, run: node index.js); // // main(); // } // 改为 if (require.main module) { main(); }再次运行node index.js。观察控制台输出它应该类似于Please ensure the Mock Translation API is running on port 3001. Run: node mock-translation-api.js Then in another terminal, run: node index.js因为我们直接运行了main()所以智能体会开始工作。输出会显示创建钱包、查询余额、调用 API、扣款等一系列操作。5.2 验证 Wallet 状态智能体运行后你可以通过 Cloudflare 仪表板或调用我们写的getWalletDetails方法来验证交易是否成功。在index.js的main()函数末尾我们已经添加了查询最终余额的代码。你可以在控制台看到类似输出Final wallet balance: 8500 USD假设初始有 10000 美分三次翻译扣除了 1500 美分。更详细的信息需要登录 Cloudflare 仪表板在 Wallet 服务相关页面查看交易流水里面会记录每一笔debit操作的描述、金额、时间戳和元数据。5.3 模拟错误场景为了充分测试我们可以模拟几种错误余额不足在.env中指定一个已存在但余额很少的钱包名称或者通过仪表板手动将钱包余额调低。再次运行智能体观察是否会正确捕获INSUFFICIENT_FUNDS错误并停止服务。API 令牌错误修改.env中的CLOUDFLARE_API_TOKEN为一个错误的值。运行程序你会看到 Wallet API 调用返回403或401错误。模拟 API 宕机关闭mock-translation-api.js服务然后运行智能体。观察是否会因TRANSLATION_API_FAILED错误而跳过扣款。通过这些测试你可以验证智能体工作流的健壮性。6. 生产环境部署的关键考量与最佳实践将基于 Wallet 的支付集成用于生产环境远不止让代码跑通那么简单。以下是必须考虑的深层问题和实践建议。6.1 事务一致性与补偿机制在我们的流程中“调用服务”和“支付扣款”是两个独立的操作这带来了数据一致性问题。如果扣款失败服务已经被消费了。这在业务上可能无法接受。解决方案预授权模式推荐在调用服务前先向 Wallet 发起一个“预授权”或“冻结”一定金额的操作。服务调用成功后再完成扣款如果失败则释放冻结的金额。这需要 Wallet API 或你的业务层支持此类两阶段操作。事后对账与补单接受最终一致性。记录所有服务调用和支付尝试。部署一个后台对账作业定期比对服务提供商的账单和你的 Wallet 交易记录找出差异并进行人工或自动处理补扣款或退款。服务提供商集成最理想的情况是像 Cloudflare 这样的平台能与主要的 AI 服务商如 OpenAI、Anthropic达成直接计费集成。你授权 Cloudflare Wallet 作为支付方式服务商直接从中扣费实现原子操作。请关注 Cloudflare 的官方集成列表。6.2 安全与权限管理API 令牌管理用于调用 Wallet API 的令牌权限必须严格控制。遵循最小权限原则仅授予Read和Edit权限并且仅限于必要的账户。绝对不要将令牌提交到代码仓库。使用安全的 Secret 管理服务如 HashiCorp Vault、AWS Secrets Manager、Azure Key Vault 或云厂商提供的类似服务。钱包隔离策略按环境隔离开发、测试、生产环境使用完全不同的钱包。按业务/团队隔离不同项目或团队使用独立钱包便于成本分摊和预算控制。按智能体实例隔离对于非常重要的或消耗资源差异大的智能体可以考虑单独的钱包实现成本精准追踪和故障隔离。监控与告警余额监控设置监控当钱包余额低于阈值时如 10 美元触发告警邮件、Slack、短信等。异常交易监控监控失败的扣款交易非余额不足原因这可能意味着集成代码存在 bug 或 Wallet 服务异常。消费速率监控如果某个智能体的消费速度异常飙升可能意味着程序出现循环调用 bug 或遭到滥用。6.3 成本控制与优化预算与限额在代码逻辑或调度策略中实现软性预算。例如智能体每日运行前检查本月累计消费如果已超预算则跳过或降级到免费服务。服务降级当 Wallet 支付失败或余额不足时设计降级策略。例如从付费的高质量翻译 API 降级到免费的或低质量的翻译服务并记录日志供后续分析。缓存与批处理对于可重复的、非实时的请求考虑使用缓存避免重复调用付费 API。对于小的、可批量处理的任务考虑攒一批后再统一调用 API 和支付可能享受更优惠的批量费率并减少交易次数。6.4 日志、审计与可观测性所有与 Wallet 相关的操作都必须记录详尽的日志包括钱包 ID、名称交易金额、描述、状态成功/失败关联的业务请求 ID如翻译请求 ID错误码和错误信息操作时间戳这些日志应集中收集如 ELK Stack、Loki 等并用于生成财务报告、审计追踪和故障排查。7. 常见问题排查清单在实际集成和使用 Cloudflare Wallet 时你可能会遇到以下问题。这里提供排查思路。问题现象可能原因检查步骤解决方案API 调用返回 403 Forbidden1. API 令牌无效或已撤销。2. API 令牌权限不足。3. 账户 ID 错误。1. 在 Cloudflare 仪表板 “API Tokens” 页面验证令牌是否存在且状态为 “Active”。2. 检查令牌权限是否包含 Wallet 的 Read 和 Edit。3. 核对.env中的CLOUDFLARE_ACCOUNT_ID是否正确。1. 重新生成 API 令牌并更新环境变量。2. 编辑令牌添加必要权限。3. 修正账户 ID。创建钱包或扣款时返回 400 Bad Request1. 请求体 JSON 格式错误或缺少必填字段。2. 金额格式不正确如负数、非数字。3. 货币代码不支持。1. 使用console.log或工具查看发送的请求体。2. 对照官方 API 文档检查字段名和类型。3. 确认amount.currency字段值是否为文档支持的类型如 “USD”。1. 修正 JSON 结构。2. 确保金额为整数。3. 使用正确的货币代码。debit操作失败提示余额不足1. 钱包内确实没有足够余额。2. 扣款金额计算有误远超实际所需。1. 调用getWalletDetails查询当前余额。2. 检查计算服务成本的逻辑是否正确。1. 通过 Cloudflare 仪表板为钱包充值。2. 修复成本计算逻辑并考虑增加余额不足的预检和告警。交易成功但服务未调用/服务调用成功但扣款失败1. 工作流非原子性两个操作之间出现程序崩溃或网络分区。2. 错误处理逻辑不完善未能正确处理部分失败。1. 检查应用日志确认两个操作的顺序和结果。2. 审查try-catch块确保一个操作失败后另一个操作有相应的补偿或回滚机制。1. 引入更健壮的事务模式如预授权、Saga 模式。2. 实现后台对账作业修复不一致状态。无法找到指定名称的钱包1. 钱包名称拼写错误或大小写不一致。2. 钱包存在于另一个 Cloudflare 账户下。3.getOrCreateWallet逻辑中列表查询未返回预期钱包。1. 核对.env中的WALLET_NAME。2. 确认当前使用的 API 令牌和账户 ID 是否正确。3. 在getOrCreateWallet方法中添加调试日志打印查询到的所有钱包列表。1. 统一名称大小写。2. 使用正确的账户和令牌。3. 检查 API 响应格式确保正确解析result字段。网络超时或连接中断1. 本地或服务器网络不稳定。2. Cloudflare API 服务临时故障。3. 客户端请求超时设置过短。1. 使用curl或Postman测试 API 连通性。2. 查看 Cloudflare Status Page 。3. 在axios配置中增加timeout参数。1. 检查网络配置。2. 等待服务恢复或联系支持。3. 增加超时时间并实现重试机制使用指数退避算法。8. 扩展方向与进阶思考掌握了基础集成后你可以从以下几个方向深化对可编程钱包的应用多钱包与路由策略为不同成本中心、不同优先级的任务配置不同钱包。智能体可以根据任务类型、用户等级等维度动态选择从哪个钱包扣款。与工作流引擎集成将 Wallet 支付节点嵌入到 Apache Airflow、Prefect 或 Temporal 等工作流引擎中。将“支付”作为一个明确的、可重试、可补偿的步骤来管理。实现预算编排开发一个预算管理服务它定期如每月初为各个钱包分配预算并监控消费速率。当某个钱包消费过快时可以动态调整其预算或通知相关负责人。探索更广泛的“可编程金融”场景Cloudflare Wallet 的理念可以延伸到其他自动化财务场景例如自动为测试环境资源充值、根据流量自动购买 CDN 带宽包、在 Serverless 函数中支付使用第三方 API 的费用等。思考如何将财务逻辑作为代码FinOps as Code进行管理。Cloudflare Wallet 为 AI 智能体和自动化系统引入了一个关键的“财务执行层”。它解决了密钥管理混乱、成本归属不清和支付流程无法自动化的问题。成功落地的关键在于像管理其他基础设施如数据库、缓存一样对可编程钱包进行设计考虑其可用性、安全性、监控和容错。通过本文的示例和讨论希望你能够构建出既智能又经济可控的 AI 应用系统。 Cloudflare Wallet：为AI智能体构建可编程支付与计费自动化方案
在实际 AI 应用开发中智能体Agent与外部服务交互时一个核心且棘手的挑战是支付与计费。无论是调用大模型 API、使用云服务还是进行链上交易都需要一个安全、可靠且可编程的支付凭证管理机制。手动处理 API 密钥、管理订阅状态或处理小额支付不仅繁琐更带来了密钥泄露、权限失控和财务对账困难等风险。Cloudflare 近期推出的 Wallet 服务正是瞄准了这一痛点它并非面向普通用户的消费钱包而是一个专为 AI 智能体设计的、可通过代码完全控制的可编程钱包基础设施。本文将深入解析 Cloudflare Wallet 的核心概念、工作机制并通过一个完整的示例项目演示如何为一个 AI 翻译智能体配置和使用 Wallet使其能够自动、安全地调用付费翻译 API。我们将从环境准备开始逐步完成依赖配置、钱包创建、资金充值、API 调用扣费以及状态查询的全流程。文章最后会详细讨论在生产环境中部署此类方案时的安全策略、错误处理、监控和成本控制等最佳实践。无论你是正在构建 AI 应用的开发者还是对自动化运维和微支付架构感兴趣的技术人员都能通过本文掌握一套可落地的、服务级别的支付自动化方案。1. 理解 Cloudflare Wallet为机器设计的支付层在深入代码之前必须厘清 Cloudflare Wallet 的定位。它不是一个存储加密货币的 Web3 钱包也不是一个面向终端用户的支付应用。其核心设计目标是成为云原生应用和自动化程序如 AI 智能体的一个“财务执行单元”。1.1 核心设计理念可编程性与隔离性传统的支付集成无论是 Stripe、支付宝还是微信支付其 API 主要服务于由人类发起的交易流程创建订单、支付、回调。而 AI 智能体的行为是持续、自动且可能高频的例如一个客服机器人可能需要根据对话内容动态决定是否调用一次昂贵的图像识别 API。Cloudflare Wallet 将支付能力抽象为一段可编程的逻辑以代码为中心钱包的创建、充值、扣款、查询全部通过 RESTful API 或 SDK 完成完美融入 CI/CD 和自动化工作流。资源隔离每个智能体、每个项目、甚至每个环境开发、测试、生产都可以拥有独立且隔离的钱包。这实现了财务上的“微服务化”一个智能体的预算超支或密钥泄露不会波及其他服务。策略驱动扣费策略可以通过代码动态定义。例如可以为翻译 API 设置单次调用成本上限或为测试环境钱包设置每日消费限额。1.2 关键组件与工作流程一个典型的 Cloudflare Wallet 集成涉及以下组件和流程钱包Wallet核心实体拥有一个唯一的标识符ID和余额。它隶属于一个 Cloudflare 账户。API 令牌API Token用于认证对 Wallet API 的调用。需要谨慎保管并遵循最小权限原则。资金源Funding Source为钱包充值的渠道通常绑定 Cloudflare 账户的支付方式如信用卡。交易Transaction从钱包中扣除资金的操作。每次 AI 智能体调用外部付费服务时你的后端代码会代表该智能体发起一笔交易。服务集成Service IntegrationCloudflare 可能提供与部分合作伙伴服务如某些 AI 模型提供商的直接计费集成简化流程。但通用模式仍是“先调用服务后通过 Wallet API 扣款”。其工作流可以概括为开发者通过 Cloudflare 仪表板或 API 创建钱包并充值 - AI 智能体执行任务需调用付费 API - 你的后端服务在调用付费 API 前后调用 Wallet API 扣除相应费用 - 所有交易记录可查用于对账和成本分析。1.3 与常见 API 密钥管理模式的对比为了更清晰地理解其价值我们将其与两种常见模式进行对比管理模式实现方式优点缺点适用场景全局共享密钥将一个 API 密钥硬编码在环境变量或配置文件中所有服务共用。配置简单。密钥泄露风险极高无法区分不同服务或环境的用量难以进行细粒度成本控制。快速原型验证内部非关键服务。密钥分发服务构建一个内部服务来动态分发和轮换密钥。提升了密钥安全性可以审计使用记录。架构复杂仍需一个“根密钥”来保护分发服务本身扣费与调用在逻辑上分离对账复杂。中大型企业对安全有较高要求。Cloudflare Wallet每个智能体拥有独立钱包通过 Wallet API 进行支付授权和扣费。天然隔离泄露影响范围小扣费即日志财务可追溯支持编程控制预算和策略。引入新的依赖Cloudflare需要设计“调用-扣费”的原子性或补偿逻辑。AI 智能体、微服务、Serverless 函数等需要自动化、细粒度计费的场景。通过对比可以看出Wallet 模式在安全性、可审计性和自动化方面提供了更优的解决方案特别适合云原生和 AI 驱动的应用架构。2. 环境准备与项目初始化我们将构建一个简单的 AI 翻译智能体示例。该智能体接收一段中文文本调用一个模拟的付费翻译 API我们将用本地服务模拟将其译为英文并使用 Cloudflare Wallet 支付本次翻译费用。2.1 前置条件与工具确保你拥有以下环境Cloudflare 账户需要一个已注册并验证的 Cloudflare 账户。如果没有请前往 Cloudflare 官网注册。Node.js 环境本文示例使用 Node.js (版本 18 或更高) 和 JavaScript。确保已安装 Node.js 和 npm。代码编辑器如 VS Code。命令行工具如 Terminal (macOS/Linux) 或 PowerShell/CMD (Windows)。2.2 创建 Cloudflare API 令牌Wallet API 的调用需要认证。我们将创建一个具有适当权限的 API 令牌。登录 Cloudflare 仪表板 。点击右上角头像选择 “My Profile”。在左侧菜单栏选择 “API Tokens”。点击 “Create Token”。为了安全我们选择自定义模板。在Permissions部分为 Wallet 服务添加权限。搜索并选择Account Wallet EditAccount Wallet Read注意权限名称可能随产品更新而变化请以仪表板实际选项为准。在Account Resources部分选择你的目标账户。点击 “Continue to summary”确认权限无误后为令牌命名如AI-Agent-Wallet-Manager然后点击 “Create Token”。至关重要立即复制生成的令牌字符串并妥善保存。它只显示一次。将令牌设置为环境变量避免硬编码在代码中# 在终端中执行 (Linux/macOS) export CLOUDFLARE_API_TOKEN你的_API_令牌_字符串 # 在终端中执行 (Windows PowerShell) $env:CLOUDFLARE_API_TOKEN你的_API_令牌_字符串2.3 初始化 Node.js 项目创建一个新的项目目录并初始化mkdir ai-translator-agent cd ai-translator-agent npm init -y安装必要的依赖库。我们将使用axios进行 HTTP 请求dotenv管理环境变量express搭建一个简单的模拟服务器。npm install axios dotenv express创建项目核心文件touch .env .env.example index.js wallet-service.js mock-translation-api.js项目结构如下ai-translator-agent/ ├── .env # 存储敏感信息API令牌、账户ID等 ├── .env.example # 环境变量示例模板 ├── package.json ├── index.js # 主应用入口模拟AI智能体工作流 ├── wallet-service.js # 封装所有Cloudflare Wallet相关操作 └── mock-translation-api.js # 模拟一个付费翻译API服务3. 构建可编程钱包服务模块我们将首先实现wallet-service.js这是一个封装了 Wallet API 调用的服务类。这样在主逻辑中我们可以清晰地调用walletService.debit(amount, description)来完成扣费。3.1 配置环境变量在.env文件中填入你的敏感信息在.env.example中只保留键名作为模板# .env CLOUDFLARE_ACCOUNT_IDyour_cloudflare_account_id_here CLOUDFLARE_API_TOKENyour_api_token_here WALLET_NAMEai_translator_agent_prod # 钱包名称如何获取CLOUDFLARE_ACCOUNT_ID登录 Cloudflare 仪表板在主页或侧边栏底部可以看到你的账户 ID。3.2 实现 WalletService 类wallet-service.js的完整代码如下我们分段解释// wallet-service.js require(dotenv).config(); // 加载 .env 文件 const axios require(axios); class WalletService { constructor() { // 从环境变量读取配置 this.accountId process.env.CLOUDFLARE_ACCOUNT_ID; this.apiToken process.env.CLOUDFLARE_API_TOKEN; this.walletName process.env.WALLET_NAME; // 验证必要配置是否存在 if (!this.accountId || !this.apiToken) { throw new Error(Missing required environment variables: CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN); } // 配置 axios 实例统一设置认证头和基础URL this.client axios.create({ baseURL: https://api.cloudflare.com/client/v4/accounts/${this.accountId}/wallet, headers: { Authorization: Bearer ${this.apiToken}, Content-Type: application/json, }, }); } /** * 获取或创建钱包。如果指定名称的钱包不存在则创建它。 * returns {PromiseObject} 钱包对象包含 id, name, balance 等信息。 */ async getOrCreateWallet() { try { // 首先尝试列出所有钱包并查找指定名称的钱包 const listResponse await this.client.get(/wallets); const wallets listResponse.data.result || []; const existingWallet wallets.find(w w.name this.walletName); if (existingWallet) { console.log(Wallet ${this.walletName} already exists. ID: ${existingWallet.id}); return existingWallet; } // 如果不存在则创建新钱包 console.log(Creating new wallet: ${this.walletName}); const createResponse await this.client.post(/wallets, { name: this.walletName, // 可以在此处设置初始元数据如关联的项目ID、环境等 metadata: { project: ai-translator, environment: production, createdBy: wallet-service } }); return createResponse.data.result; } catch (error) { console.error(Failed to get or create wallet:, error.response?.data || error.message); throw error; } } /** * 从钱包中扣除指定金额。 * param {number} amount - 扣除的金额单位美分/分取决于Cloudflare的货币单位。 * param {string} description - 交易描述用于对账。 * param {string} [walletId] - 钱包ID。如果未提供将使用 getOrCreateWallet 获取。 * returns {PromiseObject} 交易结果对象。 */ async debit(amount, description, walletId null) { try { let targetWalletId walletId; if (!targetWalletId) { const wallet await this.getOrCreateWallet(); targetWalletId wallet.id; } if (!targetWalletId) { throw new Error(Wallet ID is required to perform a debit transaction.); } const response await this.client.post(/wallets/${targetWalletId}/debit, { amount: { // 假设金额单位为美分 (USD cents)。请根据Cloudflare API文档确认。 currency: USD, value: amount, // 例如100 代表 1.00 USD }, description: description, // 可以添加更多元数据如本次调用的请求ID、用户ID等便于追踪 metadata: { service: mock-translation-api, timestamp: new Date().toISOString(), } }); console.log(Debit successful. Transaction ID: ${response.data.result?.id}. New balance (if provided): ${response.data.result?.balance}); return response.data.result; } catch (error) { // 这里需要特别处理余额不足等错误 const errorData error.response?.data; console.error(Debit transaction failed:, errorData || error.message); // 示例根据错误码进行特定处理 if (errorData errorData.errors errorData.errors.some(e e.code 10009)) { // 假设10009是余额不足错误码 throw new Error(INSUFFICIENT_FUNDS); } // 抛出其他错误 throw new Error(WALLET_ERROR: ${errorData?.errors?.[0]?.message || error.message}); } } /** * 查询钱包余额和详情。 * param {string} [walletId] - 钱包ID。 * returns {PromiseObject} 钱包详情对象。 */ async getWalletDetails(walletId null) { try { let targetWalletId walletId; if (!targetWalletId) { const wallet await this.getOrCreateWallet(); targetWalletId wallet.id; } const response await this.client.get(/wallets/${targetWalletId}); return response.data.result; } catch (error) { console.error(Failed to get wallet details:, error.response?.data || error.message); throw error; } } } module.exports WalletService;关键代码解释构造函数与配置类初始化时从环境变量加载关键配置并创建一个预配置的axios实例。这保证了所有请求都带有正确的认证头和基础 URL。getOrCreateWallet方法这是幂等性设计的体现。先尝试查找现有钱包如果不存在则创建。这确保了脚本可以安全地多次运行。创建钱包时可以附加metadata这对于后续按项目或环境筛选钱包非常有用。debit方法这是核心扣费方法。金额表示示例中假设金额以美分USD cents为单位。在实际使用前务必查阅最新的 Cloudflare Wallet API 文档确认货币单位和精度。错误处理特别捕获了 HTTP 错误并尝试解析错误码。例如我们假设错误码10009代表余额不足INSUFFICIENT_FUNDS并在上层逻辑中可以根据此特定错误类型采取不同策略如暂停服务、发送告警。元数据Metadata在交易描述之外附加了metadata字段。这是可编程钱包的强大之处你可以将任何有助于追踪的上下文信息如请求 ID、会话 ID、资源 ID存入便于后期进行精细的财务分析和审计。getWalletDetails方法用于查询钱包当前状态主要是余额。4. 模拟付费翻译 API 与智能体工作流接下来我们构建一个模拟的付费翻译 API 服务以及一个使用 Wallet 来支付调用费用的 AI 智能体主逻辑。4.1 创建模拟付费翻译 APImock-translation-api.js模拟了一个按次收费的外部翻译服务。// mock-translation-api.js const express require(express); const app express(); app.use(express.json()); // 模拟的翻译函数实际项目中会调用如 Google Translate、DeepL 等 API function translateText(text) { // 这里是一个简单的模拟 const translations { 你好世界: Hello, World, 人工智能: Artificial Intelligence, 可编程钱包: Programmable Wallet, 今天天气很好: The weather is nice today }; return translations[text] || [Translated]: ${text}; } // 定价每翻译一个字符按中文字符算收费 0.1 美分 (0.001 USD) // 最低消费 10 美分 (0.10 USD) function calculateCost(text) { const charCount text.length; const costInCents Math.max(10, Math.ceil(charCount * 0.1)); // 单位美分 return costInCents; } // 翻译 API 端点 app.post(/api/v1/translate, (req, res) { const { text, authToken } req.body; // 实际场景中authToken 可能是你的付费 API Key if (!text) { return res.status(400).json({ error: Missing text to translate }); } // 模拟认证在实际集成中这里会验证 authToken if (!authToken) { return res.status(401).json({ error: Invalid or missing authentication token }); } console.log([Translation API] Received request to translate: ${text.substring(0, 50)}...); const translation translateText(text); const costInCents calculateCost(text); // 模拟处理延迟 setTimeout(() { res.json({ success: true, original: text, translated: translation, cost: { currency: USD, value: costInCents, // 返回成本单位美分 formatted: $${(costInCents / 100).toFixed(2)} }, requestId: req_${Date.now()} }); }, 100); // 100ms 延迟 }); // 健康检查端点 app.get(/health, (req, res) { res.json({ status: ok, service: mock-translation-api }); }); const PORT process.env.MOCK_API_PORT || 3001; app.listen(PORT, () { console.log(Mock Translation API server running on http://localhost:${PORT}); });这个模拟 API 有两个关键点成本计算它根据输入文本长度计算本次调用的成本以美分为单位并在响应中返回。这模拟了真实付费 API 的计费模式。认证它期望一个authToken。在真实场景中这可能是你从服务商处获得的 API 密钥。在我们的智能体工作流中我们将用 Wallet 支付来代替直接传递这个密钥或者将其与 Wallet 支付关联。4.2 实现 AI 翻译智能体主逻辑index.js文件将整合 Wallet 服务和翻译 API形成完整的智能体工作流。// index.js require(dotenv).config(); const axios require(axios); const WalletService require(./wallet-service); // 初始化服务 const walletService new WalletService(); const TRANSLATION_API_URL http://localhost:3001/api/v1/translate; // 注意这里我们仍然需要一个 token 来调用模拟API但在 Wallet 集成理想状态下 // 这个 token 可能是一个通用网关令牌其背后关联着你的 Wallet 账户。 const MOCK_API_AUTH_TOKEN dummy_token_for_mock_api; async function translateWithAI(text) { console.log(\n AI Translator Agent Starting ); console.log(Input: ${text}); // 步骤 1: 查询钱包余额确保有足够资金可选但推荐 try { const walletDetails await walletService.getWalletDetails(); console.log(Current wallet balance: ${walletDetails.balance?.value || N/A} ${walletDetails.balance?.currency || USD}); // 这里可以添加逻辑如果余额低于阈值发送告警或暂停服务。 } catch (error) { console.warn(Could not check wallet balance: ${error.message}. Proceeding anyway...); } // 步骤 2: 调用付费翻译 API let apiResponse; try { console.log(Calling translation API...); apiResponse await axios.post(TRANSLATION_API_URL, { text: text, authToken: MOCK_API_AUTH_TOKEN, }); console.log(Translation API call successful. Cost: ${apiResponse.data.cost.formatted}); } catch (apiError) { console.error(Translation API call failed:, apiError.response?.data || apiError.message); // 如果 API 调用失败则不应该扣费 throw new Error(TRANSLATION_API_FAILED: ${apiError.message}); } const costInCents apiResponse.data.cost.value; const requestId apiResponse.data.requestId; // 步骤 3: 从 Wallet 中扣除本次 API 调用费用 try { console.log(Attempting to debit ${costInCents} cents from wallet...); const debitResult await walletService.debit( costInCents, Translation service charge for: ${text.substring(0, 30)}..., // 描述 // 可以传递 walletId如果为空则使用环境变量中名称对应的钱包 ); console.log(Payment successful. Transaction ID: ${debitResult.id}); } catch (debitError) { // 特别处理余额不足错误 if (debitError.message INSUFFICIENT_FUNDS) { console.error(PAYMENT FAILED: Insufficient funds in wallet. Service suspended.); // 在实际场景中这里应该触发告警、暂停任务队列、通知管理员等。 // 由于支付失败可以考虑是否要回滚或标记此次翻译为“未付费”。 throw new Error(INSUFFICIENT_FUNDS); } else { console.error(PAYMENT FAILED due to wallet error: ${debitError.message}); // 其他 Wallet 错误如网络问题、权限问题。这是一个关键故障。 // 需要决定是否重试扣款或者将此次交易标记为“待处理”由后台对账系统处理。 throw new Error(WALLET_DEBIT_FAILED: ${debitError.message}); } } // 步骤 4: 返回最终结果 console.log( AI Translator Agent Finished \n); return { success: true, translation: apiResponse.data.translated, financial: { cost: apiResponse.data.cost, transactionId: debitResult.id, // 假设 debitResult 在上一步已定义 }, requestId: requestId, }; } // 主执行函数 async function main() { try { // 示例翻译几句话 const textsToTranslate [ 你好世界, 人工智能和可编程钱包是云原生的重要部分, 今天天气很好 ]; for (const text of textsToTranslate) { try { const result await translateWithAI(text); console.log(Translated: ${text} - ${result.translation}); console.log(---); } catch (agentError) { console.error(Agent failed for text ${text}:, agentError.message); // 根据错误类型决定是否继续处理下一个任务 if (agentError.message INSUFFICIENT_FUNDS) { console.log(Stopping further processing due to insufficient funds.); break; } } } // 最终检查钱包余额 const finalBalance await walletService.getWalletDetails(); console.log(\nFinal wallet balance: ${finalBalance.balance?.value || N/A} ${finalBalance.balance?.currency}); } catch (error) { console.error(Unexpected error in main process:, error); } } // 启动模拟 API 服务器和智能体 if (require.main module) { // 你可以选择在一个进程中同时启动 API 和 Agent或者分开运行。 // 这里我们假设先启动 mock-translation-api.js (node mock-translation-api.js) // 然后在另一个终端运行 node index.js console.log(Please ensure the Mock Translation API is running on port 3001.); console.log(Run: node mock-translation-api.js); console.log(Then in another terminal, run: node index.js); // 为了演示我们直接调用 main但需要 API 服务已启动。 // 在实际运行前请先启动模拟API。 // main(); } module.exports { translateWithAI };工作流详解余额预检可选但推荐智能体在开始工作前先查询钱包余额。这可以作为一道简单的防护避免在明显资金不足时仍发起大量 API 调用产生大量失败的支付请求。调用外部服务智能体调用模拟的付费翻译 API。注意此时服务调用已经发生成本已经产生在真实场景中服务提供商会在你调用时计费无论你后续支付是否成功。因此步骤 3 的支付必须非常可靠。支付扣款收到翻译结果和费用后智能体立即调用walletService.debit()进行支付。这是整个流程最关键的环节需要处理INSUFFICIENT_FUNDS等错误。错误处理与补偿API 调用失败如果翻译 API 本身失败则不应扣款。代码在catch块中直接抛出错误跳过扣费步骤。支付失败余额不足这是业务逻辑错误。代码捕获特定的INSUFFICIENT_FUNDS错误并可能暂停整个智能体的后续任务同时触发告警。这里存在一个业务问题服务已调用但支付失败。在生产环境中你需要与 API 提供商约定如何处理这类“后付费”失败的情况例如是否有赊账额度、是否允许事后补缴、还是直接停止服务。支付失败其他原因如网络超时、Wallet 服务异常等。这类错误需要重试机制和事后对账系统来处理确保最终一致性。5. 运行验证与结果分析现在让我们运行整个系统观察 Wallet 如何工作。5.1 启动服务并执行首先在一个终端启动模拟翻译 API 服务器node mock-translation-api.js你应该看到输出Mock Translation API server running on http://localhost:3001然后在另一个终端运行 AI 智能体主程序node index.js为了演示我们需要修改index.js的最后部分直接调用main()函数。将最后几行注释掉改为// 注释掉原来的提示直接运行 main确保你已理解步骤 // if (require.main module) { // console.log(Please ensure the Mock Translation API is running on port 3001.); // console.log(Run: node mock-translation-api.js); // console.log(Then in another terminal, run: node index.js); // // main(); // } // 改为 if (require.main module) { main(); }再次运行node index.js。观察控制台输出它应该类似于Please ensure the Mock Translation API is running on port 3001. Run: node mock-translation-api.js Then in another terminal, run: node index.js因为我们直接运行了main()所以智能体会开始工作。输出会显示创建钱包、查询余额、调用 API、扣款等一系列操作。5.2 验证 Wallet 状态智能体运行后你可以通过 Cloudflare 仪表板或调用我们写的getWalletDetails方法来验证交易是否成功。在index.js的main()函数末尾我们已经添加了查询最终余额的代码。你可以在控制台看到类似输出Final wallet balance: 8500 USD假设初始有 10000 美分三次翻译扣除了 1500 美分。更详细的信息需要登录 Cloudflare 仪表板在 Wallet 服务相关页面查看交易流水里面会记录每一笔debit操作的描述、金额、时间戳和元数据。5.3 模拟错误场景为了充分测试我们可以模拟几种错误余额不足在.env中指定一个已存在但余额很少的钱包名称或者通过仪表板手动将钱包余额调低。再次运行智能体观察是否会正确捕获INSUFFICIENT_FUNDS错误并停止服务。API 令牌错误修改.env中的CLOUDFLARE_API_TOKEN为一个错误的值。运行程序你会看到 Wallet API 调用返回403或401错误。模拟 API 宕机关闭mock-translation-api.js服务然后运行智能体。观察是否会因TRANSLATION_API_FAILED错误而跳过扣款。通过这些测试你可以验证智能体工作流的健壮性。6. 生产环境部署的关键考量与最佳实践将基于 Wallet 的支付集成用于生产环境远不止让代码跑通那么简单。以下是必须考虑的深层问题和实践建议。6.1 事务一致性与补偿机制在我们的流程中“调用服务”和“支付扣款”是两个独立的操作这带来了数据一致性问题。如果扣款失败服务已经被消费了。这在业务上可能无法接受。解决方案预授权模式推荐在调用服务前先向 Wallet 发起一个“预授权”或“冻结”一定金额的操作。服务调用成功后再完成扣款如果失败则释放冻结的金额。这需要 Wallet API 或你的业务层支持此类两阶段操作。事后对账与补单接受最终一致性。记录所有服务调用和支付尝试。部署一个后台对账作业定期比对服务提供商的账单和你的 Wallet 交易记录找出差异并进行人工或自动处理补扣款或退款。服务提供商集成最理想的情况是像 Cloudflare 这样的平台能与主要的 AI 服务商如 OpenAI、Anthropic达成直接计费集成。你授权 Cloudflare Wallet 作为支付方式服务商直接从中扣费实现原子操作。请关注 Cloudflare 的官方集成列表。6.2 安全与权限管理API 令牌管理用于调用 Wallet API 的令牌权限必须严格控制。遵循最小权限原则仅授予Read和Edit权限并且仅限于必要的账户。绝对不要将令牌提交到代码仓库。使用安全的 Secret 管理服务如 HashiCorp Vault、AWS Secrets Manager、Azure Key Vault 或云厂商提供的类似服务。钱包隔离策略按环境隔离开发、测试、生产环境使用完全不同的钱包。按业务/团队隔离不同项目或团队使用独立钱包便于成本分摊和预算控制。按智能体实例隔离对于非常重要的或消耗资源差异大的智能体可以考虑单独的钱包实现成本精准追踪和故障隔离。监控与告警余额监控设置监控当钱包余额低于阈值时如 10 美元触发告警邮件、Slack、短信等。异常交易监控监控失败的扣款交易非余额不足原因这可能意味着集成代码存在 bug 或 Wallet 服务异常。消费速率监控如果某个智能体的消费速度异常飙升可能意味着程序出现循环调用 bug 或遭到滥用。6.3 成本控制与优化预算与限额在代码逻辑或调度策略中实现软性预算。例如智能体每日运行前检查本月累计消费如果已超预算则跳过或降级到免费服务。服务降级当 Wallet 支付失败或余额不足时设计降级策略。例如从付费的高质量翻译 API 降级到免费的或低质量的翻译服务并记录日志供后续分析。缓存与批处理对于可重复的、非实时的请求考虑使用缓存避免重复调用付费 API。对于小的、可批量处理的任务考虑攒一批后再统一调用 API 和支付可能享受更优惠的批量费率并减少交易次数。6.4 日志、审计与可观测性所有与 Wallet 相关的操作都必须记录详尽的日志包括钱包 ID、名称交易金额、描述、状态成功/失败关联的业务请求 ID如翻译请求 ID错误码和错误信息操作时间戳这些日志应集中收集如 ELK Stack、Loki 等并用于生成财务报告、审计追踪和故障排查。7. 常见问题排查清单在实际集成和使用 Cloudflare Wallet 时你可能会遇到以下问题。这里提供排查思路。问题现象可能原因检查步骤解决方案API 调用返回 403 Forbidden1. API 令牌无效或已撤销。2. API 令牌权限不足。3. 账户 ID 错误。1. 在 Cloudflare 仪表板 “API Tokens” 页面验证令牌是否存在且状态为 “Active”。2. 检查令牌权限是否包含 Wallet 的 Read 和 Edit。3. 核对.env中的CLOUDFLARE_ACCOUNT_ID是否正确。1. 重新生成 API 令牌并更新环境变量。2. 编辑令牌添加必要权限。3. 修正账户 ID。创建钱包或扣款时返回 400 Bad Request1. 请求体 JSON 格式错误或缺少必填字段。2. 金额格式不正确如负数、非数字。3. 货币代码不支持。1. 使用console.log或工具查看发送的请求体。2. 对照官方 API 文档检查字段名和类型。3. 确认amount.currency字段值是否为文档支持的类型如 “USD”。1. 修正 JSON 结构。2. 确保金额为整数。3. 使用正确的货币代码。debit操作失败提示余额不足1. 钱包内确实没有足够余额。2. 扣款金额计算有误远超实际所需。1. 调用getWalletDetails查询当前余额。2. 检查计算服务成本的逻辑是否正确。1. 通过 Cloudflare 仪表板为钱包充值。2. 修复成本计算逻辑并考虑增加余额不足的预检和告警。交易成功但服务未调用/服务调用成功但扣款失败1. 工作流非原子性两个操作之间出现程序崩溃或网络分区。2. 错误处理逻辑不完善未能正确处理部分失败。1. 检查应用日志确认两个操作的顺序和结果。2. 审查try-catch块确保一个操作失败后另一个操作有相应的补偿或回滚机制。1. 引入更健壮的事务模式如预授权、Saga 模式。2. 实现后台对账作业修复不一致状态。无法找到指定名称的钱包1. 钱包名称拼写错误或大小写不一致。2. 钱包存在于另一个 Cloudflare 账户下。3.getOrCreateWallet逻辑中列表查询未返回预期钱包。1. 核对.env中的WALLET_NAME。2. 确认当前使用的 API 令牌和账户 ID 是否正确。3. 在getOrCreateWallet方法中添加调试日志打印查询到的所有钱包列表。1. 统一名称大小写。2. 使用正确的账户和令牌。3. 检查 API 响应格式确保正确解析result字段。网络超时或连接中断1. 本地或服务器网络不稳定。2. Cloudflare API 服务临时故障。3. 客户端请求超时设置过短。1. 使用curl或Postman测试 API 连通性。2. 查看 Cloudflare Status Page 。3. 在axios配置中增加timeout参数。1. 检查网络配置。2. 等待服务恢复或联系支持。3. 增加超时时间并实现重试机制使用指数退避算法。8. 扩展方向与进阶思考掌握了基础集成后你可以从以下几个方向深化对可编程钱包的应用多钱包与路由策略为不同成本中心、不同优先级的任务配置不同钱包。智能体可以根据任务类型、用户等级等维度动态选择从哪个钱包扣款。与工作流引擎集成将 Wallet 支付节点嵌入到 Apache Airflow、Prefect 或 Temporal 等工作流引擎中。将“支付”作为一个明确的、可重试、可补偿的步骤来管理。实现预算编排开发一个预算管理服务它定期如每月初为各个钱包分配预算并监控消费速率。当某个钱包消费过快时可以动态调整其预算或通知相关负责人。探索更广泛的“可编程金融”场景Cloudflare Wallet 的理念可以延伸到其他自动化财务场景例如自动为测试环境资源充值、根据流量自动购买 CDN 带宽包、在 Serverless 函数中支付使用第三方 API 的费用等。思考如何将财务逻辑作为代码FinOps as Code进行管理。Cloudflare Wallet 为 AI 智能体和自动化系统引入了一个关键的“财务执行层”。它解决了密钥管理混乱、成本归属不清和支付流程无法自动化的问题。成功落地的关键在于像管理其他基础设施如数据库、缓存一样对可编程钱包进行设计考虑其可用性、安全性、监控和容错。通过本文的示例和讨论希望你能够构建出既智能又经济可控的 AI 应用系统。