Retell AI SDK パターン

概要

TypeScript および Python での Retell AI SDK 使用に関する本番環境対応パターンです。

前提条件

• retellai-install-auth セットアップの完了
• async/await パターンの理解
• エラーハンドリングのベストプラクティスの知識

手順

ステップ 1: シングルトンパターンの実装（推奨）

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

let instance: RetellAIClient | null = null;

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

ステップ 2: エラーハンドリングラッパーの追加

import { RetellAIError } from '@retellai/sdk';

async function safeRetellAICall<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 RetellAIError) {
      console.error({
        code: err.code,
        message: err.message,
      });
    }
    return { data: null, error: err as Error };
  }
}

ステップ 3: リトライロジックの実装

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');
}

出力

• 型安全なクライアントシングルトン
• 構造化ログ機能を備えた堅牢なエラーハンドリング
• 指数バックオフを使用した自動リトライ
• API レスポンスのランタイム検証

エラーハンドリング

パターン	ユースケース	メリット
セーフラッパー	すべての API 呼び出し	キャッチされない例外を防止
リトライロジック	一時的な障害	信頼性を向上
型ガード	レスポンス検証	API の変更を検出
ログ出力	すべての操作	デバッグと監視

例

ファクトリパターン（マルチテナント）

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 コンテキストマネージャー

from contextlib import asynccontextmanager
from retellai import RetellAIClient

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

Zod バリデーション

import { z } from 'zod';

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

リソース

• Retell AI SDK リファレンス
• Retell AI API タイプ
• Zod ドキュメント

次のステップ

retellai-core-workflow-a でパターンを適用して実際の使用例を確認します。