トラブルシューティング

AIエージェントエラーのトラブルシューティング完全ガイド

Media Lab

AIエージェントエラーのトラブルシューティング完全ガイド

AIエージェントを運用していると、様々なエラーに遭遇します。エラーの種類によって原因と対処法が異なり、適切な診断なしには解決が困難です。本記事では、代表的なエラーパターンと体系的なトラブルシューティング方法を解説します。

エラー診断の基本アプローチ

AIエージェントのエラーを解決するには、まず「どの層で問題が起きているか」を特定することが重要です。

エラーの4つの層:

  1. インフラ層: ネットワーク接続、サーバーリソース、APIエンドポイントの問題
  2. 設定層: APIキー、環境変数、設定ファイルの問題
  3. ロジック層: プロンプト設計、ツール定義、ワークフローの問題
  4. LLM層: モデルの限界、ハルシネーション、推論エラーの問題

ログを確認してエラーメッセージの内容からどの層の問題かを特定し、対処法を選択します。

代表的なエラーと対処法

1. API接続エラー（ConnectionError）

症状：requests.exceptions.ConnectionErrorまたはAPIConnectionError

原因と対処法：

  • ネットワーク接続を確認（インターネット接続が切れていないか）
  • APIエンドポイントURLが正しいか確認
  • ファイアウォールやプロキシ設定を確認
  • プロバイダーのステータスページで障害情報を確認（status.openai.com等）

AIエージェントAPIエラーの解決方法でより詳細な対処法を解説しています。

2. 認証エラー（AuthenticationError）

症状：401 UnauthorizedまたはInvalidAPIKey

原因と対処法：

  • APIキーが正しく環境変数に設定されているか確認
  • APIキーが期限切れ・無効化されていないかプロバイダーコンソールで確認
  • 環境変数のスペルミスがないか確認（OPENAI_API_KEYの大文字・アンダースコアに注意）

3. レートリミットエラー（RateLimitError）

症状：429 Too Many Requests

原因と対処法：

  • リクエスト間隔を空ける（Exponential Backoffの実装）
  • 使用量の上位プランへのアップグレード
  • 処理をバッチ化し、一度に大量のリクエストを送らない

AIエージェントのレートリミット対処法で実装例を紹介しています。

4. コンテキスト長超過エラー

症状：context_length_exceededまたはmaximum context length

原因と対処法：

  • 入力テキストを短縮する（長い文書は要約してから送信）
  • より大きなコンテキストウィンドウを持つモデルに変更
  • 会話履歴を定期的に要約して圧縮する

AIエージェントのコンテキスト上限問題で体系的な解決策を解説しています。

5. タイムアウトエラー

症状：TimeoutErrorまたはRequest timed out

原因と対処法：

  • タイムアウト設定を長くする（例：デフォルト30秒→60秒）
  • 処理を分割して1回のリクエストを小さくする
  • ネットワーク環境を確認（高レイテンシの接続環境の場合）

ログ取得と問題特定の方法

効果的なトラブルシューティングにはログが不可欠です。

Pythonでのシンプルなログ設定:

import logging

logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('agent.log'),
        logging.StreamHandler()
    ]
)

logger = logging.getLogger(__name__)

ツール呼び出しのたびにログを記録することで、どのステップで問題が発生したかを追跡できます。

n8nでのエラーハンドリング設計

n8nでワークフローを構築している場合は、Error Triggerノードを使って失敗した実行の詳細を取得できます。

エラーが発生したノードの情報、エラーメッセージ、実行ペイロードを確認し、原因を特定します。重要なワークフローにはエラー通知（Slackアラート等）を設定しておくことを強くお勧めします。

まとめ

AIエージェントのエラーは「インフラ・設定・ロジック・LLM」の4層のどれかに起因することがほとんどです。詳細なログを記録し、エラーメッセージから層を特定して対処することが効率的なトラブルシューティングの基本です。AIエージェントデバッグのコツも参照して、予防的なデバッグ習慣を身につけましょう。