AgentMonitor Class - AI Agents House SDK

The AgentMonitor class is the core component of the AI Agents House SDK, providing comprehensive monitoring capabilities for AI agents. It handles event tracking, agent registration, compliance monitoring, and data transmission to the AI Agents House platform.

Constructor

AgentMonitor(config)

Creates a new instance of the AgentMonitor with the specified configuration.

AgentMonitoringConfig

required

Configuration object for the monitor instance.

Show Configuration Properties

string

required

Your AI Agents House API key for authentication.

string

required

Your organization identifier in the AI Agents House platform.

string

default:"https://api.aiagentshouse.com"

The API endpoint for the AI Agents House platform.

'production' | 'staging' | 'development'

default:"production"

The environment designation for your deployment.

number

default:"100"

Number of events to batch before sending (1-1000).

number

default:"5000"

Time in milliseconds between automatic flushes (minimum 100).

boolean

default:"true"

Whether to enable real-time compliance monitoring.

boolean

default:"true"

Whether to enable SDK logging output.

'debug' | 'info' | 'warn' | 'error'

default:"info"

The minimum log level to output.

number

default:"3"

Number of retry attempts for failed requests (0-10).

number

default:"1000"

Base delay in milliseconds between retry attempts.

Example:

const monitor = new AgentMonitor({
  apiKey: 'your-api-key',
  organizationId: 'your-org-id',
  environment: 'production',
  enableComplianceChecks: true,
  batchSize: 250,
  flushInterval: 10000
});

Agent Registration

registerAgent(agent)

Registers an agent with the monitoring system before tracking its interactions.

AgentInfo

required

Agent information and configuration.

Show Agent Properties

string

required

Unique identifier for the agent within your organization.

string

required

Human-readable name for the agent.

AgentCategory

required

Type of agent: ‘persona’, ‘tool_calling’, ‘workflow’, or ‘autonomous’.

BankingSpecialty

Banking domain specialty if applicable.

string

required

Version identifier for the agent.

string

required

The LLM provider (e.g., ‘anthropic’, ‘openai’).

string

required

The specific model being used (e.g., ‘claude-3-5-sonnet-20241022’).

string

required

Detailed description of the agent’s purpose and capabilities.

string

The system prompt used to initialize the agent.

ToolInfo[]

Array of tools available to the agent.

ComplianceSettings

Compliance monitoring configuration for this agent.

Returns: Promise<void> Example:

await monitor.registerAgent({
  id: 'banking-assistant-v2',
  name: 'Personal Banking Assistant',
  category: 'tool_calling',
  specialty: 'personal_banking',
  version: '2.1.0',
  llmProvider: 'anthropic',
  model: 'claude-3-5-sonnet-20241022',
  description: 'AI assistant for personal banking customer service',
  availableTools: [
    {
      name: 'get_account_balance',
      description: 'Retrieves current account balance',
      category: 'banking',
      riskLevel: 'medium'
    }
  ],
  complianceSettings: {
    sr11_7_enabled: true,
    fair_lending_monitoring: true,
    bsa_aml_checks: true
  }
});

Event Tracking Methods

trackConversationStart(agentId, sessionId, userId?, metadata?)

Tracks the beginning of a new conversation session.

string

required

The ID of the agent handling the conversation.

string

required

Unique identifier for the conversation session.

string

Optional identifier for the user initiating the conversation.

object

Optional metadata object with additional context.

Example:

monitor.trackConversationStart(
  'banking-assistant',
  'session-12345',
  'customer-67890',
  {
    userAgent: 'Mozilla/5.0...',
    ipAddress: '192.168.1.100',
    referrer: 'https://mybank.com/login'
  }
);

trackUserMessage(agentId, sessionId, content, userId?, metadata?)

Tracks a message from the user to the agent.

string

required

The ID of the agent receiving the message.

string

required

The conversation session identifier.

string

required

The content of the user’s message.

string

Optional user identifier.

object

Optional metadata with additional context.

Example:

monitor.trackUserMessage(
  'banking-assistant',
  'session-12345',
  'Can you help me check my account balance?',
  'customer-67890',
  {
    messageId: 'msg-001',
    channel: 'web_chat',
    customerTier: 'premium'
  }
);

trackAgentResponse(agentId, sessionId, content, metadata?, options?)

Tracks a response from the agent to the user.

string

required

The ID of the responding agent.

string

required

The conversation session identifier.

string

required

The content of the agent’s response.

object

Optional metadata including performance and quality metrics.

Show Common Metadata Fields

number

Time taken for LLM processing in milliseconds.

TokenUsage

Token usage statistics: { input: number, output: number, total: number }.

number

Calculated cost for the LLM call.

number

Quality score for the response (0-100).

number

LLM temperature setting used.

number

Maximum tokens setting used.

MonitoringOptions

Optional monitoring configuration for this specific interaction.

Example:

monitor.trackAgentResponse(
  'banking-assistant',
  'session-12345',
  'Your current checking account balance is $2,547.83.',
  {
    llmLatency: 850,
    tokensUsed: { input: 125, output: 67, total: 192 },
    cost: 0.0034,
    responseQuality: 92,
    temperature: 0.7
  },
  {
    agentCategory: 'tool_calling',
    agentSpecialty: 'personal_banking'
  }
);

trackToolCall(agentId, sessionId, toolName, parameters, result?, executionTime?, metadata?)

Tracks when an agent uses a tool or external function.

string

required

The ID of the agent making the tool call.

string

required

The conversation session identifier.

string

required

The name of the tool being called.

any

required

The parameters passed to the tool.

any

The result returned by the tool (if available).

number

Time taken to execute the tool in milliseconds.

object

Optional metadata with additional context.

Example:

monitor.trackToolCall(
  'banking-assistant',
  'session-12345',
  'get_account_balance',
  { accountId: 'acc_123', accountType: 'checking' },
  { balance: 2547.83, currency: 'USD', lastUpdated: '2024-01-15' },
  245,
  {
    toolVersion: '1.2.0',
    cacheHit: false
  }
);

trackError(agentId, sessionId, error, metadata?)

Tracks errors that occur during agent interactions.

string

required

The ID of the agent where the error occurred.

string

required

The conversation session identifier.

string | Error

required

The error message or Error object.

object

Optional metadata with error details.

Show Error Metadata Fields

string

Classification of the error type.

string

Specific error code if available.

'low' | 'medium' | 'high' | 'critical'

Severity level of the error.

boolean

Whether the error is recoverable.

'none' | 'minimal' | 'moderate' | 'high'

Impact on the user experience.

'none' | 'minimal' | 'moderate' | 'high'

Impact on system functionality.

'client' | 'server' | 'external' | 'unknown'

Source of the error.

Example:

monitor.trackError(
  'banking-assistant',
  'session-12345',
  new Error('Failed to connect to banking API'),
  {
    errorType: 'APIConnectionError',
    errorCode: 'BANK_API_001',
    severity: 'high',
    recoverable: true,
    userImpact: 'moderate',
    systemImpact: 'minimal',
    errorSource: 'external'
  }
);

trackConversationEnd(agentId, sessionId, metadata?)

Tracks the end of a conversation session.

string

required

The ID of the agent ending the conversation.

string

required

The conversation session identifier.

object

Optional metadata with conversation summary.

Show Conversation End Metadata

number

Total duration of the conversation in milliseconds.

number

Total number of messages exchanged.

number

User satisfaction rating (1-10 scale).

'resolved' | 'unresolved' | 'escalated' | 'abandoned'

How the conversation was resolved.

'user_initiated' | 'timeout' | 'error' | 'system_initiated'

Reason for conversation ending.

boolean

Whether follow-up action is needed.

string

Reason for escalation if applicable.

Example:

monitor.trackConversationEnd(
  'banking-assistant',
  'session-12345',
  {
    duration: 180000, // 3 minutes
    messageCount: 6,
    userSatisfaction: 9,
    resolutionStatus: 'resolved',
    endReason: 'user_initiated',
    followUpRequired: false
  }
);

track(agentId, event, options?)

Generic method for tracking any type of interaction event.

string

required

The ID of the agent associated with the event.

InteractionEvent

required

The event object to track.

Show InteractionEvent Properties

string

required

The conversation session identifier.

EventType

required

The type of interaction being tracked.

string

Content for message and error events.

string

Tool name for tool-related events.

any

Parameters for tool calls.

any

Results from tool execution.

object

Additional metadata for the event.

MonitoringOptions

Optional monitoring configuration.

Example:

monitor.track(
  'banking-assistant',
  {
    sessionId: 'session-12345',
    interactionType: 'compliance_violation',
    metadata: {
      violationType: 'fair_lending',
      severity: 'warning',
      description: 'Potential discriminatory language detected',
      ruleId: 'fair_lending_001'
    }
  }
);

Utility Methods

flush()

Forces immediate transmission of all pending events to the platform. Returns: Promise<void> Example:

// Add some events
monitor.trackUserMessage('agent-1', 'session-1', 'Hello');
monitor.trackAgentResponse('agent-1', 'session-1', 'Hi there!');

// Force immediate send
await monitor.flush();

shutdown()

Gracefully shuts down the monitor, flushing any remaining events and cleaning up resources. Returns: Promise<void> Example:

// At application shutdown
process.on('SIGTERM', async () => {
  await monitor.shutdown();
  process.exit(0);
});

Properties

complianceEngine

Access to the compliance engine instance (if enabled). Type: ComplianceEngine | undefined Example:

if (monitor.complianceEngine) {
  monitor.complianceEngine.addRule({
    id: 'custom-rule',
    name: 'Custom Banking Rule',
    description: 'Custom compliance check',
    category: 'custom',
    severity: 'warning',
    isActive: true,
    ruleFunction: (context) => {
      // Custom rule logic
      return {
        isCompliant: true,
        violations: [],
        riskScore: 0,
        requiresReview: false
      };
    }
  });
}

Error Handling

The AgentMonitor class handles errors gracefully and provides detailed error information:

try {
  await monitor.registerAgent(agentInfo);
} catch (error) {
  console.error('Failed to register agent:', error.message);
  // Continue with application logic
}

// Tracking errors are logged but don't throw
monitor.trackUserMessage('agent-1', 'invalid-session-!@#', 'Hello');
// Logs validation error but continues execution

Best Practices

Event Tracking

Use consistent session IDs across related interactions
Include relevant metadata for better analytics
Track errors with sufficient context for debugging
Use meaningful agent IDs and descriptions

Performance

Configure appropriate batch sizes for your volume
Use suitable flush intervals based on latency requirements
Monitor memory usage with large event volumes
Call shutdown() during application cleanup

Error Handling

Wrap critical operations in try-catch blocks
Monitor failed requests and adjust retry settings
Use graceful degradation when monitoring fails
Log monitoring errors for debugging

Configuration

Use environment variables for sensitive configuration
Adjust settings based on deployment environment
Enable compliance checks for regulated environments
Configure logging appropriately for each environment

Next Steps

Compliance Engine

Learn about the ComplianceEngine class and custom rules

Type Definitions

Complete TypeScript type definitions

Integration Examples

Practical examples and integration patterns

Performance Guide

Optimization strategies for high-volume scenarios

​Constructor

​AgentMonitor(config)

​Agent Registration

​registerAgent(agent)

​Event Tracking Methods

​trackConversationStart(agentId, sessionId, userId?, metadata?)

​trackUserMessage(agentId, sessionId, content, userId?, metadata?)

​trackAgentResponse(agentId, sessionId, content, metadata?, options?)

​trackToolCall(agentId, sessionId, toolName, parameters, result?, executionTime?, metadata?)

​trackError(agentId, sessionId, error, metadata?)

​trackConversationEnd(agentId, sessionId, metadata?)

​track(agentId, event, options?)

​Utility Methods

​flush()

​shutdown()

​Properties

​complianceEngine

​Error Handling

​Best Practices

​Next Steps

Compliance Engine

Type Definitions

Integration Examples

Performance Guide

Constructor

AgentMonitor(config)

Agent Registration

registerAgent(agent)

Event Tracking Methods

trackConversationStart(agentId, sessionId, userId?, metadata?)

trackUserMessage(agentId, sessionId, content, userId?, metadata?)

trackAgentResponse(agentId, sessionId, content, metadata?, options?)

trackToolCall(agentId, sessionId, toolName, parameters, result?, executionTime?, metadata?)

trackError(agentId, sessionId, error, metadata?)

trackConversationEnd(agentId, sessionId, metadata?)

track(agentId, event, options?)

Utility Methods

flush()

shutdown()

Properties

complianceEngine

Error Handling

Best Practices

Next Steps