Skip to main content

​
Runtime Events

​
Overview

The AG-Kit Runtime Event System provides a powerful, optimized way to handle real-time events during agent execution. It supports event batching, async processing, and performance monitoring.

​
Event Types

​
Core Events

  • run_started - Agent execution begins
  • run_finished - Agent execution completes successfully
  • run_failed - Agent execution fails with error
  • text_message_start - Text message generation begins
  • text_message_content - Text message content is generated
  • text_message_end - Text message generation completes
  • tool_call_start - Tool execution begins
  • tool_call_end - Tool execution completes
  • tool_call_result - Tool execution result is available
  • state_update - Agent state is updated
  • approval_required - Human approval is required
  • approval_received - Human approval is received
  • error - An error occurs during execution

​
Event Handling

​
Basic Event Listening

import { EventType } from '@ag-kit/agents';

// Listen to specific events
agent.on(EventType.RUN_STARTED, (event) => {
  console.log('Run started:', event.conversationId);
});

agent.on(EventType.ERROR, (event) => {
  console.error('Error occurred:', event.error.message);
});

​
Optimized Event System

import { OptimizedEventSystem } from '@ag-kit/agents';

const eventSystem = new OptimizedEventSystem({
  batchSize: 10,           // Process events in batches
  batchTimeout: 16,        // ~60fps processing
  maxConcurrentHandlers: 5, // Limit concurrent processing
  enableBatching: true,    // Enable event batching
  enableAsyncProcessing: true // Async event processing
});

// Performance monitoring
const metrics = eventSystem.getPerformanceMetrics();
console.log('Queue size:', metrics.queueSize);
console.log('Processing handlers:', metrics.processingHandlers);

​
Event Data Structure

​
Base Event

interface BaseEvent {
  type: EventType;
  timestamp: Date;
  conversationId?: string;
  runId?: string;
  userId?: string;
}

​
Specific Event Types

interface RunStartedEvent extends BaseEvent {
  type: 'run_started';
  input: string | Message[];
  state?: Record<string, unknown>;
}

interface TextMessageContentEvent extends BaseEvent {
  type: 'text_message_content';
  content: string;
  delta?: string;
}

interface ToolCallResultEvent extends BaseEvent {
  type: 'tool_call_result';
  toolName: string;
  result: unknown;
  executionTime: number;
}

​
Performance Optimization

​
Event Batching

The optimized event system automatically batches events for better performance: 
const eventSystem = new OptimizedEventSystem({
  batchSize: 10,        // Process up to 10 events at once
  batchTimeout: 16,     // Wait max 16ms before processing batch
  enableBatching: true
});

​
Async Processing

Enable async event processing for non-blocking operations: 
const eventSystem = new OptimizedEventSystem({
  enableAsyncProcessing: true,
  maxConcurrentHandlers: 5
});

​
Best Practices

  1. Event Cleanup: Remove event listeners when no longer needed
  2. Error Handling: Always handle error events appropriately
  3. Performance: Use optimized event system for high-throughput scenarios
  4. Monitoring: Monitor event system performance metrics
  5. Batching: Configure appropriate batch sizes for your use case