Best Practices

Production-ready patterns and recommendations for building robust AI applications.

Architecture Patterns

API Selection Strategy

Use Core API when:

• You need custom agent logic
• Building unique knowledge pipelines
• Requiring low-level control
• Implementing custom guardrails

Use Business API when:

• Building business applications
• Need team collaboration features
• Want built-in analytics
• Require channel integrations

Hybrid Approach

Combine Both APIs

Use Core API for custom agents and Business API for team features.

// Create agent with Core API
const agent = await client.createPersona({...});

// Manage with Business API  
const team = await client.createTeam({
  agents: [agent.id]
});

Performance Optimization

Caching Strategies

• Cache agent responses for repeated queries

• Use session IDs for conversation continuity

• Implement knowledge source caching

• Cache team availability schedules

Request Optimization

• Batch multiple operations when possible

• Use streaming for long responses

• Implement request debouncing

• Optimize knowledge chunk sizes

Monitoring

• Track response times and token usage

• Monitor error rates and patterns

• Set up usage alerts

• Use Business API analytics

Security Guidelines

Input Validation

Input Validation Example

import { z } from 'zod';

const QuerySchema = z.object({
  message: z.string().min(1).max(1000),
  sessionId: z.string().optional()
});

// Validate before sending to API
const validated = QuerySchema.parse(userInput);

Sanitize all user inputs

Validate data schemas

Implement rate limiting

Guardrails

Multi-Layer Protection

Implement guardrails at multiple levels: input validation, prompt engineering, and output monitoring.

Use agent-level guardrails

Monitor for prompt injection

Implement output filtering

Knowledge Management

Chunking Strategy

Optimize knowledge ingestion for better retrieval accuracy with sentence window approach.

// Optimal knowledge source structure
await client.addKnowledge(agentId, {
  type: 'text',
  source: content,
  metadata: {
    title: 'Clear, descriptive title',
    category: 'support', // Helps with filtering
    version: '1.0',      // Track content versions
    priority: 'high'     // Influence retrieval ranking
  }
});

✅ Do

• Use clear, descriptive titles
• Keep content well-structured
• Update content regularly
• Use relevant metadata
• Test retrieval accuracy

❌ Don't

• Upload huge files without chunking
• Use vague or generic titles
• Include irrelevant content
• Forget to version control knowledge
• Ignore retrieval metrics

Team Collaboration Patterns

Agent Handoff Pattern

Seamlessly transfer conversations between AI agents and human team members.

Agent Handoff Example

// Escalate to human when AI confidence is low
const response = await client.query(agentId, { message });

if (response.confidence < 0.7) {
  await client.escalateToTeam(teamId, {
    conversationId: response.sessionId,
    context: response.context,
    priority: 'medium'
  });
}

Availability Optimization

Balance AI and human availability for optimal customer experience.

Business Hours

• AI + Human hybrid
• Instant AI responses
• Human escalation available

Off Hours

• AI-only with enhanced knowledge
• Queue complex issues for humans
• Set expectations clearly

Error Handling & Resilience

import { RodgerError } from '@rodger-ai/sdk';

class RobustQueryService {
  async queryWithRetry(agentId: string, message: string, maxRetries = 3) {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        return await this.client.query(agentId, { message });
      } catch (error) {
        if (error instanceof RodgerError) {
          switch (error.code) {
            case 'RATE_LIMIT_EXCEEDED':
              if (attempt < maxRetries) {
                await this.delay(Math.pow(2, attempt) * 1000); // Exponential backoff
                continue;
              }
              throw new Error('Rate limit exceeded. Please try again later.');
            
            case 'AGENT_NOT_FOUND':
              throw new Error('Agent not found or not accessible.');
            
            case 'INSUFFICIENT_QUOTA':
              throw new Error('API quota exceeded. Please upgrade your plan.');
            
            default:
              if (attempt < maxRetries && this.isRetryable(error)) {
                await this.delay(1000 * attempt);
                continue;
              }
              throw error;
          }
        }
        throw error;
      }
    }
  }

  private delay(ms: number) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }

  private isRetryable(error: RodgerError): boolean {
    const retryableCodes = ['NETWORK_ERROR', 'TIMEOUT', 'SERVER_ERROR'];
    return retryableCodes.includes(error.code);
  }
}

Performance Monitoring

Key Metrics to Track

Response time (target: <2s)

Token usage per query

Knowledge retrieval accuracy

Error rates by endpoint

User satisfaction scores

Analytics Implementation

Performance Tracking

// Track custom events
await client.trackEvent({
  type: 'query_completed',
  agentId: agent.id,
  duration: responseTime,
  tokenUsage: tokens,
  satisfaction: userRating
});

// Get performance insights
const analytics = await client.getAnalytics({
  timeframe: '24h',
  metrics: ['response_time', 'satisfaction'],
  groupBy: 'agent'
});

Testing Strategies

A/B Testing for Agents

Use Business API A/B testing to optimize agent performance continuously.

A/B Testing Setup

// Create A/B test for different agent configurations
const abTest = await client.createABTest({
  name: 'Response Style Optimization',
  description: 'Test formal vs casual tone',
  agents: {
    variant_a: 'formal-agent-id',
    variant_b: 'casual-agent-id'  
  },
  traffic_split: 50,
  success_metric: 'satisfaction_score',
  min_sample_size: 100
});

await client.startABTest(abTest.id);

Unit Testing

• Test agent creation/updates
• Validate knowledge ingestion
• Mock API responses
• Test error scenarios

Integration Testing

• End-to-end query flows
• Team routing logic
• Channel integrations
• Analytics accuracy

Quick Reference

Core API Docs Business API Docs Code Examples Authentication