🛡️ AgentGuard

🚨 문제점 (The Problem)

당신의 AI 에이전트에 버그가 발생했습니다. 루프(loop) 내에서 1,000번의 API 호출을 수행합니다. 당신의 2,000달러 신용카드가 청구됩니다.

이런 일은 개발자들에게 매주 발생합니다:

• AI 워크플로우 (workflows) 내의 무한 루프 (Infinite loops)
• 프로덕션 (production) API 키를 사용한 테스트
• 언제 멈춰야 할지 모르는 에이전트들
• 오타 하나로 수백 달러가 증발함

기존 도구들은 피해가 발생한 이후에만 알려줍니다.

💡 해결책 (The Solution)

AgentGuard는 예산이 소진되기 전에 프로세스를 자동으로 종료합니다.

// 어떤 AI 프로젝트에도 2줄만 추가하세요:
const agentGuard = require('agent-guard');
await agentGuard.init({ limit: 50 }); // $50 예산 제한
...

결과: 2,000달러를 잃는 대신, 50달러만 잃고 상세 보고서를 받게 됩니다.

🔄 작동 방식 (How It Works)

graph TD
    A["🤖 당신의 AI 에이전트 시작"] --> B["📦 AgentGuard.init({ limit: $50 })"]
    B --> C["🔍 모든 AI API 호출 모니터링"]
...

실시간 모니터링 (Real-Time Monitoring)

sequenceDiagram
    participant App as 🤖 당신의 앱 (Your App)
    participant AG as 🛡️ AgentGuard
...

보호 모드 (Protection Modes)

graph LR
    subgraph "🛠️ 보호 모드 (Protection Modes)"
        A["mode: 'throw'<br/>🛡️ 가장 안전함"]
...

왜 다른 도구 대신 AgentGuard인가요? (Why AgentGuard vs Other Tools?)

AgentGuard는 폭주하는 비용을 실시간으로 실제로 방지하는 유일한 도구입니다.

빠른 시작 (Quick Start)

1. 설치 (Install)

npm install agent-guard

2. 보호 기능 추가 (Add Protection)

2. 보호 기능 추가 (Add Protection)

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

...

3. 작동 방식 확인하기 (Watch It Work)

🛡️ AgentGuard v1.2.1 초기화됨
💰 예산 보호: $50 (모드: throw)
📊 $12.34 / $50.00 (24.7%) | OpenAI API 추적 중
...

빠른 시작하기 (Quick Start)

// 1단계: AI 에이전트에 다음 두 줄을 추가하세요
const agentGuard = require('agent-guard');
await agentGuard.init({ limit: 25 });  // $25 예산 제한
...

프로덕션 환경 설정 (Production Configuration)

try {
  const guard = await agentGuard.init({
    limit: 100,                              // USD 단위의 예산 제한
...

확인 가능한 내용 (What You'll See)

--------------------------------------------------
🛡️ AgentGuard v1.2.0 초기화됨
💰 예산 보호: $25 (모드: throw)
...

💡 실제 사용 사례 (Real-World Examples)

개발 환경 보호 (Development Protection)

// 비싼 실수로부터 개발 스크립트를 보호하세요
await agentGuard.init({ limit: 10, mode: 'throw' });
// 예상치 못한 청구서 없이 AI를 안전하게 실험해 보세요

프로덕션 배포 (Production Deployment)

// Redis를 사용한 다중 프로세스 보호
await agentGuard.init({
  limit: 1000,
...

브라우저 애플리케이션 (Browser Applications)

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

동적 예산 관리 (Dynamic Budget Management)

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

// 언제든지 비용을 확인하세요
...

🎯 실시간 보호 사례 (Live Protection Examples)

AgentGuard가 실제 통제 불능의 비용 증가를 방지하는 것을 확인해 보세요:

# 무한 루프 보호 (무한 AI 루프 시뮬레이션)
node examples/runaway-loop-demo.js

...

확인 가능한 내용: 실시간 비용 추적, 자동 보호 활성화, 그리고 돈을 절약하는 우아한 오류 처리 방식입니다.

🔧 실시간 보호 작동 원리 (How Real-Time Protection Works)

자동 AI API 가로채기 (Automatic AI API Interception)

코드 변경이 필요 없습니다. AgentGuard는 다음 항목들을 자동으로 모니터링합니다:

• fetch() - 전역 HTTP 요청 가로채기 (Global HTTP request interception)
• axios - 자동 응답 처리 (Automatic response processing)
• undici/got - 최신 Node.js HTTP 클라이언트 (Modern Node.js HTTP clients)
• console.log() - 로그 내 API 응답 탐지 (API response detection in logs)
• http/https - 로우 레벨 Node.js 요청 모니터링 (Raw Node.js request monitoring)

정확한 비용 계산 (Accurate Cost Calculation)

• 실제 토크나이저 (Real tokenizers): OpenAI의 tiktoken + Anthropic의 공식 토크나이저
• 실시간 가격 (Live pricing): 커뮤니티 소스로부터 현재 요율을 가져옴
• 스트리밍 지원 (Streaming support): 부분 응답(partial responses)으로부터 토큰을 누적
• 멀티모달 (Multimodal): 이미지, 오디오 및 복잡한 콘텐츠 처리
• 스마트 폴백 (Smart fallback): 토크나이저를 사용할 수 없을 때 정확한 추정치 제공

보호 활성화 (Protection Activation)

1. 실시간 추적 (Real-time tracking): 모든 API 호출이 예산을 업데이트함
2. 임계값 경고 (Threshold warnings): 80% 및 90% 지점에서 시각적 알림 제공
3. 한도 강제 (Limit enforcement): 예산 초과 시 자동 보호 작동
4. 우아한 처리 (Graceful handling): 프로세스를 강제 종료하는 대신 포착 가능한 에러(catchable error)를 발생시킴
5. 비용 데이터 (Cost data): 복구 결정을 위한 상세 내역 제공

모든 주요 제공업체 지원: OpenAI, Anthropic, URL로부터 자동 감지

📊 보호 대상

• 🛡️ AI API를 호출하는 무한 루프 (Infinite loops)
• 🛡️ 고비용 모델 호출 (Expensive model calls) (GPT-4, Claude Opus)
• 🛡️ 버그가 포함된 재귀적 에이전트 호출 (Recursive agent calls)
• 🛡️ 비용 관리가 미흡한 개발 워크플로우 (Development workflows)
• 🛡️ 통제 불능 상태의 RAG 문서 처리 (Runaway RAG)

🔒 보안 및 신뢰성 (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): 요청/응답 본문이 [REDACTED]로 표시됨
• URL 필터링 (URL filtering): 민감한 API 엔드포인트를 선택적으로 숨김
• 로컬 작동 (Local operation): 외부 서비스로 데이터를 전송하지 않음
• 메모리 안전성 (Memory safety): 민감한 데이터의 자동 정리

실패 모드 안전성 (Failure Mode Safety)

// 우아한 성능 저하 (Graceful degradation) (권장)
mode: 'throw'    // 포착 가능한 AgentGuardError를 발생시킴
mode: 'notify'   // 경고를 보내지만 실행을 계속함
...

소프트 실패 (Soft failures)가 중요한 이유:

• ✅ 데이터베이스 트랜잭션 (Database transactions) 보존
• ✅ 우아한 정리 (Graceful cleanup) 허용
• ✅ 오류 복구 (Error recovery) 가능
• ✅ 워커 스레드 (Worker threads) 보호

멀티 프로세스 보호 (Multi-Process Protection)

await agentGuard.init({
  redis: 'redis://localhost:6379',  // 프로세스 간 공유되는 예산
  limit: 100                        // 모든 인스턴스의 통합 제한
...

🛠️ API 레퍼런스 (API Reference)

init(options)

지정된 옵션으로 AgentGuard를 초기화합니다.

const agentGuard = require('agent-guard');
const guard = await agentGuard.init({
  limit: 50,                               // USD 단위의 비용 제한
...

가드 인스턴스 메서드 (Guard Instance Methods)

// 비용 모니터링 (Cost monitoring)
guard.getCost()        // 현재 총 비용
guard.getLimit()       // 현재 예산 제한
...

🤝 기여하기 (Contributing)

여러분의 기여를 환영합니다! 자세한 내용은 기여 가이드 (Contributing Guide)를 참조하세요.

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

📜 라이선스 (License)

MIT - 상업적 프로젝트를 포함하여 어디에서든 사용할 수 있습니다.

📞 지원 (Support)

• 🐛 버그 보고 (Bug Reports): GitHub Issues
• 💬 질문 (Questions): GitHub Discussions
• 📖 문서 (Documentation): API 레퍼런스 (API Reference) • 빠른 시작 (Quick Start)

📦 포함 사항 (What's Included)

• ✅ 실시간 보호 (Real-time protection) - 실제로 작동하는 자율적 비용 방지
• ✅ 프로덕션 준비 완료 (Production ready) - TypeScript 정의, 브라우저 지원, Redis 통합
• ✅ 라이브 예제 (Live examples) - LangChain 통합, 폭주 방지 데모
• ✅ 포괄적인 문서 (Comprehensive docs) - API 레퍼런스, 보안 가이드, 비교 분석

AgentGuard: AI 비용 폭주가 발생하기 전에 이를 차단하는 유일한 도구입니다.

실시간 예산 집행 (Real-time budget enforcement) • 우아한 오류 처리 (Graceful error handling) • 코드 변경 없음 (Zero code changes)

⭐ GitHub에서 Star 받기 • 📦 NPM에서 설치하기 • 📊 비교 분석 보기