retellai-sdk-patterns

Retell AI SDK Patterns

Overview

Production-ready patterns for Retell AI: client singletons, typed agent configurations, call management, and error handling.

Prerequisites

Completed retellai-install-auth
retell-sdk installed

Instructions

Step 1: Singleton Client

import Retell from 'retell-sdk';

let _retell: Retell | null = null;

export function getRetellClient(): Retell { if (!_retell) { _retell = new Retell({ apiKey: process.env.RETELL_API_KEY! }); } return _retell; }


### Step 2: Typed Agent Configuration

```typescript
interface AgentConfig {
  name: string;
  voiceId: string;
  prompt: string;
  functions?: FunctionConfig[];
  maxCallDurationMs?: number;
  endCallAfterSilenceMs?: number;
}

async function createAgent(config: AgentConfig) {
  const retell = getRetellClient();

  const llm = await retell.llm.create({
    model: 'gpt-4o',
    general_prompt: config.prompt,
    functions: config.functions,
  });

  const agent = await retell.agent.create({
    response_engine: { type: 'retell-llm', llm_id: llm.llm_id },
    voice_id: config.voiceId,
    agent_name: config.name,
    max_call_duration_ms: config.maxCallDurationMs || 300000,
    end_call_after_silence_ms: config.endCallAfterSilenceMs || 10000,
  });

  return { agentId: agent.agent_id, llmId: llm.llm_id };
}

Step 3: Call Manager with Retry

async function makeCallWithRetry(
  fromNumber: string, toNumber: string, agentId: string, maxRetries = 2
) {
  const retell = getRetellClient();
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const call = await retell.call.createPhoneCall({
        from_number: fromNumber,
        to_number: toNumber,
        override_agent_id: agentId,
      });
      return call;
    } catch (err: any) {
      if (attempt === maxRetries || err.status < 500) throw err;
      await new Promise(r => setTimeout(r, 2000 * (attempt + 1)));
    }
  }
}

Step 4: Batch Call Campaign

async function runCallCampaign(
  numbers: string[], agentId: string, concurrency = 3, delayMs = 2000
) {
  const results: Array<{ number: string; callId?: string; error?: string }> = [];
  const queue = [...numbers];
  const active = new Set<Promise<void>>();

  while (queue.length > 0 || active.size > 0) {
    while (active.size < concurrency && queue.length > 0) {
      const number = queue.shift()!;
      const p = (async () => {
        try {
          const call = await makeCallWithRetry(process.env.RETELL_PHONE_NUMBER!, number, agentId);
          results.push({ number, callId: call.call_id });
        } catch (err: any) {
          results.push({ number, error: err.message });
        }
        await new Promise(r => setTimeout(r, delayMs));
      })();
      active.add(p);
      p.finally(() => active.delete(p));
    }
    if (active.size > 0) await Promise.race(active);
  }
  return results;
}

Output

Singleton Retell client
Typed agent creation with LLM configuration
Retry logic for call creation
Concurrent call campaign manager

Error Handling

Pattern	Use Case	Benefit
Singleton	All SDK calls	One client instance
Typed config	Agent creation	Type safety, defaults
Retry wrapper	Call failures	Automatic recovery
Campaign manager	Outbound calls	Rate-limited concurrency

Examples

Use an idempotency boundary around call creation

Generate a request identifier at the application edge and persist its state before invoking the Retell SDK. If the network response is lost, retrieve the existing result by that identifier or operator-visible correlation data before attempting another call. Keep retries bounded and limited to operations whose outcome can be established; this prevents a transient client failure from creating multiple customer calls.

Resources

Next Steps

Apply in retellai-core-workflow-a for agent building.