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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
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
- Resource Cleanup: Always call
destroy()when done with agents - Error Handling: Implement comprehensive error handling with specific error types
- Memory Monitoring: Set appropriate memory limits and monitor usage
- Event Management: Use optimized event systems for high-throughput scenarios
- Performance Monitoring: Track performance metrics and optimize accordingly
- Type Safety: Use proper type constraints for state and output
- Configuration Validation: Validate all configurations at runtime
Related Documentation
- Runtime Overview - Runtime system overview
- Runtime Events - Event system documentation
- Runtime API - Complete API reference