Retell AI 信頼性パターン

概要

Retell AI 統合向けの本番レベルの信頼性パターンです。

前提条件

• サーキットブレーカーパターンの理解
• opossum または同様のライブラリがインストール済み
• DLQ 向けのキュー基盤
• フォールバック向けのキャッシングレイヤー

サーキットブレーカー

import CircuitBreaker from 'opossum';

const retellaiBreaker = new CircuitBreaker(
  async (operation: () => Promise<any>) => operation(),
  {
    timeout: 30000,
    errorThresholdPercentage: 50,
    resetTimeout: 30000,
    volumeThreshold: 10,
  }
);

// イベント
retellaiBreaker.on('open', () => {
  console.warn('Retell AI circuit OPEN - requests failing fast');
  alertOps('Retell AI circuit breaker opened');
});

retellaiBreaker.on('halfOpen', () => {
  console.info('Retell AI circuit HALF-OPEN - testing recovery');
});

retellaiBreaker.on('close', () => {
  console.info('Retell AI circuit CLOSED - normal operation');
});

// 使用方法
async function safeRetellAICall<T>(fn: () => Promise<T>): Promise<T> {
  return retellaiBreaker.fire(fn);
}

べき等性キー

import { v4 as uuidv4 } from 'uuid';
import crypto from 'crypto';

// 入力から決定的なべき等性キーを生成
function generateIdempotencyKey(
  operation: string,
  params: Record<string, any>
): string {
  const data = JSON.stringify({ operation, params });
  return crypto.createHash('sha256').update(data).digest('hex');
}

// またはストレージを使用したランダムキー
class IdempotencyManager {
  private store: Map<string, { key: string; expiresAt: Date }> = new Map();

  getOrCreate(operationId: string): string {
    const existing = this.store.get(operationId);
    if (existing && existing.expiresAt > new Date()) {
      return existing.key;
    }

    const key = uuidv4();
    this.store.set(operationId, {
      key,
      expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
    });
    return key;
  }
}

バルクヘッドパターン

import PQueue from 'p-queue';

// 異なる操作向けの個別キュー
const retellaiQueues = {
  critical: new PQueue({ concurrency: 10 }),
  normal: new PQueue({ concurrency: 5 }),
  bulk: new PQueue({ concurrency: 2 }),
};

async function prioritizedRetellAICall<T>(
  priority: 'critical' | 'normal' | 'bulk',
  fn: () => Promise<T>
): Promise<T> {
  return retellaiQueues[priority].add(fn);
}

// 使用方法
await prioritizedRetellAICall('critical', () =>
  retellaiClient.processPayment(order)
);

await prioritizedRetellAICall('bulk', () =>
  retellaiClient.syncCatalog(products)
);

タイムアウト階層

const TIMEOUT_CONFIG = {
  connect: 5000,      // 初期接続
  request: 30000,     // 標準リクエスト
  upload: 120000,     // ファイルアップロード
  longPoll: 300000,   // Webhook ロングポーリング
};

async function timedoutRetellAICall<T>(
  operation: 'connect' | 'request' | 'upload' | 'longPoll',
  fn: () => Promise<T>
): Promise<T> {
  const timeout = TIMEOUT_CONFIG[operation];

  return Promise.race([
    fn(),
    new Promise<never>((_, reject) =>
      setTimeout(() => reject(new Error(`Retell AI ${operation} timeout`)), timeout)
    ),
  ]);
}

グレースフルデグラデーション

interface RetellAIFallback {
  enabled: boolean;
  data: any;
  staleness: 'fresh' | 'stale' | 'very_stale';
}

async function withRetellAIFallback<T>(
  fn: () => Promise<T>,
  fallbackFn: () => Promise<T>
): Promise<{ data: T; fallback: boolean }> {
  try {
    const data = await fn();
    // 今後のフォールバック向けにキャッシュを更新
    await updateFallbackCache(data);
    return { data, fallback: false };
  } catch (error) {
    console.warn('Retell AI failed, using fallback:', error.message);
    const data = await fallbackFn();
    return { data, fallback: true };
  }
}

デッドレターキュー

interface DeadLetterEntry {
  id: string;
  operation: string;
  payload: any;
  error: string;
  attempts: number;
  lastAttempt: Date;
}

class RetellAIDeadLetterQueue {
  private queue: DeadLetterEntry[] = [];

  add(entry: Omit<DeadLetterEntry, 'id' | 'lastAttempt'>): void {
    this.queue.push({
      ...entry,
      id: uuidv4(),
      lastAttempt: new Date(),
    });
  }

  async processOne(): Promise<boolean> {
    const entry = this.queue.shift();
    if (!entry) return false;

    try {
      await retellaiClient[entry.operation](entry.payload);
      console.log(`DLQ: Successfully reprocessed ${entry.id}`);
      return true;
    } catch (error) {
      entry.attempts++;
      entry.lastAttempt = new Date();

      if (entry.attempts < 5) {
        this.queue.push(entry);
      } else {
        console.error(`DLQ: Giving up on ${entry.id} after 5 attempts`);
        await alertOnPermanentFailure(entry);
      }
      return false;
    }
  }
}

低下状態を含むヘルスチェック

type HealthStatus = 'healthy' | 'degraded' | 'unhealthy';

async function retellaiHealthCheck(): Promise<{
  status: HealthStatus;
  details: Record<string, any>;
}> {
  const checks = {
    api: await checkApiConnectivity(),
    circuitBreaker: retellaiBreaker.stats(),
    dlqSize: deadLetterQueue.size(),
  };

  const status: HealthStatus =
    !checks.api.connected ? 'unhealthy' :
    checks.circuitBreaker.state === 'open' ? 'degraded' :
    checks.dlqSize > 100 ? 'degraded' :
    'healthy';

  return { status, details: checks };
}

手順

ステップ 1: サーキットブレーカーを実装

Retell AI 呼び出しをサーキットブレーカーでラップします。

ステップ 2: べき等性キーを追加

操作向けに決定的なキーを生成します。

ステップ 3: バルクヘッドを設定

異なる優先度向けに個別キューを作成します。

ステップ 4: デッドレターキューをセットアップ

永続的な障害をグレースフルに処理します。

出力

• Retell AI 呼び出しを保護するサーキットブレーカー
• 重複を防止するべき等性
• 実装されたバルクヘッド分離
• 失敗した操作向けの DLQ

エラーハンドリング

問題	原因	解決方法
サーキットが開いたままになる	閾値が低すぎる	エラーパーセンテージを調整
操作の重複	べき等性キーが不足	べき等性キーを追加
キューが満杯	レート が高すぎる	並行処理を増加
DLQ が増加	永続的な障害	根本原因を調査

例

クイックサーキットチェック

const state = retellaiBreaker.stats().state;
console.log('Retell AI circuit:', state);

リソース

• Circuit Breaker Pattern
• Opossum Documentation
• Retell AI Reliability Guide

次のステップ

ポリシー強制については retellai-policy-guardrails を参照してください。