The AgentMonitor class is the core component of the Agent Governance SDK, providing comprehensive monitoring capabilities for AI agents. It handles event tracking, agent registration, compliance monitoring, and data transmission to the Agent Governance platform.
Constructor AgentMonitor(config) Creates a new instance of the AgentMonitor with the specified configuration.
config
AgentMonitoringConfig
required
Configuration object for the monitor instance. Show Configuration Properties
Your Agent Governance API key for authentication.
Your organization identifier in the Agent Governance platform.
endpoint
string
default: "https://api.aiagentshouse.com"
The API endpoint for the Agent Governance platform.
environment
'production' | 'staging' | 'development'
default: "production"
The environment designation for your deployment.
Number of events to batch before sending (1-1000).
Time in milliseconds between automatic flushes (minimum 100).
Whether to enable real-time compliance monitoring.
Whether to enable SDK logging output.
logLevel
'debug' | 'info' | 'warn' | 'error'
default: "info"
The minimum log level to output.
Number of retry attempts for failed requests (0-10).
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.
Agent information and configuration. Unique identifier for the agent within your organization.
Human-readable name for the agent.
Type of agent: ‘persona’, ‘tool_calling’, ‘workflow’, or ‘autonomous’.
Banking domain specialty if applicable.
Version identifier for the agent.
The LLM provider (e.g., ‘anthropic’, ‘openai’).
The specific model being used (e.g., ‘claude-3-5-sonnet-20241022’).
Detailed description of the agent’s purpose and capabilities.
The system prompt used to initialize the agent.
Array of tools available to the agent.
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 Tracks the beginning of a new conversation session.
The ID of the agent handling the conversation.
Unique identifier for the conversation session.
Optional identifier for the user initiating the conversation.
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.
The ID of the agent receiving the message.
The conversation session identifier.
The content of the user’s message.
Optional user identifier.
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.
The ID of the responding agent.
The conversation session identifier.
The content of the agent’s response.
Optional metadata including performance and quality metrics. Show Common Metadata Fields
Time taken for LLM processing in milliseconds.
Token usage statistics: { input: number, output: number, total: number }.
Calculated cost for the LLM call.
Quality score for the response (0-100).
LLM temperature setting used.
Maximum tokens setting used.
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' } ); Tracks when an agent uses a tool or external function.
The ID of the agent making the tool call.
The conversation session identifier.
The name of the tool being called.
The parameters passed to the tool.
The result returned by the tool (if available).
Time taken to execute the tool in milliseconds.
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 } ); Tracks errors that occur during agent interactions.
The ID of the agent where the error occurred.
The conversation session identifier.
The error message or Error object.
Optional metadata with error details. Show Error Metadata Fields
Classification of the error type.
Specific error code if available.
severity
'low' | 'medium' | 'high' | 'critical'
Severity level of the error.
Whether the error is recoverable.
userImpact
'none' | 'minimal' | 'moderate' | 'high'
Impact on the user experience.
systemImpact
'none' | 'minimal' | 'moderate' | 'high'
Impact on system functionality.
errorSource
'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' } ); Tracks the end of a conversation session.
The ID of the agent ending the conversation.
The conversation session identifier.
Optional metadata with conversation summary. Show Conversation End Metadata
Total duration of the conversation in milliseconds.
Total number of messages exchanged.
User satisfaction rating (1-10 scale).
resolutionStatus
'resolved' | 'unresolved' | 'escalated' | 'abandoned'
How the conversation was resolved.
endReason
'user_initiated' | 'timeout' | 'error' | 'system_initiated'
Reason for conversation ending.
Whether follow-up action is needed.
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.
The ID of the agent associated with the event.
The event object to track. Show InteractionEvent Properties
The conversation session identifier.
The type of interaction being tracked.
Content for message and error events.
Tool name for tool-related events.
Parameters for tool calls.
Results from tool execution.
Additional metadata for the event.
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 | undefinedExample: 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
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
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
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 