Basic Usage Examples

This page provides practical examples for common use cases with the AI Agents House SDK. These examples demonstrate the core functionality with minimal setup.

Simple Agent Monitoring

Here’s the most basic example of monitoring an AI agent:

import { AgentMonitor } from '@agent-governance/node';

async function basicExample() {
  // 1. Initialize the monitor
  const monitor = new AgentMonitor({
    apiKey: 'your-governance-api-key',
    organizationId: 'your-org-id',
    environment: 'development',
    enableComplianceChecks: true,
  });

  // 2. Register your agent
  await monitor.registerAgent({
    id: 'test-agent',
    name: 'Test Agent',
    category: 'persona',
    version: '1.0.0',
    llmProvider: 'anthropic',
    model: 'claude-3-5-sonnet-20241022',
    description: 'Basic test agent for demonstration',
  });

  // 3. Track a simple conversation
  const sessionId = 'session-' + Date.now();
  monitor.trackConversationStart('test-agent', sessionId);
  monitor.trackUserMessage('test-agent', sessionId, 'Hello, how are you?');
  monitor.trackAgentResponse('test-agent', sessionId, 'I am doing well, thank you for asking!');
  monitor.trackConversationEnd('test-agent', sessionId, {
    duration: 5000,
    messageCount: 2,
    resolutionStatus: 'resolved'
  });

  // 4. Clean shutdown
  await monitor.shutdown();
  console.log('✅ Basic example complete');
}

basicExample().catch(console.error);

Banking Customer Service Example

A more realistic example for a banking customer service agent:

import { AgentMonitor } from '@agent-governance/node';

async function bankingServiceExample() {
  const monitor = new AgentMonitor({
    apiKey: process.env.AGENT_GOVERNANCE_API_KEY,
    organizationId: process.env.AGENT_GOVERNANCE_ORG_ID,
    environment: 'production',
    enableComplianceChecks: true,
    batchSize: 50,
    flushInterval: 10000
  });

  // Register banking customer service agent
  await monitor.registerAgent({
    id: 'customer-service-agent',
    name: 'Banking Customer Service Assistant',
    category: 'tool_calling',
    specialty: 'customer_service',
    version: '2.1.0',
    llmProvider: 'anthropic',
    model: 'claude-3-5-sonnet-20241022',
    description: 'AI assistant for general banking customer service inquiries',
    availableTools: [
      {
        name: 'get_account_info',
        description: 'Retrieves basic account information',
        category: 'banking',
        riskLevel: 'medium'
      },
      {
        name: 'check_transaction_history',
        description: 'Reviews recent transaction history',
        category: 'banking',
        riskLevel: 'medium'
      }
    ],
    complianceSettings: {
      sr11_7_enabled: true,
      fair_lending_monitoring: true,
      bsa_aml_checks: true
    }
  });

  // Simulate a customer interaction
  const sessionId = `cs-session-${Date.now()}`;
  const customerId = 'customer-12345';

  // Start conversation
  monitor.trackConversationStart('customer-service-agent', sessionId, customerId, {
    channel: 'web_chat',
    userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
    customerTier: 'premium'
  });

  // Customer asks about their account
  monitor.trackUserMessage(
    'customer-service-agent',
    sessionId,
    'Hi, I need to check my recent transactions and account balance.',
    customerId,
    {
      messageLength: 62,
      sentiment: 'neutral'
    }
  );

  // Agent calls a tool to get account info
  monitor.trackToolCall(
    'customer-service-agent',
    sessionId,
    'get_account_info',
    { customerId: customerId, includeBalance: true },
    {
      accountType: 'checking',
      balance: 2547.83,
      currency: 'USD',
      status: 'active'
    },
    245 // execution time in ms
  );

  // Agent responds with account information
  monitor.trackAgentResponse(
    'customer-service-agent',
    sessionId,
    'I can see your checking account is active with a current balance of $2,547.83. Would you like me to show you your recent transactions?',
    {
      llmLatency: 850,
      tokensUsed: { input: 125, output: 45, total: 170 },
      responseQuality: 88,
      containsAccountInfo: true
    }
  );

  // Customer asks for transaction history
  monitor.trackUserMessage(
    'customer-service-agent',
    sessionId,
    'Yes, please show me transactions from the last week.',
    customerId
  );

  // Agent calls another tool
  monitor.trackToolCall(
    'customer-service-agent',
    sessionId,
    'check_transaction_history',
    { customerId: customerId, days: 7 },
    {
      transactions: [
        { date: '2024-01-20', amount: -45.67, description: 'Grocery Store' },
        { date: '2024-01-18', amount: 2500.00, description: 'Direct Deposit' },
        { date: '2024-01-17', amount: -120.00, description: 'Utility Payment' }
      ],
      transactionCount: 3
    },
    380
  );

  // Agent provides transaction summary
  monitor.trackAgentResponse(
    'customer-service-agent',
    sessionId,
    'Here are your transactions from the last week: Direct deposit of $2,500.00, utility payment of $120.00, and a grocery purchase of $45.67. Is there anything specific about these transactions you\'d like to know more about?',
    {
      llmLatency: 920,
      tokensUsed: { input: 200, output: 65, total: 265 },
      responseQuality: 92,
      containsTransactionData: true
    }
  );

  // Customer is satisfied
  monitor.trackUserMessage(
    'customer-service-agent',
    sessionId,
    'Thank you, that\'s exactly what I needed!',
    customerId,
    { sentiment: 'positive' }
  );

  // End conversation
  monitor.trackConversationEnd('customer-service-agent', sessionId, {
    duration: 120000, // 2 minutes
    messageCount: 5,
    userSatisfaction: 9,
    resolutionStatus: 'resolved',
    endReason: 'user_initiated',
    followUpRequired: false
  });

  await monitor.shutdown();
  console.log('✅ Banking service example complete');
}

bankingServiceExample().catch(console.error);

Error Handling Example

Demonstrating proper error handling and recovery:

import { AgentMonitor } from '@agent-governance/node';

async function errorHandlingExample() {
  const monitor = new AgentMonitor({
    apiKey: process.env.AGENT_GOVERNANCE_API_KEY,
    organizationId: process.env.AGENT_GOVERNANCE_ORG_ID,
    environment: 'development',
    enableLogging: true,
    logLevel: 'debug'
  });

  try {
    // Register agent with error handling
    await monitor.registerAgent({
      id: 'error-demo-agent',
      name: 'Error Demonstration Agent',
      category: 'tool_calling',
      version: '1.0.0',
      llmProvider: 'anthropic',
      model: 'claude-3-5-sonnet-20241022',
      description: 'Agent for demonstrating error handling'
    });

    const sessionId = 'error-demo-session';
    monitor.trackConversationStart('error-demo-agent', sessionId);

    // Simulate a user message
    monitor.trackUserMessage('error-demo-agent', sessionId, 'Can you help me transfer money?');

    // Simulate a tool call that fails
    try {
      // This would be your actual tool call
      throw new Error('Banking API connection timeout');
    } catch (toolError) {
      // Track the error with detailed context
      monitor.trackError('error-demo-agent', sessionId, toolError, {
        errorType: 'ToolExecutionError',
        errorCode: 'BANK_API_TIMEOUT',
        severity: 'high',
        recoverable: true,
        userImpact: 'moderate',
        systemImpact: 'minimal',
        errorSource: 'external',
        toolName: 'transfer_funds',
        originalError: {
          message: toolError.message,
          stack: toolError.stack
        }
      });

      // Agent provides fallback response
      monitor.trackAgentResponse(
        'error-demo-agent',
        sessionId,
        'I apologize, but I\'m experiencing a temporary connection issue with our banking systems. Please try again in a few moments, or I can help you with other account inquiries.',
        {
          isErrorRecovery: true,
          fallbackResponse: true,
          llmLatency: 450
        }
      );
    }

    // End conversation with error context
    monitor.trackConversationEnd('error-demo-agent', sessionId, {
      duration: 30000,
      messageCount: 3,
      resolutionStatus: 'unresolved',
      endReason: 'error',
      escalationRequired: true,
      errorOccurred: true
    });

  } catch (registrationError) {
    console.error('Failed to register agent:', registrationError.message);
    // Application continues with monitoring disabled
  }

  await monitor.shutdown();
  console.log('✅ Error handling example complete');
}

errorHandlingExample().catch(console.error);

Configuration Examples

Different configurations for various environments:

Development Environment

const developmentMonitor = new AgentMonitor({
  apiKey: 'dev-api-key',
  organizationId: 'dev-org',
  environment: 'development',
  enableLogging: true,
  logLevel: 'debug',
  batchSize: 5,         // Small batches for testing
  flushInterval: 1000,  // Frequent flushes for immediate feedback
  enableComplianceChecks: true,
  retryAttempts: 1      // Fail fast in development
});

Staging Environment

const stagingMonitor = new AgentMonitor({
  apiKey: process.env.STAGING_API_KEY,
  organizationId: process.env.STAGING_ORG_ID,
  environment: 'staging',
  enableLogging: true,
  logLevel: 'info',
  batchSize: 50,        // Medium batches
  flushInterval: 5000,  // Balanced flush interval
  enableComplianceChecks: true,
  retryAttempts: 3
});

Production Environment

const productionMonitor = new AgentMonitor({
  apiKey: process.env.AGENT_GOVERNANCE_API_KEY,
  organizationId: process.env.AGENT_GOVERNANCE_ORG_ID,
  environment: 'production',
  enableLogging: false, // Disable verbose logging
  logLevel: 'error',    // Only log errors
  batchSize: 500,       // Large batches for efficiency
  flushInterval: 30000, // Less frequent flushes
  enableComplianceChecks: true,
  retryAttempts: 5,     // More retries for reliability
  retryDelay: 2000
});

Multi-Agent Environment

Example of monitoring multiple agents in a single application:

import { AgentMonitor } from '@agent-governance/node';

async function multiAgentExample() {
  const monitor = new AgentMonitor({
    apiKey: process.env.AGENT_GOVERNANCE_API_KEY,
    organizationId: process.env.AGENT_GOVERNANCE_ORG_ID,
    environment: 'production',
    enableComplianceChecks: true
  });

  // Register multiple agents
  const agents = [
    {
      id: 'personal-banking-agent',
      name: 'Personal Banking Assistant',
      specialty: 'personal_banking'
    },
    {
      id: 'business-banking-agent',
      name: 'Business Banking Assistant',
      specialty: 'business_banking'
    },
    {
      id: 'fraud-detection-agent',
      name: 'Fraud Detection Assistant',
      specialty: 'fraud_detection'
    }
  ];

  for (const agent of agents) {
    await monitor.registerAgent({
      ...agent,
      category: 'tool_calling',
      version: '1.0.0',
      llmProvider: 'anthropic',
      model: 'claude-3-5-sonnet-20241022',
      description: `AI assistant for ${agent.specialty.replace('_', ' ')}`,
      complianceSettings: {
        sr11_7_enabled: true,
        fair_lending_monitoring: agent.specialty.includes('lending'),
        bsa_aml_checks: true
      }
    });
  }

  // Simulate interactions for different agents
  const sessions = [
    { agentId: 'personal-banking-agent', sessionId: 'pb-001', userId: 'customer-123' },
    { agentId: 'business-banking-agent', sessionId: 'bb-001', userId: 'business-456' },
    { agentId: 'fraud-detection-agent', sessionId: 'fd-001', userId: 'system' }
  ];

  for (const session of sessions) {
    monitor.trackConversationStart(session.agentId, session.sessionId, session.userId);

    monitor.trackUserMessage(
      session.agentId,
      session.sessionId,
      `Hello, I need help with ${session.agentId.split('-')[0]} banking.`
    );

    monitor.trackAgentResponse(
      session.agentId,
      session.sessionId,
      `I'm here to help with your ${session.agentId.split('-')[0]} banking needs.`,
      { llmLatency: Math.random() * 1000 + 500 }
    );
  }

  await monitor.shutdown();
  console.log('✅ Multi-agent example complete');
}

multiAgentExample().catch(console.error);

Batch Processing Example

Handling high-volume events efficiently:

import { AgentMonitor } from '@agent-governance/node';

async function batchProcessingExample() {
  const monitor = new AgentMonitor({
    apiKey: process.env.AGENT_GOVERNANCE_API_KEY,
    organizationId: process.env.AGENT_GOVERNANCE_ORG_ID,
    environment: 'production',
    batchSize: 1000,      // Large batch size
    flushInterval: 60000, // 1 minute intervals
    enableLogging: false  // Disable logging for performance
  });

  await monitor.registerAgent({
    id: 'high-volume-agent',
    name: 'High Volume Processing Agent',
    category: 'autonomous',
    version: '1.0.0',
    llmProvider: 'anthropic',
    model: 'claude-3-5-sonnet-20241022',
    description: 'Agent for high-volume transaction processing'
  });

  // Simulate processing many transactions
  const batchSize = 100;
  for (let batch = 0; batch < 10; batch++) {
    console.log(`Processing batch ${batch + 1}/10`);

    for (let i = 0; i < batchSize; i++) {
      const sessionId = `batch-${batch}-session-${i}`;
      const customerId = `customer-${1000 + i}`;

      monitor.trackConversationStart('high-volume-agent', sessionId, customerId);

      monitor.trackUserMessage(
        'high-volume-agent',
        sessionId,
        `Transaction request #${batch * batchSize + i}`,
        customerId
      );

      // Simulate tool call for transaction processing
      monitor.trackToolCall(
        'high-volume-agent',
        sessionId,
        'process_transaction',
        { transactionId: `txn-${batch}-${i}`, amount: Math.random() * 1000 },
        { status: 'completed', confirmationNumber: `conf-${Date.now()}-${i}` },
        Math.random() * 200 + 50
      );

      monitor.trackAgentResponse(
        'high-volume-agent',
        sessionId,
        'Transaction processed successfully.',
        { processingTime: Math.random() * 500 + 100 }
      );

      monitor.trackConversationEnd('high-volume-agent', sessionId, {
        duration: Math.random() * 10000 + 5000,
        messageCount: 2,
        resolutionStatus: 'resolved'
      });
    }

    // Force flush every few batches to manage memory
    if (batch % 3 === 0) {
      await monitor.flush();
      console.log(`Flushed events after batch ${batch + 1}`);
    }
  }

  await monitor.shutdown();
  console.log('✅ Batch processing example complete');
}

batchProcessingExample().catch(console.error);

Testing and Development Helper

Utility functions for testing and development:

import { AgentMonitor } from '@agent-governance/node';

class AgentMonitorTestHelper {
  constructor(config = {}) {
    this.monitor = new AgentMonitor({
      apiKey: config.apiKey || 'test-api-key',
      organizationId: config.organizationId || 'test-org',
      environment: 'development',
      enableLogging: config.enableLogging !== false,
      logLevel: config.logLevel || 'debug',
      batchSize: config.batchSize || 5,
      flushInterval: config.flushInterval || 1000,
      ...config
    });
  }

  async setupTestAgent(agentId = 'test-agent') {
    await this.monitor.registerAgent({
      id: agentId,
      name: 'Test Agent',
      category: 'persona',
      version: '1.0.0-test',
      llmProvider: 'anthropic',
      model: 'claude-3-5-sonnet-20241022',
      description: 'Agent for testing purposes'
    });
    return agentId;
  }

  createTestSession(agentId = 'test-agent') {
    const sessionId = `test-session-${Date.now()}-${Math.random().toString(36).slice(2)}`;
    this.monitor.trackConversationStart(agentId, sessionId);
    return sessionId;
  }

  simulateConversation(agentId, sessionId, messageCount = 3) {
    for (let i = 0; i < messageCount; i++) {
      this.monitor.trackUserMessage(
        agentId,
        sessionId,
        `Test user message ${i + 1}`
      );

      this.monitor.trackAgentResponse(
        agentId,
        sessionId,
        `Test agent response ${i + 1}`,
        {
          llmLatency: Math.random() * 1000 + 200,
          tokensUsed: {
            input: Math.floor(Math.random() * 100 + 10),
            output: Math.floor(Math.random() * 150 + 20),
            total: Math.floor(Math.random() * 250 + 30)
          }
        }
      );
    }
  }

  async cleanup() {
    await this.monitor.shutdown();
  }
}

// Usage example
async function testingExample() {
  const helper = new AgentMonitorTestHelper({
    enableLogging: true,
    logLevel: 'debug'
  });

  try {
    const agentId = await helper.setupTestAgent('my-test-agent');
    const sessionId = helper.createTestSession(agentId);

    helper.simulateConversation(agentId, sessionId, 5);

    // Simulate an error
    helper.monitor.trackError(agentId, sessionId, new Error('Test error'), {
      errorType: 'TestError',
      severity: 'low'
    });

    // End the conversation
    helper.monitor.trackConversationEnd(agentId, sessionId, {
      duration: 30000,
      messageCount: 10,
      resolutionStatus: 'resolved'
    });

    console.log('✅ Test simulation complete');
  } finally {
    await helper.cleanup();
  }
}

testingExample().catch(console.error);

Environment Configuration

Example of using environment variables for different deployment scenarios:

// config/monitoring.js
import { AgentMonitor } from '@agent-governance/node';

function createMonitor() {
  const config = {
    apiKey: process.env.AGENT_GOVERNANCE_API_KEY,
    organizationId: process.env.AGENT_GOVERNANCE_ORG_ID,
    environment: process.env.NODE_ENV || 'development'
  };

  // Environment-specific configurations
  switch (config.environment) {
    case 'production':
      Object.assign(config, {
        enableLogging: false,
        logLevel: 'error',
        batchSize: 1000,
        flushInterval: 30000,
        retryAttempts: 5
      });
      break;

    case 'staging':
      Object.assign(config, {
        enableLogging: true,
        logLevel: 'info',
        batchSize: 100,
        flushInterval: 10000,
        retryAttempts: 3
      });
      break;

    case 'development':
    default:
      Object.assign(config, {
        enableLogging: true,
        logLevel: 'debug',
        batchSize: 10,
        flushInterval: 2000,
        retryAttempts: 1
      });
      break;
  }

  return new AgentMonitor(config);
}

module.exports = { createMonitor };

Next Steps

Banking Assistant Example

Complete banking use case with multiple agents and workflows

Compliance Monitoring

Examples of compliance detection and custom rules

Anthropic Integration

Automatic monitoring with Claude API wrapper

Performance Guide

Optimization for high-volume scenarios

All examples in this guide are available in the SDK repository under the examples/ directory. You can run them directly with Node.js after installing the SDK.

Getting Started

Core Features

Integrations

Examples

Simple Agent Monitoring

Banking Customer Service Example

Error Handling Example

Configuration Examples

Development Environment

Staging Environment

Production Environment

Multi-Agent Environment

Batch Processing Example

Testing and Development Helper

Environment Configuration

Next Steps

Banking Assistant Example

Compliance Monitoring

Anthropic Integration

Performance Guide

​Simple Agent Monitoring

​Banking Customer Service Example

​Error Handling Example

​Configuration Examples

​Development Environment

​Staging Environment

​Production Environment

​Multi-Agent Environment

​Batch Processing Example

​Testing and Development Helper

​Environment Configuration

​Next Steps

Banking Assistant Example

Compliance Monitoring

Anthropic Integration

Performance Guide

Simple Agent Monitoring

Banking Customer Service Example

Error Handling Example

Configuration Examples

Development Environment

Staging Environment

Production Environment

Multi-Agent Environment

Batch Processing Example

Testing and Development Helper

Environment Configuration

Next Steps