本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 對 Connect AI 代理器問題進行故障診斷
<a name="ts-ai-agents-self-service"></a>

使用此主題來協助診斷和解決 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 代理器的記錄和追蹤
<a name="viewing-logs-for-connect-ai-agents-self-service"></a>

若要有效疑難排解 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 Logging[Monitor 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 記錄。

# 對客服人員自助服務問題進行故障診斷
<a name="ts-agentic-self-service"></a>

以下是[客服人員自助服務](agentic-self-service.md)特有的問題。

## AI 代理器未回應客戶
<a name="ts-ai-agent-not-responding"></a>

如果您的 AI 代理器正在處理請求，但客戶沒有看到任何回應，協調提示可能缺少必要的訊息格式指示。

協調器 AI 代理器只會在模型的回應包裝在`<message>`標籤中時向客戶顯示訊息。如果您的提示未指示模型使用這些標籤，則不會將回應轉譯給客戶。

**解決方案**：確保您的協同運作提示包含格式化指示，要求模型在`<message>`標籤中包裝回應。如需詳細資訊，請參閱[訊息剖析](use-orchestration-ai-agent.md#message-parsing)。

## MCP 工具調用失敗
<a name="ts-mcp-tool-failures"></a>

如果您的 AI 代理器無法在對話期間叫用 MCP 工具，請檢查下列項目：
+ **安全設定檔許可** – 驗證 AI 代理器的安全設定檔是否授予其所需特定 MCP 工具的存取權。AI 代理程式只能叫用具有明確存取許可的工具。
+ **閘道連線** – 確認 Amazon Bedrock AgentCore Gateway 已正確設定，且探索 URL 有效。確認傳入身分驗證對象已設定為閘道 ID。在 AgentCore 主控台中檢查閘道狀態。
+ **API 端點運作狀態** – 確認 MCP 工具後方的後端 API 或 Lambda 函數正在執行並正確回應。檢查 CloudWatch Logs 是否有目標服務中的錯誤。

## MCP 工具的 IAM 許可
<a name="ts-mcp-iam-permissions"></a>

如果 MCP 工具呼叫傳回存取遭拒錯誤，請確認 IAM 角色具有必要的許可：
+ **Amazon Bedrock AgentCore Gateway 角色** – 閘道的執行角色必須具有叫用 MCP 工具所連線後端 APIs或 Lambda 函數的許可。
+ **Amazon Connect 服務連結角色** – Amazon Connect 服務連結角色必須具有叫用 Amazon Bedrock AgentCore Gateway 的許可。

# 常見問題
<a name="ts-common-self-service-issues"></a>

## 將最新的 AWS SDK 與您的 Lambda 函數綁定
<a name="ts-lambda-sdk-bundling"></a>

如果您直接從 Lambda 函數呼叫 Connect AI 代理程式 APIs，則必須將最新版本的 AWS SDK 與函數程式碼封裝並綁定。Lambda 執行時間環境可能包含不支援最新 Connect AI 代理器 API 模型和功能的舊版 SDK。

**徵狀**：使用過時的 SDK 版本時，您可能會遇到參數驗證例外狀況，或要求無提示地忽略輸入參數。

為了避免 API 模型偏離，請在部署套件中包含最新的 AWS SDK 做為相依性，或做為 Lambda 層，而不是依賴 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)。

# （舊版） 自助式問題
<a name="ts-non-agentic-self-service"></a>

以下是[舊版自助式服務](generative-ai-powered-self-service.md)特有的問題。

## 客戶意外收到「呈報至客服人員...」
<a name="customers-unexpectedly-receiving-escalating-to-agent"></a>

自助式服務機器人互動期間發生錯誤，或模型未針對 `SELF_SERVICE_PRE_PROCESS` 產生有效 `tool_use` 回應時，就會發生非預期的客服人員呈報動作。

### 疑難排解步驟
<a name="escalation-ts-steps"></a>

1. **檢查 Connect AI 代理程式日誌**：檢查相關聯日誌項目中的`completion`屬性。

1. **確認停止原因**：確認 `stop_reason` 為 `tool_use`。

1. **確認剖析的回應**：檢查是否已填寫 `parsed_response` 欄位，因為這是您將從模型收到的回應。

### Claude 3 Haiku 的已知問題
<a name="known-issue-with-claude-3-haiku"></a>

如果您使用 Claude 3 Haiku 進行自助式服務預先處理，則有個已知問題是，它會以文字形式產生 `tool_use` JSON，導致 `stop_reason` `end_turn`，而非 `tool_use`。

**解決方案**：新增此指示，更新您的自訂提示，以在 `<tool>` 標籤內包裝 `tool_use` JSON 字串：

```
You MUST enclose the tool_use JSON in the <tool> tag
```

## 自助式服務的聊天或語音通話意外終止
<a name="self-service-unexpectedly-terminating"></a>

此問題可能是因為 Amazon Lex 逾時或 Amazon Nova Pro 組態不正確而發生。這些問題的說明如下。

### 來自 Amazon Lex 的逾時
<a name="timeouts-from-amazon-lex"></a>
+ **徵狀**：Amazon Connect 日誌顯示 [取得客戶輸入內容](get-customer-input.md) 區塊「內部伺服器錯誤」
+ **原因**：您的自助式服務機器人在 10 秒限制內提供結果時逾時。Connect AI 代理器日誌中不會顯示逾時錯誤。
+ **解決方案**：移除複雜的推理來簡化提示，以縮短處理時間。

### Amazon Nova Pro 組態
<a name="amazon-nova-pro-configuration"></a>

如果您將 Amazon Nova Pro 用於自訂 AI 提示，請確保 tool\$1use 範例遵循 [Python 相容格式](create-ai-prompts.md#nova-pro-aiprompt)。