TypeScript Types - AI Agents House SDK

This page provides comprehensive TypeScript type definitions for all interfaces, types, and enums used throughout the AI Agents House SDK.

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 the track() 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

​Core Configuration Types

​AgentMonitoringConfig

​MonitoringOptions

​Agent Types

​AgentInfo

​ToolInfo

​ComplianceSettings

​Event Types

​InteractionEvent

​EventMetadata

​Detailed Event Types

​ConversationStartEvent

​UserMessageEvent

​AgentResponseEvent

​ToolCallEvent

​ToolResultEvent

​ErrorEvent

​ConversationEndEvent

​Compliance Types

​ComplianceRule

​InteractionContext

​ComplianceResult

​Event Batching Types

​EventBatch

​EventBatcherConfig

​Utility Types

​BaseEvent

​Logger

​HttpOptions

​Validation Types

​ValidationError

​Export Summary

​Type Usage Examples

​Custom Rule with Full Typing

​Strongly Typed Event Tracking

​Type-Safe Configuration

​Next Steps