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支持:无需修改原有代码,即可自动监控
fetch
,axios
,http/https
等多种HTTP客户端发出的请求。 - 精准的成本计算:使用官方的
tiktoken
等分词器,并能获取最新的API价格,支持文本、图像等多种格式的成本计算。
使用帮助
AgentGuard的设计目标是让开发者以最小的成本接入,只需简单几步,就可以为你的AI项目增加一层坚实的费用保护。
安装
首先,你需要通过npm(Node.js包管理器)将AgentGuard安装到你的项目中。打开终端,进入你的项目目录,然后运行以下命令:
npm install agent-guard
快速上手
安装完成后,你可以在你的AI应用代码的入口处,用两行代码快速启动保护。
- 引入并初始化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();
- 观察运行状态当你运行上述代码后,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项目中,确保开发和线上运行的财务安全。
应用场景
- 开发与调试在开发AI功能时,开发者可以为一个调试会话设置一个非常低的预算上限(例如10美元)。这样,即使代码中存在死循环或逻辑错误,也能保证不会因为反复调用昂贵的模型(如GPT-4o)而产生意外的高额账单。
- 生产环境安全监控在正式上线的应用中,将AgentGuard作为一道安全防线。通过配置Redis和Webhook,可以为整个服务集群设置一个总的预算上限。一旦费用接近或达到阈值,系统会自动发送警报到Slack,并根据策略(如
throw
模式)优雅地暂停服务,防止因意外流量或恶意攻击导致财务损失。 - 自动化工作流(Agent)对于自主运行的AI代理(Agent),其行为有时难以预测。AgentGuard可以确保这些代理在执行复杂任务(如递归分析、代码生成)时,其行为始终处于成本可控的范围内。一旦某个代理的行为失控,可以立即将其停止,并记录下详细的成本数据供后续分析。
- 多租户SaaS平台如果你的SaaS平台为不同用户提供AI功能,你可以为每个用户的会话或每个租户启动一个独立的AgentGuard实例。通过动态设置和重置预算,可以精确地控制每个用户的资源消耗,防止单个用户的滥用行为影响整个平台的稳定性。
QA
- AgentGuard支持哪些AI服务提供商?AgentGuard能够自动监控通过标准HTTP客户端(如fetch、axios)发出的网络请求。它会根据请求的URL自动识别主流的AI服务提供商,如OpenAI和Anthropic,并应用相应的计费规则。因此,它理论上兼容任何通过标准HTTP API提供服务的AI平台。
- AgentGuard会影响我的应用性能吗?AgentGuard被设计为轻量级工具,其性能开销极小。它在每次API调用后执行快速的计算,这个过程通常在几毫秒内完成。对于绝大多数应用场景,这种微小的延迟是可以忽略不计的,不会对用户体验或应用性能产生显著影响。
- 开启
privacy
模式后,AgentGuard还会发送数据到外部吗?不会。AgentGuard完全在本地运行,其所有计算和监控都在你自己的服务器或设备上完成。它不会将你的任何API请求、响应或密钥发送到任何外部服务器。开启privacy
模式只是为了确保在本地日志中也不会记录这些敏感信息。 - 如果我同时运行多个应用实例,该如何统一管理预算?这就是
redis
配置选项的用途。通过为所有应用实例配置相同的Redis数据库地址,它们可以共享同一个成本计数器。每个实例在进行API调用后都会更新Redis中的总费用,并检查是否超过共享的预算上限。这使得对整个分布式系统的成本控制成为可能。