本番環境の人工知能（AI）エージェントは、静かに失敗することがあります。もっともらしいが不正確な回答を返したり、無限の推論ループに陥ったり、エラーアラートをトリガーせずに間違ったツールを選択したりします。これらの失敗により、標準のログやメトリクスでは意思決定のプロセスが捉えられないため、本番環境のエージェント動作のデバッグが困難になります。
Amazon Bedrock AgentCore Observabilityは、メトリクス、トレース、構造化ログの3つのレイヤーでエージェントの実行への可視性を提供することで、これらのデバッグの課題に対処します。各推論ステップを追跡し、ツール呼び出しを検査し、実行が期待から逸脱した場所を正確に特定できます。この可視性により、障害が発生したことを検出する段階から、なぜ発生したのかを理解する段階へと移行できます。明示的なエラーが発生していない場合でも、エージェントがどのように推論したか、どのツールを選択したか、ワークフローがどこで中断したかをトレースできます。この記事では、組み込みの可観測性機能を使用して本番環境のエージェント障害をデバッグする方法を学びます。一般的な障害パターンを説明し、トレースとメトリクスでエージェントの動作を分析する方法を示し、無限ループやツール呼び出しの失敗などの問題を解決するための構造化されたワークフローを提供します。これは2回シリーズの第1回です。第2回ではパフォーマンス最適化とメモリ管理を扱います。
前提条件
この記事のチュートリアルに従う前に、必要なアクセス権とツールが揃っていることを確認してください。
AWSアカウントが必要で、Amazon Bedrock AgentCoreへのアクセスが有効になっていること、Amazon CloudWatchダッシュボードと基本的なログクエリに精通していること、AWS Identity and Access Management（IAM）ロールとポリシーに関する実用的な知識があることが必要です。また、アカウントでCloudWatch Transaction Searchが有効になっていること（「可観測性の有効化」セクションを参照）、およびAmazon Bedrock AgentCoreエージェントが既にデプロイされているか、デプロイする権限が必要です。
エージェントの障害パターンを理解する
AIエージェントの障害の仕方は、従来のアプリケーションとは異なります。実行は成功しても不正確な回答を返したり、ワークフローが不完全だったり、予期しないツールの使用が見られることがあります。これらの問題は、標準のエラーアラートをトリガーせずに本番環境で発生することが多く、検出と診断がより困難になります。ほとんどの本番環境の問題は、品質、信頼性、効率の3つのカテゴリに分類されます。これらのパターンを理解することで、調査を迅速に絞り込むことができます。
品質の障害
品質の障害は、エージェントがタスクを完了したが誤った結果を返す場合に発生します。監視システムは多くの場合、実行成功を示しますが、ユーザーは不正確な応答を受け取ります。幻覚や事実誤認が頻繁に発生します。エージェントは存在しないポリシーを参照したり、ギャップを埋めるためにデータを生成したりする可能性があります。マルチエージェントシステムでは、あるエージェントの出力が別のエージェントの入力になると、これらのエラーが伝播する可能性があります。推論の問題も表面化する可能性があります。エージェントは同じ誤った計算を繰り返したり、不適切なツールを選択したりするかもしれません。このような場合、実行トレースを確認することで、論理がどこで崩れたかを特定できます。
信頼性の問題
信頼性の問題は、エージェントがワークフローを完了するのを妨げます。
ツール呼び出しの失敗は一般的な原因です。エージェントは、資格情報の欠如により401エラー、ロールに権限がないために403エラー、または無効な入力により400エラーを受け取る可能性があります。各エラーは異なる根本原因を示します。
また、コンテキストの喪失が発生する場合もあります。これは、エージェントがセッション状態を保持できず、フォローアップリクエストを新しい会話として扱うことです。これは通常、セッション管理またはメモリ設定に問題があることを示しています。
効率の問題
効率の問題は、正確性ではなくコストとパフォーマンスに影響します。高レイテンシーは応答時間を遅くし、ユーザーエンゲージメントを低下させます。応答に時間がかかりすぎると、ユーザーはインタラクションを放棄したり、リクエストを再試行したりします。過剰なトークン使用は、結果を改善せずにコストを増加させます。これは、エージェントが過度に冗長な応答を生成したり、不必要に完全なドキュメントを取得したり、結果をキャッシュせずにツール呼び出しを繰り返したりする場合に見られます。
デバッグツールキット
メトリクス、トレース、構造化ログの3つの可観測性レイヤーを通じて、エージェントの動作を監視、トレース、分析できます。これらの機能は連携して、問題を検出してから根本原因を特定するのに役立ちます。
Amazon CloudWatchダッシュボード
Amazon CloudWatchメトリクス（セッション量、レイテンシー、トークン使用量、エラー率など）を通じて、エージェントのパフォーマンスをリアルタイムで監視します。これらのメトリクスにより、エージェント、メモリシステム、ツール統合全体の可視性が得られます。
GenAI可観測性ダッシュボードは、セッション量、呼び出しレイテンシー、トークン使用量、エラー率を統一ビューで表示します。これらのメトリクスをエージェントID、セッションID、または時間範囲でフィルタリングして、特定のパフォーマンスパターンに焦点を当てることができます。
異常を検出すると、CloudWatchアラートがレイテンシーが許容しきい値を超えたり、エラー率が通常レベルを超えて急上昇したりした場合に自動的に通知します。
OpenTelemetryトレース
ダッシュボードはシステムレベルの動作を示します。トレースは各リクエストがどのようにステップバイステップで実行されるかを示します。
Amazon Bedrock AgentCoreは、分散トレース、構造化スパンレベルのログ、メトリクスをbedrock-agentcore CloudWatch名前空間で出力します。このテレメトリはOpenTelemetry（OTEL）プロトコルに従い、デフォルトでAmazon CloudWatchにルーティングされます。組織がDatadog、Grafana Cloud、またはElastic Observabilityを使用している場合、追加のインストルメンテーションなしで同じテレメトリをそれらのバックエンドにエクスポートできます。
各トレースは、推論ステップ、ツール呼び出し、メモリ検索、最終出力など、完全な実行フローをキャプチャします。この細かい可視性により、実行が期待される動作から逸脱した場所を特定し、問題につながった一連の決定を示します。
監視すべき主要メトリクス
3つのメトリクスカテゴリに焦点を当てます：パフォーマンス、リソース使用量、信頼性。
パフォーマンスメトリクス
50パーセンタイル、95パーセンタイル、99パーセンタイルのレイテンシーを追跡します。高いレイテンシーは、多くの場合、下流のボトルネックを示します。メモリ検索時間とツール応答時間を個別に測定します。これにより、どのコンポーネントが実行を遅くしているかを特定できます。
リソースメトリクス
セッション期間は使用パターンを明らかにします。短いセッションはユーザーの不満を示す可能性があります。長いセッションはループや複雑なワークフローを示す可能性があります。同時セッション数は、システムがサポートするアクティブなインタラクションの数を示します。トークン使用量はコストに直接影響します。入力トークンと出力トークンを個別に監視して、非効率性を特定します。
信頼性メトリクス
エラー率は、実行の失敗頻度を示します。
タイプ別に分類します：
認証エラー。
認可エラー。
検証エラー。
タイムアウトエラー。
いずれかのカテゴリでスパイクが見られた場合、調査すべき特定の領域を示しています。
可観測性の有効化
デバッグを開始する前に、アカウントでCloudWatch Transaction Searchを有効にします。これにより、Amazon Bedrock AgentCoreがトレースとメトリクスデータをCloudWatchに送信できるようになります。この設定を有効にすると、サービスはエージェント、メモリシステム、ツール統合全体で可観測性データの収集を開始します。その後、CloudWatchダッシュボードとLogs Insightsクエリを通じてこのデータにアクセスできます。
ステップバイステップのトラブルシューティングワークフロー
次のシナリオでは、2つの最も一般的な本番環境障害を診断および解決する方法を説明します。各シナリオでは、観察される症状、実行するAmazon CloudWatch Logs Insightsクエリ（通常2〜3分かかります）、および実装する修正を示します。CloudWatch Logs Insightsは、Bedrock AgentCoreからの構造化ログデータをリアルタイムで検索および分析できるフルマネージドクエリサービスです。CloudWatchコンソールのLogsメニューからアクセスします。
シナリオ1：無限エージェントループのデバッグ
無限ループは、エージェントに適切な終了条件がないか、間違いを認識できない場合に発生します。ログを詳しく調べる前に、3つの最も一般的な根本原因を理解することで診断が迅速化されます。
無限ループの一般的な原因
プロンプト設計の不備：システムプロンプトに明確な終了条件が設定されていない場合に発生します。プロンプトは、合理的な試行回数、タスクが不可能な場合の宣言方法、または人間へのエスカレーション方法を指定していない可能性があります。ループ検出の欠如：エージェントの推論フレームワークが繰り返しアクションを認識しない場合に発生します。以前の試行を追跡する明示的なロジックがないと、エージェントは「これを3回試したがうまくいかない」というパターンを検出できません。誤ったツール選択：エージェントが一貫して間違ったツールを選択する場合に発生します。たとえば、計算機の代わりにウェブ検索ツールを使用して数学の問題を解決しようとするなどです。
注意すべき症状
エージェントがループに入ると、トークン使用量が大幅に増加します。セッション期間も通常の範囲を超えて増加します。場合によっては、エージェントはユーザー入力なしで複数の応答を生成します。注目すべき点は、エラー率が低いままであることです。エージェントはクラッシュしていないため、単にタスクを完了できないだけです。
CloudWatch GenAI可観測性ダッシュボードには、合計266,900トークンが消費され、エラー率は0%と表示されます。高いトークン使用量とエラーなしの組み合わせは、無限ループの主要な指標です。エージェントは実行中ですが、タスクを完了できません。
プロンプトエンジニアリングの不良の診断
まず、問題のあるセッションを特定します。CloudWatch Logs Insightsで次のクエリを実行して、トークン使用量が異常に高いセッションを見つけます：
fields @timestamp, SessionId, TokenUsage | filter TokenUsage > 10000 | sort TokenUsage desc | limit 20
最も消費量の多いセッションを選択し、SessionIdをメモします。次に、そのセッション内のエージェントの推論パターンを調べます：
fields @timestamp, @message, RequestId | filter SessionId = "" | filter Operation like /InvokeAgent/ | sort @timestamp asc | limit 1000
セッションの詳細には、177スパンの単一トレースと平均レイテンシー85,590ミリ秒（約85秒）が表示されます。通常のエージェント応答は1〜5秒で完了します。スパン数と実行時間の両方が、エージェントがループに入ったことを確認します。
エージェントの推論内で繰り返しパターンを探します。次のログシーケンスはループの明確な指標です：
"計算機ツールを使用して、入力25を試す" "結果：24.95" "これは正しくない、再試行" "計算機ツールを使用して、入力25を試す" "結果：24.95" "これは正しくない、再試行"
OpenTelemetryトレースのウォーターフォールは根本原因を明らかにします：システムプロンプトがエージェントに「決して諦めない」および「正確な答えが得られるまで試行を続ける」と指示し、終了条件がないことです。このプロンプト設計の欠陥が、図2に示す177スパンのループを直接引き起こしました。
プロンプト設計の問題を修正するには、エージェントのシステムプロンプトに明示的な終了条件を追加します。「同じアクションを3回試しても成功しない場合は、停止して、なぜタスクを完了できないかをユーザーに説明する」などの指示を含めます。セッションごとの最大トークン制限を設定します。通常、会話エージェントの場合は5,000〜10,000トークン、推論ステップ制限を10〜15ステップ（内部ロジックに関係なくハードストップ）として実装します。
ループ検出失敗の診断
次のクエリを実行して、ツール呼び出しシーケンスを調べます：
fields @timestamp, ToolName, ToolInput, ToolOutput | filter SessionId = "" | filter Operation like /InvokeTool/ | sort @timestamp asc
結果の次のパターンは、ループ検出の失敗を確認します：
2026-02-02 22:02:39 | calculate_percentage | {"value": 25, "total": 100} | 25.0 2026-02-02 22:02:45 | calculate_percentage | {"value": 25, "total": 100} | 25.0 2026-02-02 22:02:51 | calculate_percentage | {"value": 25, "total": 100} | 25.0 [40回以上繰り返し]
CloudWatch Logs Insightsの結果は、86回の繰り返しcalculate_percentageツール呼び出しを示し、入力はほぼ同一で、24.954％や25.049％などの値を返し、プロンプトが要求した正確な25.00％には決して達しませんでした。列全体での繰り返されるニアミス値は、ループ検出の失敗を確認します。
ループ検出の失敗を修正するには、エージェントフレームワークにループ検出を追加します。ツール呼び出しと推論ステップを追跡します。