retellai-sdk-patterns

Apply production-ready Retell AI SDK patterns for TypeScript and Python.Use when implementing Retell AI integrations, refactoring SDK usage,or establishing team coding standards for Retell AI.Trigger with phrases like "retellai SDK patterns", "retellai best practices","retellai code patterns", "idiomatic retellai".

⭐939stars🔀114forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides production-ready Retell AI SDK patterns for TypeScript and Python, designed to streamline the implementation of robust voice AI integrations. It offers standardized templates for singleton clients, advanced error handling wrappers, and exponential backoff retry logic to ensure high reliability, type safety, and maintainability in professional development environments.

Use Cases

  • Implementing a thread-safe Singleton client for Retell AI to optimize resource usage and connection management in TypeScript applications.
  • Refactoring existing SDK usage to include structured logging and comprehensive error handling, preventing uncaught exceptions in production.
  • Building resilient voice AI workflows with automatic exponential backoff retry logic to mitigate transient API and network failures.
  • Developing multi-tenant systems using the Factory pattern to manage and isolate multiple Retell AI API keys dynamically.
  • Enforcing runtime data integrity and type safety for Retell AI API responses by integrating Zod validation or Python context managers.
nameretellai-sdk-patterns
description|
allowed-toolsRead, Write, Edit
version1.0.0
licenseMIT
authorJeremy Longshore <jeremy@intentsolutions.io>

Retell AI SDK Patterns

Overview

Production-ready patterns for Retell AI SDK usage in TypeScript and Python.

Prerequisites

  • Completed retellai-install-auth setup
  • Familiarity with async/await patterns
  • Understanding of error handling best practices

Instructions

// src/retellai/client.ts
import { RetellAIClient } from '@retellai/sdk';

let instance: RetellAIClient | null = null;

export function getRetell AIClient(): RetellAIClient {
  if (!instance) {
    instance = new RetellAIClient({
      apiKey: process.env.RETELLAI_API_KEY!,
      // Additional options
    });
  }
  return instance;
}

Step 2: Add Error Handling Wrapper

import { Retell AIError } from '@retellai/sdk';

async function safeRetell AICall<T>(
  operation: () => Promise<T>
): Promise<{ data: T | null; error: Error | null }> {
  try {
    const data = await operation();
    return { data, error: null };
  } catch (err) {
    if (err instanceof Retell AIError) {
      console.error({
        code: err.code,
        message: err.message,
      });
    }
    return { data: null, error: err as Error };
  }
}

Step 3: Implement Retry Logic

async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries = 3,
  backoffMs = 1000
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (err) {
      if (attempt === maxRetries) throw err;
      const delay = backoffMs * Math.pow(2, attempt - 1);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

Output

  • Type-safe client singleton
  • Robust error handling with structured logging
  • Automatic retry with exponential backoff
  • Runtime validation for API responses

Error Handling

Pattern Use Case Benefit
Safe wrapper All API calls Prevents uncaught exceptions
Retry logic Transient failures Improves reliability
Type guards Response validation Catches API changes
Logging All operations Debugging and monitoring

Examples

Factory Pattern (Multi-tenant)

const clients = new Map<string, RetellAIClient>();

export function getClientForTenant(tenantId: string): RetellAIClient {
  if (!clients.has(tenantId)) {
    const apiKey = getTenantApiKey(tenantId);
    clients.set(tenantId, new RetellAIClient({ apiKey }));
  }
  return clients.get(tenantId)!;
}

Python Context Manager

from contextlib import asynccontextmanager
from retellai import RetellAIClient

@asynccontextmanager
async def get_retellai_client():
    client = RetellAIClient()
    try:
        yield client
    finally:
        await client.close()

Zod Validation

import { z } from 'zod';

const retellaiResponseSchema = z.object({
  id: z.string(),
  status: z.enum(['active', 'inactive']),
  createdAt: z.string().datetime(),
});

Resources

Next Steps

Apply patterns in retellai-core-workflow-a for real-world usage.