Performance Optimization

The AI Agents House SDK is designed for high performance out of the box, but there are many configuration options and patterns to optimize for your specific use case. This guide covers performance tuning, monitoring, and optimization strategies.

Performance Overview

Default Performance Characteristics

Throughput: 10,000+ events/minute with default batching
Latency: < 2ms overhead per tracked interaction
Memory: ~1KB per event in buffer, ~2MB base overhead
CPU: Minimal impact with async processing

Performance Bottlenecks

Common performance bottlenecks and their solutions:

Network I/O
Memory Usage
Compliance Processing
Event Serialization

Symptoms: High latency, timeout errors Solutions: Optimize batch size, adjust flush intervals, use regional endpoints

Batch Configuration Optimization

High-Throughput Configuration

For maximum throughput in high-volume scenarios:

const highThroughputConfig = {
  apiKey: 'your-api-key',
  organizationId: 'your-org-id',

  // Optimize for throughput
  batchSize: 1000, // Maximum batch size
  flushInterval: 30000, // 30 seconds

  // Reduce overhead
  enableLogging: false,
  enableComplianceChecks: false, // Disable if not needed

  // Network optimization
  retryAttempts: 3,
  retryDelay: 5000,
  httpTimeout: 60000
};

const monitor = new AgentMonitor(highThroughputConfig);

Low-Latency Configuration

For real-time applications requiring immediate event delivery:

const lowLatencyConfig = {
  apiKey: 'your-api-key',
  organizationId: 'your-org-id',

  // Optimize for latency
  batchSize: 1, // Send immediately
  flushInterval: 100, // Minimal delay

  // Fast failure
  retryAttempts: 1,
  retryDelay: 100,
  httpTimeout: 5000,

  // Minimal processing
  enableLogging: false,
  logLevel: 'error'
};

const monitor = new AgentMonitor(lowLatencyConfig);

Balanced Configuration

For most production scenarios:

const balancedConfig = {
  apiKey: 'your-api-key',
  organizationId: 'your-org-id',

  // Balanced settings
  batchSize: 250,
  flushInterval: 5000, // 5 seconds

  // Reasonable retry policy
  retryAttempts: 3,
  retryDelay: 1000,

  // Essential features only
  enableLogging: false,
  enableComplianceChecks: true,
  logLevel: 'warn'
};

const monitor = new AgentMonitor(balancedConfig);

Memory Optimization

Memory-Efficient Event Tracking

class MemoryEfficientTracker {
  constructor(monitor, options = {}) {
    this.monitor = monitor;
    this.options = {
      maxMetadataSize: 1024, // 1KB max metadata
      enableSampling: true,
      samplingRate: 0.1, // 10% sampling for low-priority events
      ...options
    };
  }

  trackEvent(agentId, event, priority = 'normal') {
    // Sample low-priority events
    if (priority === 'low' && this.options.enableSampling) {
      if (Math.random() > this.options.samplingRate) {
        return; // Skip this event
      }
    }

    // Optimize metadata size
    if (event.metadata) {
      event.metadata = this.optimizeMetadata(event.metadata);
    }

    this.monitor.track(agentId, event);
  }

  optimizeMetadata(metadata) {
    const optimized = {};
    const metadataStr = JSON.stringify(metadata);

    if (metadataStr.length <= this.options.maxMetadataSize) {
      return metadata;
    }

    // Prioritize important fields
    const importantFields = [
      'llmLatency', 'tokensUsed', 'cost', 'riskScore',
      'complianceFlags', 'errorType', 'severity'
    ];

    for (const field of importantFields) {
      if (metadata[field] !== undefined) {
        optimized[field] = metadata[field];
      }
    }

    // Add truncation indicator
    optimized._truncated = true;

    return optimized;
  }
}

// Usage
const efficientTracker = new MemoryEfficientTracker(monitor, {
  maxMetadataSize: 512,
  samplingRate: 0.05 // 5% sampling
});

efficientTracker.trackEvent('agent-id', event, 'low');

Memory Pool Pattern

class EventPool {
  constructor(poolSize = 1000) {
    this.pool = [];
    this.poolSize = poolSize;
    this.initializePool();
  }

  initializePool() {
    for (let i = 0; i < this.poolSize; i++) {
      this.pool.push(this.createEmptyEvent());
    }
  }

  createEmptyEvent() {
    return {
      eventId: '',
      timestamp: 0,
      sessionId: '',
      agentId: '',
      interactionType: '',
      content: '',
      metadata: {}
    };
  }

  getEvent() {
    if (this.pool.length > 0) {
      return this.pool.pop();
    }
    return this.createEmptyEvent();
  }

  returnEvent(event) {
    if (this.pool.length < this.poolSize) {
      // Reset event
      Object.keys(event).forEach(key => {
        if (typeof event[key] === 'object' && event[key] !== null) {
          if (Array.isArray(event[key])) {
            event[key].length = 0;
          } else {
            Object.keys(event[key]).forEach(subKey => delete event[key][subKey]);
          }
        } else {
          event[key] = typeof event[key] === 'string' ? '' : 0;
        }
      });
      this.pool.push(event);
    }
  }
}

// Usage with monitor
const eventPool = new EventPool(500);

class PooledAgentMonitor extends AgentMonitor {
  track(agentId, eventData) {
    const event = eventPool.getEvent();
    Object.assign(event, eventData);
    event.agentId = agentId;
    event.timestamp = Date.now();
    event.eventId = `evt_${Date.now()}_${Math.random().toString(36).slice(2)}`;
    super.track(agentId, event);
    setTimeout(() => eventPool.returnEvent(event), 1000);
  }
}

CPU Optimization

Async Processing Patterns

class AsyncEventProcessor {
  constructor(monitor, options = {}) {
    this.monitor = monitor;
    this.options = {
      workerCount: require('os').cpus().length,
      queueSize: 10000,
      ...options
    };
    this.eventQueue = [];
    this.processing = true;
    this.workers = [];
    this.startWorkers();
  }

  startWorkers() {
    for (let i = 0; i < this.options.workerCount; i++) {
      this.workers.push(this.createWorker());
    }
  }

  createWorker() {
    return setImmediate(async () => {
      while (this.processing || this.eventQueue.length > 0) {
        const events = this.eventQueue.splice(0, 100);
        if (events.length) await this.processEventBatch(events);
        else await new Promise(r => setTimeout(r, 10));
      }
    });
  }

  async processEventBatch(events) {
    try {
      await Promise.all(events.map(e => this.processEvent(e)));
    } catch (err) { console.error('Batch processing error:', err); }
  }

  async processEvent({agentId, data}) {
    this.monitor.track(agentId, data);
  }

  enqueueEvent(agentId, eventData) {
    if (this.eventQueue.length < this.options.queueSize) {
      this.eventQueue.push({agentId, data: eventData});
    } else console.warn('Event queue full, dropping event');
  }

  async shutdown() {
    this.processing = false;
    await Promise.all(this.workers);
    await this.monitor.shutdown();
  }
}

Compliance Rule Optimization

class OptimizedComplianceEngine {
  constructor(monitor) {
    this.monitor = monitor;
    this.ruleCache = new Map();
    this.compiledRules = new Map();
    this.compileRules();
  }

  compileRules() {
    const rules = this.monitor.complianceEngine?.getAllRules() || [];
    rules.forEach(rule => {
      if (rule.category === 'privacy') {
        this.compiledRules.set(rule.id, { ...rule, compiledPatterns: this.compilePIIPatterns(rule) });
      } else if (rule.category === 'fair_lending') {
        this.compiledRules.set(rule.id, { ...rule, compiledKeywords: this.compileKeywordPatterns(rule) });
      }
    });
  }

  compilePIIPatterns() {
    return {
      ssn: /\b\d{3}[- ]?\d{2}[- ]?\d{4}\b/g,
      phone: /\b(?:\+?1\s*-?)?(?:\(\d{3}\)|\d{3})[\s.-]?\d{3}[\s.-]?\d{4}\b/g,
      email: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/gi
    };
  }

  compileKeywordPatterns() {
    const keywords = ['people like you', 'your kind', 'typical for'];
    return new RegExp(keywords.join('|'), 'i');
  }

  async evaluateCompliance(context) {
    const key = this.generateCacheKey(context);
    if (this.ruleCache.has(key)) return this.ruleCache.get(key);
    const result = await this.runOptimizedCheck(context);
    this.ruleCache.set(key, result);
    setTimeout(() => this.ruleCache.delete(key), 60000);
    return result;
  }

  generateCacheKey(context) {
    const str = `${context.agentId}-${context.agentResponse?.length}-${context.userMessage?.length}`;
    return require('crypto').createHash('md5').update(str).digest('hex');
  }

  async runOptimizedCheck(context) {
    const violations = [];
    let score = 0;
    for (const [id, rule] of this.compiledRules) {
      if (!rule.isActive) continue;
      const res = await this.evaluateCompiledRule(rule, context);
      violations.push(...res.violations);
      score += res.riskScore;
    }
    return { isCompliant: violations.length===0, violations, riskScore: Math.min(score,100), requiresReview: score>50 };
  }
}

Network Optimization

Connection Pooling

import https from 'https';
class OptimizedHTTPClient {
  constructor(baseURL, opts={}) {
    this.baseURL = baseURL;
    this.agent = new https.Agent({ keepAlive:true, maxSockets: opts.maxSockets||50, maxFreeSockets: opts.maxFreeSockets||10, timeout: opts.timeout||30000, freeSocketTimeout: opts.freeSocketTimeout||4000 });
  }
  async makeRequest(path, options) {
    return fetch(this.baseURL+path, {...options, agent:this.agent});
  }
}

Request Compression

import zlib from 'zlib';
class CompressedEventBatcher {
  constructor(monitor) {
    this.monitor = monitor;
    this.zlib = zlib;
  }
  async sendCompressedBatch(events) {
    const payload = JSON.stringify({events});
    if (payload.length>10240) {
      const compressed = await this.compressData(payload);
      return this.monitor.makeRequest('/api/events/batch',{method:'POST',headers:{'Content-Type':'application/json','Content-Encoding':'gzip'},body:compressed});
    }
    return this.monitor.makeRequest('/api/events/batch',{method:'POST',headers:{'Content-Type':'application/json'},body:payload});
  }
  compressData(data){return new Promise((res,rej)=>this.zlib.gzip(data,(e,c)=>e?rej(e):res(c)));}
}

Regional Endpoints

class RegionalEndpointManager {
  constructor(primary, fallbacks=[]) { this.endpoints=[primary,...fallbacks]; this.current=0; this.health=new Map(); this.startHealthChecking(); }
  getCurrentEndpoint(){return this.endpoints[this.current];}
  async makeRequest(path,options,retries=3){
    for(let i=0;i<retries;i++){const ep=this.getCurrentEndpoint();
      try{const res=await fetch(ep+path,options);
        if(res.ok){this.health.set(ep,{healthy:true,lastCheck:Date.now()});return res;}throw new Error(`HTTP ${res.status}`);
      }catch(err){this.health.set(ep,{healthy:false,lastCheck:Date.now()}); if(i<retries-1){this.current=(this.current+1)%this.endpoints.length;await this.delay(2**i*1000);}else throw err;}
    }
  }
  delay(ms){return new Promise(r=>setTimeout(r,ms));}
  startHealthChecking(){setInterval(()=>this.endpoints.forEach(async ep=>{try{await fetch(ep+'/health',{method:'HEAD',timeout:5000});this.health.set(ep,{healthy:true,lastCheck:Date.now()});}catch{this.health.set(ep,{healthy:false,lastCheck:Date.now()});}}),60000);}
}

Performance Monitoring

Metrics Collection

class PerformanceMonitor {
  constructor(monitor) {
    this.monitor = monitor;
    this.metrics = { eventThroughput:new Map(), latencyStats:[], errorRates:new Map(), batchEfficiency:[], memoryUsage:[] };
    this.startMetricsCollection();
  }

  startMetricsCollection() { setInterval(()=>this.collectMetrics(), 30000); }
  collectMetrics() {
    const now=Date.now(); this.collectThroughput(now); this.collectMemory(now); this.collectBatch(now); this.cleanup(now);
  }
  collectThroughput(ts) {
    const window=Math.floor(ts/60000);
    this.metrics.eventThroughput.set(window,(this.metrics.eventThroughput.get(window)||0)+1);
  }
  collectMemory(ts) { const u=process.memoryUsage(); this.metrics.memoryUsage.push({timestamp:ts,heapUsed:u.heapUsed,heapTotal:u.heapTotal,external:u.external,rss:u.rss}); }
  collectBatch(ts) { const size=this.monitor.eventBatcher?.getCurrentBatchSize()||0; const ratio=size/this.monitor.config.batchSize; this.metrics.batchEfficiency.push({timestamp:ts,batchSize:size,fillRatio:ratio,efficiency:ratio>0.8?'good':ratio>0.5?'medium':'poor'}); }
  recordLatency(op,lat){this.metrics.latencyStats.push({timestamp:Date.now(),operation:op,latency:lat});}
  recordError(type){const m=Math.floor(Date.now()/60000);const k=`${m}-${type}`;this.metrics.errorRates.set(k,(this.metrics.errorRates.get(k)||0)+1);}
  getPerformanceReport(){
    const now=Date.now();const lastHour=now-3600000;
    return { throughput:this.calculateThroughput(lastHour), latency:this.calculateLatency(lastHour), errorRate:this.calculateErrorRate(lastHour), memoryTrend:this.calculateMemoryTrend(lastHour), batchEfficiency:this.calculateBatchEfficiency(lastHour) };
  }
  calculateThroughput(since){ const windows=Array.from(this.metrics.eventThroughput.entries()).filter(([w])=>w*60000>=since); const total=windows.reduce((s,[,c])=>s+c,0); return {eventsPerSecond:total/((Date.now()-since)/1000), totalEvents:total}; }
  calculateLatency(since){ const arr=this.metrics.latencyStats.filter(s=>s.timestamp>=since).map(s=>s.latency).sort((a,b)=>a-b); if(!arr.length) return null; const get=(p)=>arr[Math.floor(arr.length*p)]; return {min:arr[0], max:arr[arr.length-1], median:get(0.5), p95:get(0.95), p99:get(0.99), average:arr.reduce((a,b)=>a+b,0)/arr.length}; }
  calculateErrorRate(since){ return Array.from(this.metrics.errorRates.values()).reduce((a,b)=>a+b,0)/((Date.now()-since)/60000)||0; }
  calculateMemoryTrend(since){ return this.metrics.memoryUsage.filter(m=>m.timestamp>=since); }
  calculateBatchEfficiency(since){ return this.metrics.batchEfficiency.filter(b=>b.timestamp>=since); }
  cleanup(now){ const hr=now-3600000; this.metrics.latencyStats=this.metrics.latencyStats.filter(s=>s.timestamp>=hr); this.metrics.memoryUsage=this.metrics.memoryUsage.filter(m=>m.timestamp>=hr); this.metrics.batchEfficiency=this.metrics.batchEfficiency.filter(b=>b.timestamp>=hr); }
}

Getting Started

Core Features

Integrations

Examples

Performance Overview

Default Performance Characteristics

Performance Bottlenecks

Batch Configuration Optimization

High-Throughput Configuration

Low-Latency Configuration

Balanced Configuration

Memory Optimization

Memory-Efficient Event Tracking

Memory Pool Pattern

CPU Optimization

Async Processing Patterns

Compliance Rule Optimization

Network Optimization

Connection Pooling

Request Compression

Regional Endpoints

Performance Monitoring

Metrics Collection

​Performance Overview

​Default Performance Characteristics

​Performance Bottlenecks

​Batch Configuration Optimization

​High-Throughput Configuration

​Low-Latency Configuration

​Balanced Configuration

​Memory Optimization

​Memory-Efficient Event Tracking

​Memory Pool Pattern

​CPU Optimization

​Async Processing Patterns

​Compliance Rule Optimization

​Network Optimization

​Connection Pooling

​Request Compression

​Regional Endpoints

​Performance Monitoring

​Metrics Collection

Performance Overview

Default Performance Characteristics

Performance Bottlenecks

Batch Configuration Optimization

High-Throughput Configuration

Low-Latency Configuration

Balanced Configuration

Memory Optimization

Memory-Efficient Event Tracking

Memory Pool Pattern

CPU Optimization

Async Processing Patterns

Compliance Rule Optimization

Network Optimization

Connection Pooling

Request Compression

Regional Endpoints

Performance Monitoring

Metrics Collection