Api

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)
}

Related Documentation

• Runtime Overview - Runtime system overview
• Runtime Events - Event system documentation
• Runtime Examples - Code examples and patterns