本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 解决 Connect AI 代理问题
<a name="ts-ai-agents-self-service"></a>

使用本主题来帮助诊断和解决 Connect AI 代理的常见问题。

**Topics**
+ [Connect 人工智能代理的日志记录和跟踪](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 人工智能代理的日志记录和跟踪
<a name="viewing-logs-for-connect-ai-agents-self-service"></a>

要有效地解决 Connect AI 代理问题，请使用以下日志和跟踪选项。
+ **ListSpans API（推荐用于 Orchestrator AI 代理）**：使用 [ListSpans](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_ListSpans.html)API 检索会话的 AI 代理执行跟踪。这是调试 Orchestrator AI 代理交互的推荐起点，因为它提供了代理编排流程、LLM 交互和工具调用的精细可见性，允许您跟踪 AI 代理是如何通过请求推理的，以及它选择和执行了哪些工具。
+ **CloudWatch 日志**：按照中的步骤为您的 Connect AI 代理启用 CloudWatch 日志记录[监控 Connect 人工智能代理](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 代理正在处理请求，但客户未看到任何响应，则编排提示可能缺少所需的消息格式化说明。

Orchestrator 人工智能代理仅在`<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 日志中是否存在目标服务中的错误。

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

如果 MCP 工具调用返回访问被拒绝的错误，请验证 IAM 角色是否具有所需的权限：
+ **Amazon Bedrock AgentCore Gateway 角色** — 网关的执行角色必须有权调用您的 MCP 工具所连接的后端 APIs 或 Lambda 函数。
+ **Amazon Connect 服务相关角色** — Amazon Connect 服务相关角色必须具有调用 Amazon Bedro AgentCore ck Gateway 的权限。

# 常见问题
<a name="ts-common-self-service-issues"></a>

## 将最新的软件 AWS 开发工具包与您的 Lambda 函数捆绑在一起
<a name="ts-lambda-sdk-bundling"></a>

如果您 APIs 直接从 Lambda 函数调用 Connect AI 代理，则必须将最新版本的软件 AWS 开发工具包与您的函数代码打包并捆绑在一起。Lambda 运行时环境可能包含不支持最新的 Connect AI 代理 API 模型和功能的旧版本的软件开发工具包。

**症状**：使用过时的 SDK 版本时，您可能会遇到参数验证异常或请求输入参数被静默忽略的情况。

为避免 API 模型偏差，请将最新的 AWS 软件开发工具包作为依赖项包含在您的部署包中或作为 Lambda 层，而不是依赖 Lambda 运行时提供的软件开发工具包。捆绑软件开发工具包的步骤因语言而异。例如，对于 Node.js，请参阅[创建具有依赖项的部署包](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-package.html#nodejs-package-create-dependencies)。有关其他语言的信息，请参阅相应的 Lambda 部署打包文档。有关跨多个函数共享软件开发工具包的信息，请参阅 [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_use` JSON 字符串封装在 `<tool>` 标签内：

```
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 用于自定义人工智能提示，请确保 tool\$1use 示例遵循[与 Python 兼容的格式](create-ai-prompts.md#nova-pro-aiprompt)。