Skip to main content

Runtime Examples

Overview

This page provides practical examples of using the AG-Kit Runtime system, from basic agent creation to advanced performance optimization.

Basic Examples

Simple Agent

import { Agent, createOpenAIProvider } from '@ag-kit/agents';

// Create model provider
const modelProvider = createOpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY,
  defaultModel: 'gpt-4'
});

// Create agent
const agent = new Agent({
  name: 'simple-agent',
  description: 'A simple helpful assistant',
  model: modelProvider,
  instructions: 'You are a helpful assistant. Be concise and accurate.'
});

// Run agent
const result = await agent.run('What is the capital of France?');
console.log(result.data); // "The capital of France is Paris."

Agent with Custom State

interface UserSession {
  userId: string;
  preferences: {
    language: string;
    theme: 'light' | 'dark';
  };
  history: string[];
}

const agent = new Agent<UserSession>({
  name: 'personalized-agent',
  model: modelProvider,
  instructions: 'You are a personalized assistant.',
  stateType: class implements UserSession {
    userId = '';
    preferences = { language: 'en', theme: 'light' };
    history = [];
  }
});

const initialState: UserSession = {
  userId: 'user123',
  preferences: { language: 'en', theme: 'dark' },
  history: []
};

const result = await agent.run('Hello!', initialState);

Advanced Examples

Streaming Responses

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

// Listen to streaming events
agent.on(EventType.TEXT_MESSAGE_CONTENT, (event) => {
  process.stdout.write(event.delta || '');
});

agent.on(EventType.TEXT_MESSAGE_END, () => {
  console.log('\n--- Message Complete ---');
});

// Run with streaming
const stream = agent.runStream('Tell me a story about a robot.');
stream.subscribe({
  next: (event) => {
    if (event.type === EventType.TEXT_MESSAGE_CONTENT) {
      process.stdout.write(event.delta || '');
    }
  },
  complete: () => console.log('\nStream complete'),
  error: (error) => console.error('Stream error:', error)
});

Tool Integration

import { z } from 'zod';

const weatherTool = {
  name: 'get_weather',
  description: 'Get current weather for a location',
  schema: z.object({
    location: z.string().describe('City name or coordinates')
  }),
  handler: async (input) => {
    const { location } = input as { location: string };
    // Simulate weather API call
    return {
      location,
      temperature: 22,
      condition: 'sunny',
      humidity: 65
    };
  }
};

const agent = new Agent({
  name: 'weather-agent',
  model: modelProvider,
  instructions: 'You can help users get weather information.',
  tools: [weatherTool]
});

const result = await agent.run('What\'s the weather like in Tokyo?');

Human-in-the-Loop

const agent = new Agent({
  name: 'approval-agent',
  model: modelProvider,
  instructions: 'You can send emails, but require approval first.',
  tools: [
    {
      name: 'send_email',
      description: 'Send an email',
      handler: async (input) => {
        // Email sending logic
        return { success: true, messageId: 'msg123' };
      },
      requiresApproval: true
    }
  ],
  humanInTheLoop: {
    enabled: true,
    requireApproval: ['send_email'],
    timeout: 30000, // 30 seconds
    defaultAction: 'pause'
  }
});

// Listen for approval requests
agent.on(EventType.APPROVAL_REQUIRED, (event) => {
  console.log('Approval required for:', event.toolName);
  console.log('Input:', event.input);
  
  // Simulate user approval
  setTimeout(() => {
    agent.approveToolCall(event.toolCallId, true);
  }, 1000);
});

const result = await agent.run('Send an email to [email protected] about the meeting');

Performance Optimization Examples

Optimized Event System

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

const eventSystem = new OptimizedEventSystem({
  batchSize: 20,           // Process 20 events at once
  batchTimeout: 8,         // ~120fps processing
  maxConcurrentHandlers: 10,
  enableBatching: true,
  enableAsyncProcessing: true
});

// Monitor performance
setInterval(() => {
  const metrics = eventSystem.getPerformanceMetrics();
  console.log('Event System Metrics:', {
    queueSize: metrics.queueSize,
    processingHandlers: metrics.processingHandlers,
    averageProcessingTime: metrics.averageProcessingTime,
    errorRate: metrics.errorRate
  });
}, 5000);

Memory Management

const agent = new Agent({
  name: 'memory-optimized-agent',
  model: modelProvider,
  instructions: 'You are a memory-efficient assistant.',
  memory: {
    maxHistoryLength: 50,      // Keep last 50 messages
    compressionThreshold: 0.7, // Compress at 70% usage
    ttl: 15 * 60 * 1000       // 15 minutes TTL
  }
});

// Monitor memory usage
setInterval(() => {
  const usage = agent.getMemoryUsage();
  console.log(`Memory: ${usage.percentage.toFixed(1)}% used`);
  
  if (usage.percentage > 80) {
    console.log('Memory usage high, clearing old data...');
    agent.clearMemory();
  }
}, 30000); // Check every 30 seconds

Error Handling

import { 
  ConfigurationError, 
  NetworkError, 
  ModelError,
  ErrorCategory 
} from '@ag-kit/agents';

try {
  const result = await agent.run('Hello');
} catch (error) {
  switch (error.category) {
    case ErrorCategory.CONFIGURATION:
      console.error('Configuration error:', error.message);
      // Handle configuration issues
      break;
      
    case ErrorCategory.NETWORK:
      console.error('Network error:', error.message);
      // Retry or fallback logic
      break;
      
    case ErrorCategory.MODEL:
      console.error('Model error:', error.message);
      // Switch to backup model
      break;
      
    default:
      console.error('Unexpected error:', error);
  }
}

Production Examples

Multi-Agent System

class AgentManager {
  private agents: Map<string, Agent> = new Map();
  private eventSystem: OptimizedEventSystem;

  constructor() {
    this.eventSystem = new OptimizedEventSystem({
      batchSize: 50,
      batchTimeout: 16,
      maxConcurrentHandlers: 20
    });
  }

  async createAgent(name: string, config: AgentConfig) {
    const agent = new Agent(config);
    this.agents.set(name, agent);
    
    // Set up event forwarding
    agent.on('*', (event) => {
      this.eventSystem.emit({
        ...event,
        agentName: name
      });
    });
    
    return agent;
  }

  async runAgent(name: string, input: string) {
    const agent = this.agents.get(name);
    if (!agent) {
      throw new Error(`Agent ${name} not found`);
    }
    
    return await agent.run(input);
  }

  destroy() {
    this.agents.forEach(agent => agent.destroy());
    this.eventSystem.destroy();
  }
}

Health Monitoring

class AgentHealthMonitor {
  private agents: Agent[];
  private metrics: Map<string, any> = new Map();

  constructor(agents: Agent[]) {
    this.agents = agents;
    this.startMonitoring();
  }

  private startMonitoring() {
    setInterval(() => {
      this.agents.forEach((agent, index) => {
        const memoryUsage = agent.getMemoryUsage();
        const health = {
          memoryUsage: memoryUsage.percentage,
          isHealthy: memoryUsage.percentage < 90,
          timestamp: new Date()
        };
        
        this.metrics.set(`agent-${index}`, health);
        
        if (!health.isHealthy) {
          console.warn(`Agent ${index} memory usage high: ${health.memoryUsage}%`);
        }
      });
    }, 10000); // Check every 10 seconds
  }

  getHealthReport() {
    return Array.from(this.metrics.entries()).map(([name, health]) => ({
      name,
      ...health
    }));
  }
}

Best Practices

  1. Resource Cleanup: Always call destroy() when done with agents
  2. Error Handling: Implement comprehensive error handling with specific error types
  3. Memory Monitoring: Set appropriate memory limits and monitor usage
  4. Event Management: Use optimized event systems for high-throughput scenarios
  5. Performance Monitoring: Track performance metrics and optimize accordingly
  6. Type Safety: Use proper type constraints for state and output
  7. Configuration Validation: Validate all configurations at runtime