Core Configuration Types
AgentMonitoringConfig
Main configuration interface for the AgentMonitor class.interface AgentMonitoringConfig {
apiKey: string; // Required: Your governance API key
organizationId: string; // Required: Your organization ID
endpoint?: string; // Optional: Custom API endpoint
environment?: Environment; // Optional: Deployment environment
batchSize?: number; // Optional: Events per batch (1-1000)
flushInterval?: number; // Optional: Flush interval in ms (min 100)
enableComplianceChecks?: boolean; // Optional: Enable compliance monitoring
enableLogging?: boolean; // Optional: Enable SDK logging
logLevel?: LogLevel; // Optional: Minimum log level
retryAttempts?: number; // Optional: Retry attempts (0-10)
retryDelay?: number; // Optional: Delay between retries in ms
}
type Environment = 'production' | 'staging' | 'development';
type LogLevel = 'debug' | 'info' | 'warn' | 'error';
MonitoringOptions
Optional configuration for individual interactions.interface MonitoringOptions {
requestId?: string; // Custom request identifier
userId?: string; // User identifier for the interaction
sessionId?: string; // Override session ID
agentCategory?: AgentCategory; // Agent category for this interaction
agentSpecialty?: BankingSpecialty; // Agent specialty for this interaction
trackConversationStart?: boolean; // Whether to track conversation start
complianceChecks?: boolean; // Override global compliance setting
}
Agent Types
AgentInfo
Complete agent registration information.interface AgentInfo {
id: string; // Unique agent identifier
name: string; // Human-readable agent name
category: AgentCategory; // Agent type classification
specialty?: BankingSpecialty; // Banking domain specialty
version: string; // Agent version string
llmProvider: string; // LLM provider name
model: string; // Model name/version
description: string; // Detailed agent description
systemPrompt?: string; // System prompt used
availableTools?: ToolInfo[]; // Tools available to the agent
complianceSettings?: ComplianceSettings; // Compliance configuration
}
type AgentCategory = 'persona' | 'tool_calling' | 'workflow' | 'autonomous';
type BankingSpecialty =
| 'generalist'
| 'personal_banking'
| 'business_banking'
| 'wealth_management'
| 'mortgage_lending'
| 'investment_services'
| 'fraud_detection'
| 'customer_service'
| 'compliance';
ToolInfo
Information about tools available to agents.interface ToolInfo {
name: string; // Tool name
description: string; // Tool description
category: string; // Tool category
riskLevel: RiskLevel; // Risk level for compliance
version?: string; // Tool version
parameters?: ToolParameters; // Tool parameter schema
}
type RiskLevel = 'low' | 'medium' | 'high';
interface ToolParameters {
type: 'object';
properties: Record<string, {
type: string;
description: string;
required?: boolean;
default?: any;
}>;
required?: string[];
}
ComplianceSettings
Agent-specific compliance configuration.interface ComplianceSettings {
sr11_7_enabled: boolean; // SR 11-7 model validation compliance
fair_lending_monitoring: boolean; // Fair lending compliance monitoring
bsa_aml_checks: boolean; // BSA/AML compliance checks
custom_rules?: string[]; // IDs of custom rules to apply
risk_threshold?: number; // Custom risk threshold (0-100)
}
Event Types
InteractionEvent
Generic event interface for thetrack() method.
interface InteractionEvent {
sessionId: string; // Required: Session identifier
conversationId?: string; // Optional: Conversation identifier
userId?: string; // Optional: User identifier
interactionType: EventType; // Required: Type of interaction
content?: string; // Content for message/error events
toolName?: string; // Tool name for tool events
toolParameters?: any; // Parameters for tool calls
toolResult?: any; // Results from tool execution
metadata?: EventMetadata; // Additional event metadata
// Error-specific fields (convenience for error events)
errorType?: string; // Error type classification
errorCode?: string; // Specific error code
severity?: ErrorSeverity; // Error severity level
}
type EventType =
| 'conversation_start'
| 'user_message'
| 'agent_response'
| 'tool_call'
| 'tool_result'
| 'error'
| 'conversation_end';
type ErrorSeverity = 'low' | 'medium' | 'high' | 'critical';
EventMetadata
Flexible metadata interface for events.interface EventMetadata {
// LLM Performance Metrics
llmLatency?: number; // LLM response time in ms
tokensUsed?: TokenUsage; // Token usage statistics
cost?: number; // Calculated cost for the request
temperature?: number; // LLM temperature setting
maxTokens?: number; // Maximum tokens setting
// Quality Metrics
responseQuality?: number; // Response quality score (0-100)
relevanceScore?: number; // Relevance score (0-100)
coherenceScore?: number; // Coherence score (0-100)
helpfulnessScore?: number; // Helpfulness score (0-100)
// Tool Execution
toolExecutionTime?: number; // Tool execution time in ms
toolVersion?: string; // Version of tool used
cacheHit?: boolean; // Whether result was cached
// Error Context
errorStack?: string; // Error stack trace
recoverable?: boolean; // Whether error is recoverable
userImpact?: ImpactLevel; // Impact on user experience
systemImpact?: ImpactLevel; // Impact on system functionality
errorSource?: ErrorSource; // Source of the error
originalError?: any; // Original error object
// Conversation Context
duration?: number; // Conversation duration in ms
messageCount?: number; // Total message count
userSatisfaction?: number; // User satisfaction (1-10)
resolutionStatus?: ResolutionStatus; // How conversation ended
endReason?: EndReason; // Reason for ending
followUpRequired?: boolean; // Whether follow-up is needed
escalationReason?: string; // Reason for escalation
// Business Context
customerTier?: string; // Customer tier/segment
channel?: string; // Communication channel
deviceFingerprint?: string; // Device identification
geolocation?: string; // Geographic location
// Custom fields
[key: string]: any; // Allow additional custom metadata
}
interface TokenUsage {
input: number; // Input tokens used
output: number; // Output tokens used
total: number; // Total tokens used
}
type ImpactLevel = 'none' | 'minimal' | 'moderate' | 'high';
type ErrorSource = 'client' | 'server' | 'external' | 'unknown';
type ResolutionStatus = 'resolved' | 'unresolved' | 'escalated' | 'abandoned';
type EndReason = 'user_initiated' | 'timeout' | 'error' | 'system_initiated';
Detailed Event Types
The SDK internally uses more detailed event types for specific tracking:ConversationStartEvent
interface ConversationStartEvent extends BaseEvent {
interactionType: 'conversation_start';
metadata?: {
userAgent?: string; // User's browser/client info
ipAddress?: string; // User's IP address
referrer?: string; // Referring page/application
channel?: string; // Communication channel
customerType?: string; // Type of customer
[key: string]: any;
};
}
UserMessageEvent
interface UserMessageEvent extends BaseEvent {
interactionType: 'user_message';
content: string; // The user's message content
contentHash?: string; // Hash of the content
contentLength: number; // Length of the content
metadata?: {
messageId?: string; // Unique message identifier
threadId?: string; // Thread identifier
attachments?: AttachmentInfo[]; // File attachments
sentiment?: string; // Detected sentiment
language?: string; // Detected language
[key: string]: any;
};
}
interface AttachmentInfo {
type: string; // MIME type
size: number; // File size in bytes
name: string; // Original filename
hash?: string; // File hash for integrity
}
AgentResponseEvent
interface AgentResponseEvent extends BaseEvent {
interactionType: 'agent_response';
content: string; // The agent's response content
contentHash?: string; // Hash of the content
contentLength: number; // Length of the content
llmMetadata?: LLMMetadata; // LLM-specific metadata
qualityMetrics?: QualityMetrics; // Response quality metrics
complianceFlags?: ComplianceFlag[]; // Compliance violations
riskScore?: number; // Calculated risk score
requiresReview?: boolean; // Whether human review is needed
}
interface LLMMetadata {
model: string; // Model used
provider: string; // LLM provider
latency: number; // Response latency in ms
tokensUsed: TokenUsage; // Token usage
cost?: number; // Calculated cost
temperature?: number; // Temperature setting
maxTokens?: number; // Max tokens setting
topP?: number; // Top-p sampling parameter
frequencyPenalty?: number; // Frequency penalty
presencePenalty?: number; // Presence penalty
}
interface QualityMetrics {
responseQuality: number; // Overall quality score (0-100)
relevanceScore: number; // Relevance to user query (0-100)
coherenceScore: number; // Internal coherence (0-100)
helpfulnessScore: number; // Helpfulness rating (0-100)
factualAccuracy?: number; // Factual accuracy (0-100)
completeness?: number; // Response completeness (0-100)
}
ToolCallEvent
interface ToolCallEvent extends BaseEvent {
interactionType: 'tool_call';
toolName: string; // Name of the tool called
toolParameters: any; // Parameters passed to tool
toolCategory?: string; // Category of the tool
riskLevel?: RiskLevel; // Risk level of the tool
metadata?: {
toolVersion?: string; // Version of the tool
executionContext?: string; // Execution context
timeout?: number; // Tool timeout setting
retryAttempts?: number; // Number of retry attempts
[key: string]: any;
};
}
ToolResultEvent
interface ToolResultEvent extends BaseEvent {
interactionType: 'tool_result';
toolName: string; // Name of the tool
toolResult: any; // Result from tool execution
toolError?: string; // Error message if tool failed
executionTime: number; // Execution time in ms
success: boolean; // Whether execution succeeded
metadata?: {
cacheHit?: boolean; // Whether result was cached
dataSource?: string; // Source of the data
resultSize?: number; // Size of result in bytes
retryCount?: number; // Number of retries needed
[key: string]: any;
};
}
ErrorEvent
interface ErrorEvent extends BaseEvent {
interactionType: 'error';
errorType: string; // Classification of error type
errorMessage: string; // Human-readable error message
errorStack?: string; // Stack trace if available
errorCode?: string; // Specific error code
severity: ErrorSeverity; // Severity level
recoverable: boolean; // Whether error is recoverable
metadata?: {
userImpact: ImpactLevel; // Impact on user experience
systemImpact: ImpactLevel; // Impact on system
errorSource: ErrorSource; // Source of the error
originalError?: any; // Original error object
contextInfo?: any; // Additional context
[key: string]: any;
};
}
ConversationEndEvent
interface ConversationEndEvent extends BaseEvent {
interactionType: 'conversation_end';
duration: number; // Total conversation duration in ms
messageCount: number; // Total messages exchanged
userSatisfaction?: number; // User satisfaction rating (1-10)
resolutionStatus: ResolutionStatus; // How conversation was resolved
metadata?: {
endReason: EndReason; // Reason for ending
followUpRequired: boolean; // Whether follow-up is needed
escalationReason?: string; // Reason for escalation if any
avgResponseTime?: number; // Average response time
toolCallCount?: number; // Number of tool calls made
errorCount?: number; // Number of errors encountered
[key: string]: any;
};
}
Compliance Types
ComplianceRule
Interface for defining compliance rules.interface ComplianceRule {
id: string; // Unique rule identifier
name: string; // Human-readable rule name
description: string; // Detailed rule description
category: ComplianceCategory; // Compliance category
severity: ComplianceSeverity; // Severity of violations
isActive: boolean; // Whether rule is active
ruleFunction: (context: InteractionContext) => ComplianceResult; // Rule logic
version?: string; // Rule version
createdAt?: string; // Rule creation timestamp
updatedAt?: string; // Rule last update timestamp
tags?: string[]; // Tags for organization
}
type ComplianceCategory =
| 'sr_11_7' // Model validation requirements
| 'fair_lending' // Fair lending compliance
| 'bsa_aml' // Bank Secrecy Act / Anti-Money Laundering
| 'privacy' // Privacy and PII protection
| 'consumer_protection' // Consumer protection regulations
| 'custom'; // Organization-specific rules
type ComplianceSeverity = 'info' | 'warning' | 'violation';
InteractionContext
Context provided to compliance rules for evaluation.interface InteractionContext {
agentId: string; // Agent identifier
agentCategory: AgentCategory; // Agent category
agentSpecialty?: BankingSpecialty; // Agent specialty
userMessage?: string; // User's message content
agentResponse?: string; // Agent's response content
toolsUsed?: ToolUsageInfo[]; // Tools used in interaction
userId?: string; // User identifier
sessionId: string; // Session identifier
timestamp: number; // Interaction timestamp
metadata?: any; // Additional metadata
// Extended context for banking compliance
customerProfile?: CustomerProfile; // Customer information
transactionContext?: TransactionContext; // Transaction details
riskFactors?: string[]; // Identified risk factors
}
interface ToolUsageInfo {
name: string; // Tool name
parameters: any; // Parameters used
result: any; // Result returned
executionTime?: number; // Execution time
success: boolean; // Whether execution succeeded
}
interface CustomerProfile {
customerId: string; // Customer identifier
customerTier?: string; // Customer tier/segment
riskRating?: string; // Customer risk rating
accountTypes?: string[]; // Types of accounts held
relationshipLength?: number; // Length of relationship in months
previousViolations?: number; // Number of previous violations
}
interface TransactionContext {
transactionId?: string; // Transaction identifier
amount?: number; // Transaction amount
transactionType?: string; // Type of transaction
frequency?: string; // Transaction frequency
location?: string; // Transaction location
merchantCategory?: string; // Merchant category code
}
ComplianceResult
Result returned by compliance rule evaluation.interface ComplianceResult {
isCompliant: boolean; // Overall compliance status
violations: ComplianceViolation[]; // Array of violations found
riskScore: number; // Calculated risk score (0-100)
requiresReview: boolean; // Whether human review is needed
metadata?: {
evaluationTime?: number; // Time taken to evaluate
rulesEvaluated?: number; // Number of rules checked
confidence?: number; // Confidence in result (0-1)
[key: string]: any;
};
}
interface ComplianceViolation {
rule: string; // ID of rule that detected violation
severity: ComplianceSeverity; // Severity level
description: string; // Human-readable description
context?: ViolationContext; // Additional context
recommendation?: string; // Suggested remediation
confidence?: number; // Confidence in detection (0-1)
timestamp?: number; // When violation was detected
}
interface ViolationContext {
detectedContent?: string; // Content that triggered violation
detectedPattern?: string; // Pattern that was matched
riskFactors?: string[]; // Contributing risk factors
relatedViolations?: string[]; // Related violation IDs
customerImpact?: ImpactLevel; // Impact on customer
businessImpact?: ImpactLevel; // Impact on business
regulatoryImpact?: string; // Potential regulatory impact
[key: string]: any; // Additional context fields
}
Event Batching Types
EventBatch
Structure for batched event transmission.interface EventBatch {
batchId: string; // Unique batch identifier
organizationId: string; // Organization identifier
timestamp: number; // Batch creation timestamp
events: DetailedEvent[]; // Array of events in batch
eventCount: number; // Number of events
totalSize: number; // Total size in bytes
checksum?: string; // Batch integrity checksum
metadata?: {
batchVersion?: string; // Batch format version
compressionType?: string; // Compression algorithm used
encryptionInfo?: string; // Encryption information
[key: string]: any;
};
}
type DetailedEvent =
| ConversationStartEvent
| UserMessageEvent
| AgentResponseEvent
| ToolCallEvent
| ToolResultEvent
| ErrorEvent
| ConversationEndEvent;
EventBatcherConfig
Configuration for the EventBatcher class.interface EventBatcherConfig {
batchSize: number; // Events per batch
flushInterval: number; // Flush interval in ms
onFlush: (events: DetailedEvent[]) => Promise<void>; // Flush callback
logger: Logger; // Logger instance
maxRetries?: number; // Maximum retry attempts
retryDelay?: number; // Delay between retries
compression?: boolean; // Enable compression
encryption?: EncryptionConfig; // Encryption configuration
}
interface EncryptionConfig {
enabled: boolean; // Whether encryption is enabled
algorithm?: string; // Encryption algorithm
keyId?: string; // Key identifier
}
Utility Types
BaseEvent
Base interface for all events.interface BaseEvent {
eventId: string; // Unique event identifier
timestamp: number; // Event timestamp
sessionId: string; // Session identifier
agentId: string; // Agent identifier
userId?: string; // User identifier
conversationId?: string; // Conversation identifier
environment: Environment; // Environment designation
requestId: string; // Request identifier
version?: string; // Event schema version
}
Logger
Interface for logging functionality.interface Logger {
debug(message: string, data?: any): void;
info(message: string, data?: any): void;
warn(message: string, data?: any): void;
error(message: string, data?: any): void;
}
HttpOptions
Options for HTTP requests.interface HttpOptions {
method: string; // HTTP method
headers?: Record<string, string>; // Request headers
body?: string; // Request body
timeout?: number; // Request timeout in ms
retries?: number; // Number of retry attempts
retryDelay?: number; // Delay between retries
}
Validation Types
ValidationError
Error type for validation failures.interface ValidationError extends Error {
name: 'ValidationError';
details: ValidationDetail[]; // Detailed validation errors
field?: string; // Field that failed validation
value?: any; // Value that failed validation
}
interface ValidationDetail {
field: string; // Field path
message: string; // Error message
code: string; // Error code
value?: any; // Invalid value
}
Export Summary
All types are exported from the main module:// Core configuration
export type {
AgentMonitoringConfig,
MonitoringOptions,
Environment,
LogLevel
};
// Agent types
export type {
AgentInfo,
AgentCategory,
BankingSpecialty,
ToolInfo,
RiskLevel,
ComplianceSettings
};
// Event types
export type {
InteractionEvent,
EventType,
EventMetadata,
TokenUsage,
ErrorSeverity,
ImpactLevel,
ErrorSource,
ResolutionStatus,
EndReason
};
// Detailed event types
export type {
ConversationStartEvent,
UserMessageEvent,
AgentResponseEvent,
ToolCallEvent,
ToolResultEvent,
ErrorEvent,
ConversationEndEvent,
LLMMetadata,
QualityMetrics
};
// Compliance types
export type {
ComplianceRule,
ComplianceCategory,
ComplianceSeverity,
InteractionContext,
ComplianceResult,
ComplianceViolation,
ViolationContext,
ToolUsageInfo,
CustomerProfile,
TransactionContext
};
// Utility types
export type {
BaseEvent,
EventBatch,
EventBatcherConfig,
Logger,
HttpOptions,
ValidationError,
ValidationDetail
};
Type Usage Examples
Custom Rule with Full Typing
import type { ComplianceRule, InteractionContext, ComplianceResult } from '@agent-governance/node';
const customRule: ComplianceRule = {
id: 'banking-hours-compliance',
name: 'Banking Hours Compliance',
description: 'Ensures banking hours are mentioned correctly',
category: 'consumer_protection',
severity: 'warning',
isActive: true,
ruleFunction: (context: InteractionContext): ComplianceResult => {
const violations = [];
const response = context.agentResponse || '';
if (response.includes('banking hours') && !response.includes('Monday through Friday')) {
violations.push({
rule: 'banking-hours-compliance',
severity: 'warning' as const,
description: 'Banking hours mentioned without complete schedule',
context: {
detectedContent: response,
missingInfo: 'complete_schedule'
},
recommendation: 'Include full banking hours (Monday through Friday, 9 AM to 5 PM)'
});
}
return {
isCompliant: violations.length === 0,
violations,
riskScore: violations.length * 10,
requiresReview: violations.length > 0
};
}
};
Strongly Typed Event Tracking
import type { InteractionEvent, EventMetadata, TokenUsage } from '@agent-governance/node';
const trackAgentResponse = (
monitor: AgentMonitor,
agentId: string,
sessionId: string,
content: string,
metadata: EventMetadata
) => {
const event: InteractionEvent = {
sessionId,
interactionType: 'agent_response',
content,
metadata: {
llmLatency: metadata.llmLatency,
tokensUsed: metadata.tokensUsed,
responseQuality: metadata.responseQuality,
cost: metadata.cost
}
};
monitor.track(agentId, event);
};
Type-Safe Configuration
import type { AgentMonitoringConfig, AgentInfo } from '@agent-governance/node';
const config: AgentMonitoringConfig = {
apiKey: process.env.AGENT_GOVERNANCE_API_KEY!,
organizationId: process.env.AGENT_GOVERNANCE_ORG_ID!,
environment: 'production',
batchSize: 100,
flushInterval: 5000,
enableComplianceChecks: true,
enableLogging: false,
logLevel: 'error',
retryAttempts: 3,
retryDelay: 1000
};
const agentInfo: AgentInfo = {
id: 'banking-assistant',
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 services',
complianceSettings: {
sr11_7_enabled: true,
fair_lending_monitoring: false,
bsa_aml_checks: true
}
};
Next Steps
AgentMonitor API
Learn about the main monitoring class methods
ComplianceEngine API
Explore compliance rule management
Error Handling
Understand error types and handling strategies
Examples
See these types used in practical examples