AgentGuard
扫码查看

防止AI应用因Bug产生天价API账单的开发工具

AgentGuard

综合介绍

AgentGuard是一个为开发者设计的实时“护栏”工具,主要用于解决人工智能(AI)应用开发中一个常见且代价高昂的问题:程序错误导致的API费用失控。在AI代理或大语言模型应用的开发过程中,一个微小的Bug(例如无限循环)就可能导致程序在短时间内进行成千上万次API调用,从而产生巨额费用。AgentGuard通过在代码中添加简单的几行配置,就能实时监控所有由应用发起的AI API调用(如OpenAI、Anthropic等),并精确计算其产生的费用。开发者可以预设一个费用上限,一旦累计费用达到这个阈值,AgentGuard会根据预设的模式自动采取行动,例如抛出异常、发送警告通知,或直接终止进程,从而有效避免预算超支。

功能列表

  • 实时成本监控:自动拦截应用中的所有AI API请求,实时计算并累积token消耗所产生的费用。
  • 预算保护:用户可以设置一个具体的费用上限(如50美元),当实际费用达到该上限时,系统会自动触发保护机制。
  • 多种保护模式
    • throw(抛出异常):达到限额时抛出一个可捕获的错误,允许开发者进行后续的清理或恢复操作,是推荐的安全模式。
    • notify(仅通知):达到限额时在控制台打印警告信息并发送Webhook通知,但不会中断程序运行。
    • kill(终止进程):立即强制退出整个应用程序(process.exit(1)),是一种不做任何清理的紧急停止方式。
  • Webhook通知:支持配置Webhook地址(如Slack或Discord),在触发保护机制时发送实时警报。
  • 跨进程预算共享:通过集成Redis,可以让多个独立的进程或服务实例共享同一个费用预算,适用于分布式或多进程架构的应用。
  • 隐私保护模式:提供privacy选项,开启后可以在日志中隐藏敏感的请求和响应数据,保护数据安全。
  • 全面的API支持:无需修改原有代码,即可自动监控fetchaxioshttp/https等多种HTTP客户端发出的请求。
  • 精准的成本计算:使用官方的tiktoken等分词器,并能获取最新的API价格,支持文本、图像等多种格式的成本计算。

使用帮助

AgentGuard的设计目标是让开发者以最小的成本接入,只需简单几步,就可以为你的AI项目增加一层坚实的费用保护。

安装

首先,你需要通过npm(Node.js包管理器)将AgentGuard安装到你的项目中。打开终端,进入你的项目目录,然后运行以下命令:

npm install agent-guard

快速上手

安装完成后,你可以在你的AI应用代码的入口处,用两行代码快速启动保护。

  1. 引入并初始化AgentGuard在你的主程序文件(例如index.js)的开头,引入agent-guard模块,并调用init方法来初始化。你需要设置一个limit参数,它代表你的美元预算上限。
    const agentGuard = require('agent-guard');
    async function main() {
    // 在这里初始化AgentGuard并设置50美元的预算上限
    await agentGuard.init({ limit: 50 });
    // 下面是你原有的AI应用代码,无需任何改动
    // 例如,这是一个调用OpenAI API的例子
    const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: '你好,世界' }]
    });
    console.log('API响应:', response);
    }
    main();
    
  2. 观察运行状态当你运行上述代码后,AgentGuard会自动开始工作。它会监控所有后续的API调用,并在控制台实时显示当前的费用消耗情况。

    输出会像这样:

    🛡️ AgentGuard v1.2.1 initialized
    💰 Budget protection: $50 (mode: throw)
    📊 $12.34 / $50.00 (24.7%) | OpenAI API tracked
    

    如果费用持续上涨并达到50美元的限额,AgentGuard会立即介入,默认情况下会抛出一个错误并停止后续的API调用,同时显示一条消息,告诉你它可能为你节省了多少钱。

生产环境配置

在生产环境或更复杂的应用中,你可能需要更详细的配置。init方法支持传入一个配置对象,包含更多高级选项。

const agentGuard = require('agent-guard');
async function startApp() {
try {
const guard = await agentGuard.init({
limit: 100,                          // 预算上限,单位为美元
mode: 'throw',                       // 保护模式,推荐使用'throw'以进行优雅的错误处理
webhook: 'https://hooks.slack.com/...', // 你的Slack或Discord Webhook地址,用于接收警报
redis: 'redis://localhost:6379',     // Redis连接字符串,用于多进程共享预算
privacy: true                        // 开启隐私模式,日志中将隐藏敏感数据
});
// ... 你的AI应用核心逻辑 ...
} catch (error) {
// 如果mode设置为'throw',当达到费用上限时,代码会进入这里
if (error.message.includes('AGENTGUARD_LIMIT_EXCEEDED')) {
console.log('费用超出预算,保护机制已激活:', error.agentGuardData);
// 在这里可以添加自定义的逻辑,比如:
// 1. 保存当前应用的状态
// 2. 通知系统管理员
// 3. 切换到一个更便宜的备用模型继续处理任务
} else {
// 处理其他类型的错误
console.error('发生未知错误:', error);
}
}
}
startApp();

动态预算管理

AgentGuard初始化后返回的guard实例对象提供了一些方法,允许你在程序运行时动态地管理预算和配置。

  • 获取当前花费:console.log(已花费: $${guard.getCost()});
  • 动态调整预算上限:你可以根据任务的优先级动态调整预算。例如,为一个紧急任务临时增加预算。if (isUrgentTask) { guard.setLimit(500); }
  • 重置成本计数器:当你开始一个新的会话或者一个完全独立的任务时,可以重置费用计数器。await guard.reset();

浏览器环境使用

AgentGuard同样支持在前端浏览器环境中使用,这可以帮助你监控直接在浏览器中发生的AI API调用。

<!-- 引入AgentGuard的浏览器版本 -->
<script src="https://unpkg.com/agent-guard@latest/dist/agent-guard.min.js"></script>
<script>
// 初始化并设置一个通知模式的预算保护
AgentGuard.init({
limit: 50,
mode: 'notify' // 在浏览器中,'notify'模式可以避免因抛出错误而中断整个页面脚本
});
// 你在浏览器中的AI调用代码...
</script>

通过以上这些详细的步骤和配置,你可以将AgentGuard深度集成到你的AI项目中,确保开发和线上运行的财务安全。

应用场景

  1. 开发与调试在开发AI功能时,开发者可以为一个调试会话设置一个非常低的预算上限(例如10美元)。这样,即使代码中存在死循环或逻辑错误,也能保证不会因为反复调用昂贵的模型(如GPT-4o)而产生意外的高额账单。
  2. 生产环境安全监控在正式上线的应用中,将AgentGuard作为一道安全防线。通过配置Redis和Webhook,可以为整个服务集群设置一个总的预算上限。一旦费用接近或达到阈值,系统会自动发送警报到Slack,并根据策略(如throw模式)优雅地暂停服务,防止因意外流量或恶意攻击导致财务损失。
  3. 自动化工作流(Agent)对于自主运行的AI代理(Agent),其行为有时难以预测。AgentGuard可以确保这些代理在执行复杂任务(如递归分析、代码生成)时,其行为始终处于成本可控的范围内。一旦某个代理的行为失控,可以立即将其停止,并记录下详细的成本数据供后续分析。
  4. 多租户SaaS平台如果你的SaaS平台为不同用户提供AI功能,你可以为每个用户的会话或每个租户启动一个独立的AgentGuard实例。通过动态设置和重置预算,可以精确地控制每个用户的资源消耗,防止单个用户的滥用行为影响整个平台的稳定性。

QA

  1. AgentGuard支持哪些AI服务提供商?AgentGuard能够自动监控通过标准HTTP客户端(如fetch、axios)发出的网络请求。它会根据请求的URL自动识别主流的AI服务提供商,如OpenAI和Anthropic,并应用相应的计费规则。因此,它理论上兼容任何通过标准HTTP API提供服务的AI平台。
  2. AgentGuard会影响我的应用性能吗?AgentGuard被设计为轻量级工具,其性能开销极小。它在每次API调用后执行快速的计算,这个过程通常在几毫秒内完成。对于绝大多数应用场景,这种微小的延迟是可以忽略不计的,不会对用户体验或应用性能产生显著影响。
  3. 开启privacy模式后,AgentGuard还会发送数据到外部吗?不会。AgentGuard完全在本地运行,其所有计算和监控都在你自己的服务器或设备上完成。它不会将你的任何API请求、响应或密钥发送到任何外部服务器。开启privacy模式只是为了确保在本地日志中也不会记录这些敏感信息。
  4. 如果我同时运行多个应用实例,该如何统一管理预算?这就是redis配置选项的用途。通过为所有应用实例配置相同的Redis数据库地址,它们可以共享同一个成本计数器。每个实例在进行API调用后都会更新Redis中的总费用,并检查是否超过共享的预算上限。这使得对整个分布式系统的成本控制成为可能。
微信微博Email复制链接