AgentGuard：实时监控AI代理成本并防止超支的工具

AgentGuard 是一个开源工具，专为开发者和企业设计，用于实时监控和控制 AI 代理（如大型语言模型）的使用成本。它通过简单的代码集成，帮助用户设定预算上限，防止因 AI 代理运行失控导致的高额费用。AgentGuard 支持多种保护模式，能在成本超支时自动停止进程或发出警告。它的设计简单易用，只需添加几行代码即可在项目中启用，适合各种 AI 开发场景。无论是单机开发还是多进程环境，AgentGuard 都能提供可靠的成本管理和透明的日志记录。

功能列表

• 实时监控 AI 代理的 API 调用成本，显示当前花费和预算占比。
• 支持设置预算上限，超出时可选择抛出错误、发送通知或终止进程。
• 提供详细的 API 调用历史日志，便于追踪和分析成本。
• 支持多进程预算共享，通过 Redis 实现跨进程的成本跟踪。
• 提供隐私保护选项，可自动屏蔽敏感数据。
• 支持动态调整预算上限和保护模式，适应不同任务需求。
• 集成 webhook 功能，向 Slack 或 Discord 发送实时成本警报。
• 提供示例代码，支持 LangChain 等框架的快速集成。

使用帮助

安装流程

AgentGuard 是一个 Node.js 模块，安装和配置过程简单，适合大多数 AI 项目。以下是详细的安装和使用步骤：

1. 安装 Node.js
   确保你的系统已安装 Node.js（建议版本 18 或更高）。你可以在 Node.js 官网 下载并安装。
2. 克隆 AgentGuard 仓库
   在终端运行以下命令，克隆 AgentGuard 的 GitHub 仓库：

   git clone https://github.com/dipampaul17/AgentGuard.git
   cd AgentGuard
   

3. 安装依赖
   进入项目目录后，运行以下命令安装必要的依赖：

   npm install
   

4. 验证安装
   安装完成后，运行以下命令检查是否成功：

   node verify-installation.js
   

   如果安装正确，终端会输出确认信息。

5. 初始化 AgentGuard
   在你的 AI 项目中添加以下两行代码，初始化 AgentGuard：

   const agentGuard = require('agent-guard');
   await agentGuard.init({ limit: 50 });
   

   这里，limit: 50 表示设置 50 美元的预算上限。你可以根据需要调整此值。

配置选项

AgentGuard 提供灵活的配置选项，以下是常用参数的说明：

• limit: 设置预算上限（单位：美元），如 50 表示 50 美元。
• mode: 保护模式，支持以下三种：
  • throw: 超支时抛出错误，适合需要手动处理的情况。
  • notify: 超支时发送通知（如通过 webhook），但不终止进程。
  • kill: 超支时直接终止进程，适合严格预算控制。
• webhook: 配置通知地址（如 Slack 或 Discord 的 webhook URL），用于接收警报。例如：

  webhook: 'https://hooks.slack.com/...'
  

• redis: 配置 Redis URL，用于多进程预算共享。例如：

  redis: 'redis://localhost:6379'
  

• privacy: 设置为 true 时，自动屏蔽敏感数据。
• silent: 设置为 true 时，隐藏实时成本更新日志。

示例初始化代码：

const guard = await agentGuard.init({
limit: 100,
mode: 'throw',
webhook: 'https://hooks.slack.com/...',
redis: 'redis://localhost:6379',
privacy: true
});

主要功能操作

1. 查看当前成本
   使用 guard.getCost() 获取当前总花费。例如：

   console.log(`已花费: $${guard.getCost()}`);
   

2. 调整预算上限
   如果任务优先级变化，可以动态调整预算：

   guard.setLimit(500); // 将预算上限改为 500 美元
   

3. 重置成本
   新任务开始时，可以重置成本计数：

   await guard.reset();
   

4. 查看调用日志
   使用 guard.getLogs() 获取详细的 API 调用历史，便于分析成本来源。
5. 处理超支情况
   当预算超支时，AgentGuard 会根据 mode 参数执行相应操作。例如，若模式为 throw，你可以用 try-catch 处理：

   try {
   const response = await openai.chat.completions.create({...});
   } catch (error) {
   if (error.message.includes('AGENTGUARD_LIMIT_EXCEEDED')) {
   console.log('预算超支:', error.agentGuardData);
   // 切换到低成本模型或保存状态
   }
   }
   

浏览器环境支持

AgentGuard 也支持浏览器环境。引入以下脚本即可：

<script src="https://unpkg.com/agent-guard@latest/dist/agent-guard.min.js"></script>
<script>
AgentGuard.init({ limit: 50, mode: 'notify' });
</script>

示例代码

以下是一个完整的示例，展示如何在 OpenAI 项目中集成 AgentGuard：

const agentGuard = require('agent-guard');
const openai = require('openai');
(async () => {
const guard = await agentGuard.init({
limit: 25,
mode: 'notify',
webhook: 'https://hooks.slack.com/...',
privacy: true
});
try {
const response = await openai.chat.completions.create({
model: 'gpt-4',
messages: [{ role: 'user', content: 'Hello world' }]
});
console.log('响应:', response);
console.log(`当前花费: $${guard.getCost()}`);
} catch (error) {
if (error.message.includes('AGENTGUARD_LIMIT_EXCEEDED')) {
console.log('预算保护触发:', error.agentGuardData);
}
}
})();

调试与测试

AgentGuard 提供多个示例供开发者测试：

• 运行 node examples/runaway-loop-demo.js 模拟无限循环场景，测试预算保护。
• 运行 node examples/langchain-example.js 查看与 LangChain 的集成。
• 打开 examples/test-browser.html 测试浏览器环境支持。

应用场景

1. AI 开发中的成本控制
   开发者在构建 AI 应用时，常常因 API 调用过多导致意外高额费用。AgentGuard 通过实时监控和预算限制，确保开发成本可控，适合个人开发者或小型团队。
2. 企业级 AI 项目管理
   企业在部署大型 AI 项目时，需要跨团队共享预算。AgentGuard 的 Redis 支持允许多进程协同管理成本，适合复杂的企业级应用。
3. 教育与研究项目
   学生或研究人员在使用 AI 模型进行实验时，可以用 AgentGuard 限制实验成本，避免因跑偏任务导致资源浪费。
4. 浏览器端 AI 应用
   在浏览器中运行 AI 代理的开发者，可以通过 AgentGuard 的浏览器支持，监控前端 AI 调用的成本，适合交互式 Web 应用。

QA

1. AgentGuard 支持哪些 AI 框架？
   AgentGuard 是框架无关的工具，支持任何使用 API 调用的 AI 项目。它提供与 LangChain 等框架的示例集成，开发者可根据需要扩展。
2. 如何处理预算超支？
   根据配置的 mode，AgentGuard 可抛出错误（throw）、发送通知（notify）或终止进程（kill）。开发者可通过 try-catch 捕获错误并处理。
3. 是否需要 Redis？
   Redis 是可选的，仅在多进程或分布式环境中需要，用于共享预算数据。单机项目无需配置 Redis。
4. 如何保护敏感数据？
   将 privacy 设置为 true，AgentGuard 会自动屏蔽敏感信息，确保日志和通知中不包含隐私数据。