翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Connect AI エージェントの問題のトラブルシューティング
このトピックは、Connect AI エージェントに関する一般的な問題の診断と解決に役立ちます。
**Topics**
+ [Connect AI エージェントのログ記録とトレース](viewing-logs-for-connect-ai-agents-self-service.md)
+ [エージェントセルフサービスの問題のトラブルシューティング](ts-agentic-self-service.md)
+ [一般的な問題](ts-common-self-service-issues.md)
+ [(レガシー) セルフサービスの問題](ts-non-agentic-self-service.md)
# Connect AI エージェントのログ記録とトレース
Connect AI エージェントの問題を効果的にトラブルシューティングするには、次のログ記録とトレースオプションを使用します。
+ **ListSpans API (オーケストレーター AI エージェントに推奨)**: [ListSpans](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_ListSpans.html) API を使用してセッションの AI エージェント実行トレースを取得します。これは、オーケストレーター AI エージェントインタラクションのデバッグに推奨される出発点です。エージェントオーケストレーションフロー、LLM インタラクション、ツール呼び出しをきめ細かく可視化できるため、AI エージェントがリクエストを通じてどのように推論したか、どのツールを選択して実行したかを追跡できます。
+ **CloudWatch Logs**: 「」の手順に従って、Connect AI エージェントの CloudWatch ログ記録を有効にします[Connect AI エージェントをモニタリングする](monitor-ai-agents.md)。
従来のセルフサービスインタラクションでは、イベントタイプのログエントリが次の形式で生成`TRANSCRIPT_SELF_SERVICE_MESSAGE`されます。
```
{
"assistant_id": "{UUID}",
"event_timestamp": 1751414298692,
"event_type": "TRANSCRIPT_SELF_SERVICE_MESSAGE",
"session_id": "{UUID}",
"utterance": "[CUSTOMER]...",
"prompt": "{prompt used}",
"prompt_type": "SELF_SERVICE_PRE_PROCESS|SELF_SERVICE_ANSWER_GENERATION",
"completion": "{Response from model}",
"model_id": "{model id e.g.: us.amazon.nova-pro-v1:0}",
"session_message_id": "{UUID}",
"parsed_response": "{model response}"
}
```
エージェントセルフサービスインタラクションは、イベントタイプ のログエントリを生成します`TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION`。これらのエントリには、ツール設定を含むプロンプト、ツール呼び出しと結果を含む会話履歴、モデルの完了、AI エージェント設定などの完全なオーケストレーションコンテキストが含まれます。次の例は、キーフィールドを示しています。
```
{
"assistant_id": "{UUID}",
"event_timestamp": 1772748470993,
"event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
"session_id": "{UUID}",
"prompt": "{full prompt including system instructions, tool configs, and conversation history}",
"prompt_type": "ORCHESTRATION",
"completion": "{model response with message and tool use}",
"model_id": "{model id e.g.: us.anthropic.claude-haiku-4-5-20251001-v1:0}",
"parsed_response": "{parsed customer-facing message}",
"generation_id": "{UUID}",
"ai_agent_id": "{UUID}"
}
```
+ **Amazon Lex ログ記録 (セルフサービスのみ)**: Amazon Lex [ V2 のエラーログによるエラーのログ記録の手順に従ってAmazon Lexログ記録](https://docs.aws.amazon.com/lexv2/latest/dg/error-logs.html)を有効にします。
+ **Amazon Connect ログ記録**: Amazon Connect フローに [ログ記録動作の設定](set-logging-behavior.md) フローブロックを追加して Amazon Connect ログ記録を有効にします。
# エージェントセルフサービスの問題のトラブルシューティング
以下の問題は[、エージェントセルフサービス](agentic-self-service.md)に固有の問題です。
## AI エージェントが顧客に応答しない
AI エージェントがリクエストを処理しているが、お客様にレスポンスが表示されない場合、オーケストレーションプロンプトに必要なメッセージフォーマット手順が欠落している可能性があります。
オーケストレーター AI エージェントは、モデルのレスポンスが``タグでラップされている場合にのみ、顧客にメッセージを表示します。プロンプトがモデルにこれらのタグを使用するように指示しない場合、レスポンスは顧客にレンダリングされません。
**解決策**: オーケストレーションプロンプトに、モデルがレスポンスを``タグでラップする必要があるフォーマット手順が含まれていることを確認します。詳細については、「[メッセージ解析](use-orchestration-ai-agent.md#message-parsing)」を参照してください。
## MCP ツール呼び出しの失敗
AI エージェントが会話中に MCP ツールを呼び出せない場合は、以下を確認してください。
+ **セキュリティプロファイルのアクセス許可** – AI エージェントのセキュリティプロファイルが、必要な特定の MCP ツールへのアクセスを許可していることを確認します。AI エージェントは、アクセス許可が明示的に付与されているツールのみを呼び出すことができます。
+ **ゲートウェイ接続** — Amazon Bedrock AgentCore Gateway が正しく設定され、検出 URL が有効であることを確認します。インバウンド認証対象者がゲートウェイ ID に設定されていることを確認します。AgentCore コンソールでゲートウェイのステータスを確認します。
+ **API エンドポイントのヘルス** — MCP ツールの背後にあるバックエンド API または Lambda 関数が実行され、正しく応答していることを確認します。CloudWatch Logs でターゲットサービスのエラーを確認します。
## MCP ツールの IAM アクセス許可
MCP ツール呼び出しがアクセス拒否エラーを返す場合は、IAM ロールに必要なアクセス許可があることを確認します。
+ **Amazon Bedrock AgentCore Gateway ロール** – ゲートウェイの実行ロールには、MCP ツールが接続するバックエンド APIs または Lambda 関数を呼び出すアクセス許可が必要です。
+ **Amazon Connect サービスにリンクされたロール** – Amazon Connect サービスにリンクされたロールには、Amazon Bedrock AgentCore Gateway を呼び出すためのアクセス許可が必要です。
# 一般的な問題
## 最新の AWS SDK を Lambda 関数にバンドルする
Lambda 関数から直接 Connect AI エージェント APIs呼び出す場合は、関数コードとともに最新バージョンの AWS SDK をパッケージ化してバンドルする必要があります。Lambda ランタイム環境には、最新の Connect AI エージェント API モデルと機能をサポートしていない古いバージョンの SDK が含まれている場合があります。
**症状**: 古い SDK バージョンを使用すると、パラメータ検証の例外が発生したり、リクエスト入力パラメータがサイレントに無視されたりすることがあります。
API モデルのドリフトを回避するには、Lambda ランタイムによって提供される AWS SDK に依存するのではなく、デプロイパッケージの依存関係として、または Lambda レイヤーとして最新の SDK を含めます。SDK をバンドルする手順は言語によって異なります。例えば、Node.js の場合は、[「依存関係を持つデプロイパッケージの作成](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-package.html#nodejs-package-create-dependencies)」を参照してください。その他の言語については、対応する Lambda デプロイパッケージドキュメントを参照してください。複数の関数間で SDK を共有するには、[「Lambda レイヤー](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html)」を参照してください。
# (レガシー) セルフサービスの問題
以下の問題は、[レガシーセルフサービス](generative-ai-powered-self-service.md)に固有のものです。
## 予期せず顧客に「エージェントにエスカレーションしています...」が表示される
予期しないエージェントエスカレーションは、セルフサービスボットの操作中にエラーが発生した場合、またはモデルが `SELF_SERVICE_PRE_PROCESS` に対して有効な `tool_use` レスポンスを生成しない場合に発生します。
### トラブルシューティングのステップ
1. **Connect AI エージェントログを確認する**: 関連するログエントリの `completion` 属性を調べます。
1. **停止理由を検証する**: `stop_reason` が `tool_use` であることを確認します。
1. **解析されたレスポンスを検証する**: `parsed_response` フィールドが入力されているかどうかを確認します。これは、モデルから受け取るレスポンスを表すためです。
### Claude 3 Haiku の既知の問題
Claude 3 Haiku をセルフサービスの前処理に使用している場合、`tool_use` JSON をテキストとして生成し、`tool_use` の代わりに `end_turn` の `stop_reason` が発生するという既知の問題があります。
**解決策**: カスタムプロンプトを更新して、次の指示を追加して `tool_use` JSON 文字列を `` タグ内にラップします。
```
You MUST enclose the tool_use JSON in the tag
```
## セルフサービスチャットまたは音声通話が予期せず終了する
この問題は、Amazon Lex からのタイムアウトまたは誤った Amazon Nova Pro 設定が原因で発生する可能性があります。これらの問題について以下で説明します。
### Amazon Lex からのタイムアウト
+ **症状**: Amazon Connect ログに [顧客の入力を取得する](get-customer-input.md) ブロックの「内部サーバーエラー」が表示されます
+ **原因**: セルフサービスボットが 10 秒の制限内に結果を提供中にタイムアウトしました。タイムアウトエラーは Connect AI エージェントログに表示されません。
+ **解決策**: 複雑な推論を削除してプロンプトを簡素化し、処理時間を短縮します。
### Amazon Nova Pro の設定
カスタム AI プロンプトに Amazon Nova Pro を使用している場合は、tool\$1use の例が [Python 互換形式](create-ai-prompts.md#nova-pro-aiprompt)に従っていることを確認してください。