Follow these guidelines to ensure your Metorial integration is production-ready, reliable, and performant.

Error Handling

Always implement comprehensive error handling:

import { generateText } from 'ai';

async function processUserRequest(userMessage: string) {
  try {
    const result = await metorial.withProviderSession(
      metorialAiSdk,
      { serverDeployments: [process.env.METORIAL_DEPLOYMENT_ID!] },
      async session => {
        return await generateText({
          model: openai('gpt-4'),
          messages: [{ role: 'user', content: userMessage }],
          tools: session.tools,
          maxToolRoundtrips: 5
        });
      }
    );
    
    return { success: true, text: result.text };
  } catch (error) {
    console.error('Error processing request:', error);
    
    // Return user-friendly error message
    return { 
      success: false, 
      error: 'Unable to process your request. Please try again.' 
    };
  }
}

Rate Limiting

Implement rate limiting to prevent abuse and manage costs:

// Example using a simple in-memory rate limiter
const requestCounts = new Map<string, number>();

function checkRateLimit(userId: string, maxRequests: number = 10): boolean {
  const count = requestCounts.get(userId) || 0;
  
  if (count >= maxRequests) {
    return false;
  }
  
  requestCounts.set(userId, count + 1);
  
  // Reset after 1 hour
  setTimeout(() => {
    requestCounts.delete(userId);
  }, 3600000);
  
  return true;
}

Timeout Management

Set appropriate timeouts to prevent hanging requests:

async function generateWithTimeout(config: any, timeoutMs: number = 30000) {
  const timeoutPromise = new Promise((_, reject) => {
    setTimeout(() => reject(new Error('Request timeout')), timeoutMs);
  });
  
  const generationPromise = generateText(config);
  
  return Promise.race([generationPromise, timeoutPromise]);
}

Monitoring and Logging

Implement proper logging for debugging and monitoring:

import { generateText } from 'ai';

async function generateWithLogging(config: any, requestId: string) {
  const startTime = Date.now();
  
  console.log(`[${requestId}] Starting generation`, {
    model: config.model,
    messageCount: config.messages.length
  });
  
  try {
    const result = await generateText({
      ...config,
      onToolCall: (toolCall) => {
        console.log(`[${requestId}] Tool called: ${toolCall.toolName}`);
      }
    });
    
    const duration = Date.now() - startTime;
    console.log(`[${requestId}] Generation completed in ${duration}ms`);
    
    return result;
  } catch (error) {
    console.error(`[${requestId}] Generation failed`, error);
    throw error;
  }
}

Caching Strategies

Cache session configurations when appropriate:

// Cache deployment configurations that don't change often
const deploymentCache = new Map<string, any>();

async function getCachedSession(deploymentId: string) {
  if (deploymentCache.has(deploymentId)) {
    return deploymentCache.get(deploymentId);
  }
  
  // This is conceptual - actual implementation depends on your needs
  const config = { serverDeployments: [deploymentId] };
  deploymentCache.set(deploymentId, config);
  
  return config;
}

Resource Cleanup

Ensure proper cleanup of resources:

async function processWithCleanup(userMessage: string) {
  let sessionActive = false;
  
  try {
    const result = await metorial.withProviderSession(
      metorialAiSdk,
      { serverDeployments: [process.env.METORIAL_DEPLOYMENT_ID!] },
      async session => {
        sessionActive = true;
        // Your processing logic
        return await generateText({
          model: openai('gpt-4'),
          messages: [{ role: 'user', content: userMessage }],
          tools: session.tools
        });
      }
    );
    
    sessionActive = false;
    return result;
  } finally {
    // Cleanup code
    if (sessionActive) {
      console.log('Session was not properly closed');
    }
  }
}

Testing in Production

1. Use separate deployments: Create different server deployments for development, staging, and production
2. Implement feature flags: Control rollout of new integrations
3. Monitor usage metrics: Track API calls, errors, and latency
4. Set up alerts: Get notified of unusual patterns or errors

Performance Optimization

• Stream responses for better user experience
• Limit tool roundtrips to prevent long execution times
• Choose appropriate models (faster models for simple tasks)
• Implement request batching where applicable

Security Checklist

• ✅ API keys in environment variables only
• ✅ Server-side API calls only (never client-side)
• ✅ Input validation and sanitization
• ✅ Rate limiting implemented
• ✅ Error messages don't leak sensitive info
• ✅ Regular security audits
• ✅ Monitoring for suspicious activity

Cost Management

• Set usage budgets in your Metorial dashboard
• Monitor token usage and costs
• Implement usage limits per user
• Choose cost-effective models for appropriate tasks
• Cache responses when possible

Deployment Checklist

Before deploying to production:

• ✅ All API keys configured in production environment
• ✅ Error handling implemented
• ✅ Logging and monitoring set up
• ✅ Rate limiting in place
• ✅ Timeouts configured
• ✅ Load testing completed
• ✅ Rollback plan prepared
• ✅ Team trained on debugging procedures