Skip to main content

​
Runtime API Reference

​
Overview

Complete API reference for the AG-Kit Runtime system, including agent management, event handling, and performance optimization.

​
Core Classes

​
Agent

Main agent class for executing AI agents. 
class Agent<TState extends StateConstraint = StateConstraint, TOutput extends OutputConstraint = string>

​
Constructor

constructor(config: AgentConfig<TState, TOutput>)

​
Methods

run(input, state?, options?)
Execute the agent with given input. 
async run(
  input: string | Message[],
  state?: TState,
  options?: RunOptions<TState>
): Promise<AgentResult<TOutput>>
Parameters:
  • input: Input text or message array
  • state: Optional state object
  • options: Optional run configuration
Returns: Promise resolving to agent result
runStream(input, state?, options?)
Execute the agent with streaming output. 
runStream(
  input: string | Message[],
  state?: TState,
  options?: RunOptions<TState>
): Observable<AgentEvent>
getMemoryUsage()
Get current memory usage statistics. 
getMemoryUsage(): { current: number; max: number; percentage: number }
clearMemory()
Clear all stored memory and reset state. 
clearMemory(): void
setMemoryLimit(limit)
Set maximum memory usage limit. 
setMemoryLimit(limit: number): void
destroy()
Clean up resources and remove event listeners. 
destroy(): void

​
Configuration Interfaces

​
AgentConfig

interface AgentConfig<TState extends StateConstraint, TOutput extends OutputConstraint> {
  name: string;
  description?: string;
  model: ModelProvider | string;
  instructions?: string | InstructionProvider<TState>;
  stateType?: new () => TState;
  outputType?: OutputType<TOutput>;
  modelSettings?: ModelSettings;
  tools?: ToolDefinition<TState>[];
  memory?: MemoryConfig;
  humanInTheLoop?: HumanInTheLoopConfig;
  controlFlow?: ControlFlowConfig;
}

​
RunOptions

interface RunOptions<TState extends StateConstraint> {
  state?: TState;
  conversationId?: string;
  runId?: string;
  userId?: string;
  temperature?: number;
  maxTokens?: number;
  stream?: boolean;
  tools?: ToolDefinition<TState>[];
  memory?: MemoryConfig;
  humanInTheLoop?: HumanInTheLoopConfig;
  controlFlow?: ControlFlowConfig;
}

​
Event System

​
OptimizedEventSystem

High-performance event system with batching and async processing. 
class OptimizedEventSystem {
  constructor(config: EventSystemConfig);
  
  emit(event: BaseEvent): void;
  on(eventType: EventType, handler: EventHandler): void;
  off(eventType: EventType, handler: EventHandler): void;
  getPerformanceMetrics(): PerformanceMetrics;
  destroy(): void;
}

​
Event System Configuration

interface EventSystemConfig {
  batchSize?: number;           // Default: 10
  batchTimeout?: number;        // Default: 16ms
  maxConcurrentHandlers?: number; // Default: 5
  enableBatching?: boolean;     // Default: true
  enableAsyncProcessing?: boolean; // Default: true
}

​
Error Handling

​
Error Classes

abstract class AGKitError extends Error {
  abstract readonly code: string;
  abstract readonly category: ErrorCategory;
  readonly timestamp: Date;
  readonly context?: Record<string, unknown>;
}

class ConfigurationError extends AGKitError
class NetworkError extends AGKitError
class ModelError extends AGKitError
class ToolError extends AGKitError
class ValidationError extends AGKitError
class RuntimeError extends AGKitError
class MemoryError extends AGKitError
class ControlFlowError extends AGKitError

​
Error Categories

enum ErrorCategory {
  CONFIGURATION = 'CONFIGURATION',
  NETWORK = 'NETWORK',
  MODEL = 'MODEL',
  TOOL = 'TOOL',
  VALIDATION = 'VALIDATION',
  RUNTIME = 'RUNTIME',
  MEMORY = 'MEMORY',
  CONTROL_FLOW = 'CONTROL_FLOW'
}

​
Type System

​
Type Constraints

type StateConstraint = Record<string, unknown>;
type OutputConstraint = string | Record<string, unknown> | Array<unknown>;

​
Type Validation

function validateState<T extends StateConstraint>(
  value: unknown,
  schema?: z.ZodSchema<T>
): T

function validateOutput<T extends OutputConstraint>(
  value: unknown,
  schema?: z.ZodSchema<T>
): T

​
Performance Monitoring

​
Performance Metrics

interface PerformanceMetrics {
  queueSize: number;
  processingHandlers: number;
  averageProcessingTime: number;
  totalEventsProcessed: number;
  errorRate: number;
}

​
Memory Usage

interface MemoryUsage {
  current: number;      // Current memory usage in bytes
  max: number;         // Maximum memory limit in bytes
  percentage: number;  // Usage percentage (0-100)
}