🛡️ AgentGuard

🚨 The Problem

Your AI agent has a bug. It makes 1000 API calls in a loop. Your $2000 credit card gets charged.

This happens to developers every week:

• Infinite loops in AI workflows
• Testing with production API keys
• Agents that don't know when to stop
• One typo = hundreds of dollars gone

Existing tools only tell you after the damage is done.

💡 The Solution

AgentGuard automatically kills your process before it burns through your budget.

// Add 2 lines to any AI project:
const agentGuard = require('agent-guard');
await agentGuard.init({ limit: 50 }); // $50 budget limit

// Your code runs normally until it hits $50, then AgentGuard stops it
const response = await openai.chat.completions.create({...});

Result: Instead of losing $2000, you lose $50 and get a detailed report.

🔄 How It Works

graph TD
    A["🤖 Your AI Agent Starts"] --> B["📦 AgentGuard.init({ limit: $50 })"]
    B --> C["🔍 Monitors All AI API Calls"]
    C --> D["💰 Tracks Real-Time Costs"]
    D --> E{"💸 Cost ≥ $50?"}
    E -->|No| F["✅ Continue Running"]
    E -->|Yes| G["🛑 Emergency Stop"]
    F --> C
    G --> H["📊 Show Savings Report"]
    H --> I["💾 Log Final Statistics"]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#fff3e0
    style D fill:#fff3e0
    style E fill:#ffebee
    style G fill:#ffcdd2
    style H fill:#e8f5e8

Real-Time Monitoring

sequenceDiagram
    participant App as 🤖 Your App
    participant AG as 🛡️ AgentGuard
    participant API as 🔗 AI API
    participant User as 👤 Developer
    
    App->>AG: init({ limit: $50, mode: "throw" })
    AG->>App: ✅ Protection Active
    
    loop Every AI Call
        App->>API: API Request (OpenAI/Anthropic)
        API->>App: Response + Usage Data
        AG->>AG: 💰 Calculate Cost ($0.0243)
        AG->>AG: 📊 Update Total ($47.23 / $50)
        
        alt Cost Under Limit
            AG->>App: ✅ Continue
        else Cost Exceeds Limit
            AG->>App: 🛑 throw AgentGuardError
            AG->>User: 📱 Webhook Notification
            AG->>User: 💰 "Saved you ~$200!"
        end
    end

Protection Modes

graph LR
    subgraph "🛠️ Protection Modes"
        A["mode: 'throw'<br/>🛡️ Safest"]
        B["mode: 'notify'<br/>⚠️ Warning"]
        C["mode: 'kill'<br/>💀 Nuclear"]
    end
    
    subgraph "🎯 When Limit Exceeded"
        A --> D["✅ Throws recoverable error<br/>📝 Allows cleanup<br/>🔄 Graceful shutdown"]
        B --> E["⚠️ Logs warning<br/>📊 Continues monitoring<br/>🚨 Sends notifications"]
        C --> F["💀 process.exit(1)<br/>🚫 Immediate termination<br/>⚡ No cleanup"]
    end
    
    style A fill:#e8f5e8
    style B fill:#fff3e0
    style C fill:#ffebee
    style D fill:#e8f5e8
    style E fill:#fff3e0
    style F fill:#ffebee

Why AgentGuard vs Other Tools?

| Tool | What It Does | When You Find Out About Problems | |------|-------------|----------------------------------| | OpenAI Dashboard | Shows usage after it happens | Hours later via email | | LangChain Callbacks | Tracks tokens in your code | After script finishes |
| tokencost | Estimates costs beforehand | Before you make calls | | AgentGuard | Stops execution when limit hit | Immediately, mid-execution |

AgentGuard is the only tool that actually prevents runaway costs in real-time.

Quick Start

1. Install

npm install agent-guard

2. Add Protection

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

// Your existing AI code works unchanged
const response = await openai.chat.completions.create({...});

3. Watch It Work

🛡️ AgentGuard v1.2.1 initialized
💰 Budget protection: $50 (mode: throw)
📊 $12.34 / $50.00 (24.7%) | OpenAI API tracked
🛑 COST LIMIT EXCEEDED - Saved you ~$2000!

Quick Start

// Step 1: Add these two lines to your AI agent
const agentGuard = require('agent-guard');
await agentGuard.init({ limit: 25 });  // $25 budget limit

// Step 2: Your existing code works unchanged
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello world' }]
});
console.log('Response:', response); // ← AgentGuard automatically tracks this

// Real-time protection: 🛡️ $12.34 / $25.00 49.4%

Production Configuration

try {
  const guard = await agentGuard.init({
    limit: 100,                              // Budget limit in USD
    mode: 'throw',                          // Safe error vs 'kill' (hard exit)
    webhook: 'https://hooks.slack.com/...',  // Slack/Discord alerts
    redis: 'redis://localhost:6379',        // Multi-process shared budgets
    privacy: true                           // Redact sensitive data
  });
  
  // Your AI agent code here...
  
} catch (error) {
  if (error.message.includes('AGENTGUARD_LIMIT_EXCEEDED')) {
    console.log('Budget protection activated:', error.agentGuardData);
    // Handle gracefully: save state, notify, switch to cheaper model, etc.
  }
}

What You'll See

--------------------------------------------------
🛡️ AgentGuard v1.2.0 initialized
💰 Budget protection: $25 (mode: throw)
📡 Monitoring: console.log, fetch, axios, undici, got
--------------------------------------------------

$0.23 / $25.00 0.9%     # Real-time cost tracking
$2.45 / $25.00 9.8%     # Updates with each API call  
$20.10 / $25.00 80.4%   # Warning at 80%
$24.89 / $25.00 99.6%   # Danger at 90%

🛑 AGENTGUARD: COST LIMIT EXCEEDED - Saved you ~$75.00
💰 Total cost when stopped: $24.89
📊 Budget used: 99.6%
🛡️ Mode: throw - gracefully stopping with recoverable error

💡 Real-World Examples

Development Protection

// Protect development scripts from expensive mistakes
await agentGuard.init({ limit: 10, mode: 'throw' });
// Safely experiment with AI without surprise bills

Production Deployment

// Multi-process protection with Redis
await agentGuard.init({
  limit: 1000,
  mode: 'throw',
  redis: 'redis://production:6379',
  webhook: 'https://hooks.slack.com/alerts'
});

Browser Applications

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

Dynamic Budget Management

const guard = await agentGuard.init({ limit: 100 });

// Check costs anytime
console.log(`Spent: $${guard.getCost()}`);

// Adjust for high-priority tasks
if (urgentTask) guard.setLimit(500);

// Reset for new session
await guard.reset();

🎯 Live Protection Examples

See AgentGuard prevent real runaway costs:

# Runaway loop protection (simulates infinite AI loop)
node examples/runaway-loop-demo.js

# Real customer workflow with budget protection
node examples/real-customer-demo.js

# LangChain integration example
node examples/langchain-example.js

# Interactive browser demo
open examples/test-browser.html

What you'll see: Real-time cost tracking, automatic protection activation, and graceful error handling that saves money.

🔧 How Real-Time Protection Works

Automatic AI API Interception

No code changes needed - AgentGuard automatically monitors:

• fetch() - Global HTTP request interception
• axios - Automatic response processing
• undici/got - Modern Node.js HTTP clients
• console.log() - API response detection in logs
• http/https - Raw Node.js request monitoring

Accurate Cost Calculation

• Real tokenizers: OpenAI's tiktoken + Anthropic's official tokenizer
• Live pricing: Fetches current rates from community sources
• Streaming support: Accumulates tokens from partial responses
• Multimodal: Handles images, audio, and complex content
• Smart fallback: Accurate estimation when tokenizers unavailable

Protection Activation

1. Real-time tracking: Every API call updates budget
2. Threshold warnings: Visual alerts at 80% and 90%
3. Limit enforcement: Automatic protection when budget exceeded
4. Graceful handling: Throws catchable error vs hard process exit
5. Cost data: Detailed breakdown for recovery decisions

Supports all major providers: OpenAI, Anthropic, auto-detected from URLs

📊 What Gets Protected

• 🛡️ Infinite loops calling AI APIs
• 🛡️ Expensive model calls (GPT-4, Claude Opus)
• 🛡️ Recursive agent calls with bugs
• 🛡️ Development workflows with cost oversight
• 🛡️ Runaway RAG document processing

🔒 Security & Reliability

Privacy Protection

await agentGuard.init({
  privacy: true,    // Redacts request/response content from logs
  silent: true      // Disables cost display for sensitive environments
});

• Data redaction: Request/response bodies marked as [REDACTED]
• URL filtering: Sensitive API endpoints optionally hidden
• Local operation: No data sent to external services
• Memory safety: Automatic cleanup of sensitive data

Failure Mode Safety

// Graceful degradation (recommended)
mode: 'throw'    // Throws catchable AgentGuardError
mode: 'notify'   // Warns but continues execution  
mode: 'kill'     // Hard process termination (use sparingly)

Why soft failures matter:

• ✅ Preserves database transactions
• ✅ Allows graceful cleanup
• ✅ Enables error recovery
• ✅ Protects worker threads

Multi-Process Protection

await agentGuard.init({
  redis: 'redis://localhost:6379',  // Shared budget across processes
  limit: 100                        // Combined limit for all instances
});

🛠️ API Reference

init(options)

Initializes AgentGuard with the specified options.

const agentGuard = require('agent-guard');
const guard = await agentGuard.init({
  limit: 50,                               // Cost limit in USD
  mode: 'throw',                          // 'throw' | 'notify' | 'kill'
  webhook: null,                          // Webhook URL for notifications
  redis: null,                            // Redis URL for multi-process tracking
  privacy: false,                         // Redact sensitive data
  silent: false                           // Hide cost updates
});

Guard Instance Methods

// Cost monitoring
guard.getCost()        // Current total cost
guard.getLimit()       // Current budget limit
guard.getLogs()        // Detailed API call history

// Budget management  
guard.setLimit(200)    // Update budget limit
guard.reset()          // Reset costs to $0

// Configuration
guard.setMode('notify') // Change protection mode
guard.updatePrices()   // Refresh live pricing data

🤝 Contributing

We love contributions! See our Contributing Guide for details.

git clone https://github.com/dipampaul17/AgentGuard.git
cd AgentGuard
node verify-installation.js

📜 License

MIT - Use anywhere, even commercial projects.

📞 Support

• 🐛 Bug Reports: GitHub Issues
• 💬 Questions: GitHub Discussions
• 📖 Documentation: API Reference • Quick Start

📦 What's Included

• ✅ Real-time protection - Autonomous cost prevention that actually works
• ✅ Production ready - TypeScript definitions, browser support, Redis integration
• ✅ Live examples - LangChain integration, runaway protection demos
• ✅ Comprehensive docs - API reference, security guide, comparison analysis

AgentGuard: The only tool that stops AI runaway costs before they happen.

Real-time budget enforcement • Graceful error handling • Zero code changes

⭐ Star on GitHub • 📦 Install from NPM • 📊 See Comparison