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

# 使用 CloudWatch 日志监控 Connect 人工智能代理
<a name="monitor-ai-agents"></a>

要了解 Connect AI 代理向您的代理提供的实时建议，以及他们通过自然语言理解检测到的客户意图，您可以查询 CloudWatch 日志。 CloudWatch 通过日志，您可以了解整个联系历程：对话、触发因素、意图、推荐。您也可以使用此信息进行调试，或者在联系他们寻求帮助 支持 时将其提供给他们。

本主题介绍如何为 Connect AI 代理启用日志记录。

**Topics**
+ [所需的 IAM 权限](#permissions-cw-q)
+ [启用日志记录](#enable-assistant-logging)
+ [支持的日志类型](#supported-log-types-q)
+ [检查 CloudWatch 日志配额](#cwl-quotas)
+ [使用交互式处理程序记录 CloudWatch 事件](#documenting-cw-events-ih)
+ [调试助理日志的常见查询示例](#example2-assistant-log)

## 所需的 IAM 权限
<a name="permissions-cw-q"></a>

在启用 Connect 助手的日志记录之前，请检查您是否具有以下 AWS Identity and Access Management 权限。登录 Amazon Connect 控制台的用户账户需要这些信息：
+ `wisdom:AllowVendedLogDeliveryForResource`：要求允许为助理资源传送日志。

要查看具有特定日志记录目标所需全部权限的 IAM 角色示例，请参阅[需要额外权限的日志记录 [V2]](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html#AWS-vended-logs-permissions-V2)。该主题包含不同日志记录目标的示例，例如发送到日志的 CloudWatch 日志和发送到 Amazon S3 的日志。这些示例展示了如何允许更新您的特定日志目标资源。

## 为 Connect AI 代理启用日志记录
<a name="enable-assistant-logging"></a>

要启用 Connect AI 代理的日志记录，请使用 CloudWatch API。完成以下步骤。

1. 获取您的*助手*的 ARN（也称为其[*域*](ai-agent-initial-setup.md#ai-agent-requirements)名）。[创建助手后，您可以从 A](ai-agent-initial-setup.md#enable-ai-agents-step1) mazon Connect 控制台或通过调用 API 来获取它的 ARN。[GetAssistant](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_GetAssistant.html)ARN 遵循以下格式：

   `arn:aws:wisdom:your-region:your-account-id:assistant/assistant-id`

1. 调用 [PutDeliverySource](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliverySource.html)：使用此 CloudWatch API 为助手创建传送来源。将助理的 ARN 作为 `resourceArn` 传输。对于 `logType`，指定 `EVENT_LOGS` 从助理收集日志。

   ```
   {
       "logType": "EVENT_LOGS",
       "name": "your-assistant-delivery-source",
       "resourceArn": "arn:aws:wisdom:your-region:your-account-id:assistant/assistant_id
   }
   ```

1. 调用 [PutDeliveryDestination](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliveryDestination.html)：使用此 CloudWatch API 配置日志的存储位置。您可以选择 CloudWatch 日志、Amazon S3 或 Amazon Data Firehose 作为存储日志的目标。您必须为日志的存储位置指定其中一个目标选项的 ARN。您可以选择日志的 `outputFormat` 作为以下选项之一：`json`、`plain`、`w3c`、`raw`、`parquet`。

   以下示例说明如何将日志配置为以 JSON 格式存储在 Amazon CloudWatch 日志组中。

   ```
   {
       "deliveryDestinationConfiguration": {
           "destinationResourceArn": "arn:aws:logs:your-region:your-account-id:log-group:your-log-group-name:*"
       },
       "name": "string",
       "outputFormat": "json",
       "tags": {
           "key": "value"
       }
   }
   ```

1. 调用 [CreateDelivery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateDelivery.html)：使用此 CloudWatch API 将传送源链接到您在之前的步骤中创建的配送目的地。此 API 操作将发送源与最终目的地关联起来。

   ```
   {
       "deliveryDestinationArn": "string",
       "deliverySourceName": "string",
       "tags": {
           "string": "string"
       }
   }
   ```

## 支持的日志类型
<a name="supported-log-types-q"></a>

Connect AI 代理支持以下日志类型：
+ `EVENT_LOGS`：用于跟踪 Connect 助手在通话、聊天、任务和发送电子邮件期间的事件的日志。

## 检查 CloudWatch 日志配额
<a name="cwl-quotas"></a>

我们建议您查看 [Amazon CloudWatch Logs 终端节点和配](https://docs.aws.amazon.com/general/latest/gr/cwl_region.html)额，以查看是否存在与 CloudWatch 日志传输相关的 API 调用的配额。配额设置了您可以调用 API 或创建资源的最大次数。超过限制会导致 `ServiceQuotaExceededException` 错误。

## 使用交互式处理程序记录 CloudWatch 事件
<a name="documenting-cw-events-ih"></a>

### 事件类型定义
<a name="event-type-definitions"></a>

下表描述了每个事件类型。请注意，不同的事件类型包含不同的字段。有关每个字段的详细信息，请参阅[字段定义](#field-definitions)部分。


| EventType | 定义 | 
| --- | --- | 
| TRANSCRIPT\$1CREATE\$1SESSION | 在创建新的 Connect AI 代理会话时记录。这标志着开始对话。 | 
| TRANSCRIPT\$1INTENT\$1TRIGGERING\$1REFERENCE | 在对话中检测到特定的客户意图时记录，这可能会触发自动回复或工作流程。 | 
| TRANSCRIPT\$1LARGE\$1LANGUAGE\$1MODEL\$1INVOCATION | 当调用大语言模型（LLM）来生成回复或处理对话内容时记录。记录到 LLM 的输入和来自 LLM 的输出。 | 
| TRANSCRIPT\$1QUERY\$1ASSISTANT | 在调用以下 Connect AI 代理之一时记录： AnswerRecommendation CaseSummarization、 EmailGenerativeAnswer、 EmailOverview、 EmailResponse、、 ManualSearch、 NoteTaking。 | 
| TRANSCRIPT\$1RECOMMENDATION | 当系统向座席或客户提供建议（可能包括知识文章、生成的回复或推荐的操作）时记录。 | 
| TRANSCRIPT\$1RESULT\$1FEEDBACK | 在提供有关搜索或查询结果的有用性或相关性的反馈时记录。 | 
| TRANSCRIPT\$1SELF\$1SERVICE\$1MESSAGE | 当客户与 C SelfService onnect 人工智能代理互动时已登录 | 
| TRANSCRIPT\$1SESSION\$1POLLED | 当系统检测到代理已连接到会话时记录（调用 GetRecommendations API 后会对会话进行轮询） | 
| TRANSCRIPT\$1TRIGGER\$1DETECTION\$1MODEL\$1INVOCATION | 当调用触发器检测模型以确定对话是否有意图时记录 | 
| TRANSCRIPT\$1UTTERANCE | 当对话中的任何参与者发送消息时记录，此时记录实际的对话内容。 | 

### 字段定义
<a name="field-definitions"></a>

下表描述了每个元素。


| 字段 | 定义 | 
| --- | --- | 
| ai\$1agent\$1id | Connect AI 代理资源的唯一标识符。 | 
| assistant\$1id | Connect 助手资源的唯一标识符。 | 
| completion | 由 LLM 返回的或为消息生成的原始完成文本。 | 
| connect\$1user\$1arn | 访问会话的 Connect 用户的 Amazon 资源名称（ARN）。 | 
| event\$1timestamp | 事件发生时的 Unix 时间戳（以毫秒为单位）。 | 
| event\$1type | 事件的类型，表示系统中发生了什么操作或进程。 | 
| generation\$1id | 人工智能生成的特定回复的唯一标识符。 | 
| intent | 意图文本或描述。 | 
| intent\$1clicked | 表示建议是否由点击的意图触发的布尔值。 | 
| 意图\$1id | 检测到的意图的唯一标识符。 | 
| issue\$1probability | 在对话中检测到问题的数值概率（0.0–1.0）（概率大于 0.5 将调用意图生成） | 
| is\$1recommendation\$1useful | 表示用户认为结果是否有用的布尔值。 | 
| is\$1valid\$1trigger | 一个布尔值，表示检测模型分析是否产生了有效的触发器。 | 
| model\$1id | 用于调用 LLM 的人工智能模型的标识符。 | 
| parsed\$1response | 语言模型响应的 processed/parsed 版本，通常采用结构化格式。 | 
| 提示 | 用于调用 LLM 的输入提示。 | 
| prompt\$1type | 用于处理消息或查询的 AI 提示类型。 | 
| 建议 | 提供给用户的实际建议文字内容 | 
| recommendation\$1id | 建议的唯一标识符。 | 
| 响应 | 处理后为用户生成的最终回复文本。 | 
| session\$1event\$1id | 会话中特定事件的唯一标识符。 | 
| session\$1event\$1ids | 会话事件标识符的列表。 | 
| session\$1id | Connect AI 代理会话的唯一标识符。 | 
| session\$1message\$1id | 会话中自助服务消息的唯一标识符。 | 
| session\$1name | 会话的名称。 | 
| 言语 | 对话中交流的实际消息文本。 | 

### 助理日志示例
<a name="assistant-log-examples"></a>

以下是每种事件类型的不同事件日志的示例。有关每种事件类型的详细说明，请参阅[事件类型定义](#event-type-definitions)部分。

#### CreateSession
<a name="create-session-example"></a>

```
{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173612,
    "event_type": "TRANSCRIPT_CREATE_SESSION",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
    "session_name": "nabbccdd-9999-4b23-aaee-112233445566"
}
```

#### IntentTriggeringReference
<a name="intent-triggering-reference-example"></a>

```
{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173623,
    "event_type": "TRANSCRIPT_INTENT_TRIGGERING_REFERENCE",
    "intent": "To learn about how to autoscale DynamoDB.",
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}
```

#### LargeLanguageModelInvocation
<a name="large-language-model-invocation-example"></a>

查询重构

```
{
    "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "completion": "<query>The customer is asking for information on how to autoscale DynamoDB.</query>",
    "event_timestamp": 1729530173645,
    "event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
    "generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5"
    "model_id": "us.amazon.nova-lite-v1:0",
    "parsed_response": "The customer is asking for information on how to autoscale DynamoDB.",
    "prompt": "{\"anthropic_version\":\"bedrock-2023-05-31\",\"max_tokens\":1024,\"system\":\"You are a...\"}",
    "prompt_type": "BEDROCK_KB_QUERY_REFORMULATION",
    "session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}
```

意图检测

```
{
    "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "completion": "no</malice>\n  - Step 2. <specific>yes</specific>\n  - Step 3. <intent>To learn how to autoscale DynamoDB.</intent>",
    "event_timestamp": 1729530173645,
    "event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
    "generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5"
    "model_id": "us.amazon.nova-lite-v1:0",
    "parsed_response": "To learn how to autoscale DynamoDB.",
    "prompt": "{\"anthropic_version\":\"bedrock-2023-05-31\",\"max_tokens\":1024,\"system\":\"You are a...\"}",
    "prompt_type": "GENERATIVE_INTENT_DETECTION",
    "session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}
```

意图答案生成

```
{
    "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "completion": "{\"citations\":[{\"citation\":{\"generatedResponsePart\":{\"textResponsePart\":{\"span\":{\"end\":1065,\"start\":0},\"text\":\"\\nDynamoDB auto s\"}}}}]}",
    "event_timestamp": 1729530173645,
    "event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
    "generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5",
    "model_id": "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
    "parsed_response": "DynamoDB auto scaling works by creating CloudWatch alarms that monitor your table's activity. When the...",
    "prompt": "{\"input\":{\"text\":\"The customer is seeking information on how to autoscale DynamoDB. Key utterance: \\\"How can \"}}",
    "prompt_type": "BEDROCK_KB_GENERATIVE_ANSWER",
    "session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}
```

手动搜索生成

```
{
    "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "completion": "no</malice>\n  - Step 2. <specific>yes</specific>\n  - Step 3. <intent>To learn how to autoscale DynamoDB.</intent>",
    "event_timestamp": 1729530173645,
    "event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
    "generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5",
    "model_id": "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
    "parsed_response": "DynamoDB auto scaling works by creating CloudWatch alarms that monitor...",
    "prompt": "{\"anthropic_version\":\"bedrock-2023-05-31\",\"max_tokens\":1024,\"system\":\"You are a...\"}",
    "prompt_type": "BEDROCK_KB_GENERATIVE_ANSWER",
    "session_id": "******************-*****************"
}
```

#### QueryAssistant
<a name="query-assistant-example"></a>

```
{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173667,
    "event_type": "TRANSCRIPT_QUERY_ASSISTANT",
    "recommendation_id": "r0001112-3f4e-4fa5-9111-aabbccddeeff",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}
```

#### 建议
<a name="recommendation-example"></a>

```
{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173656,
    "event_type": "TRANSCRIPT_RECOMMENDATION",
    "intent_clicked": 1,
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5",
    "recommendation_id": "r0001112-3f4e-4fa5-9111-aabbccddeeff",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}
```

#### ResultFeedback
<a name="result-feedback-example"></a>

```
{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173667,
    "event_type": "TRANSCRIPT_RESULT_FEEDBACK",
    "generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
    "is_recommendation_useful": 1,
    "recommendation_id": "r0001112-3f4e-4fa5-9111-aabbccddeeff"
}
```

#### SelfServiceMessage
<a name="self-service-message-example"></a>

```
{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "completion": "{\"citations\":[{\"generatedResponsePart\":{\"textResponsePart\":{\"span\":{\"end\":276,\"start\":0},\"text\":\"To autoscale Amazon DynamoDB...\"}}]}",
    "event_timestamp": 1729530173678,
    "event_type": "TRANSCRIPT_SELF_SERVICE_MESSAGE",
    "model_id": "us.amazon.nova-pro-v1:0",
    "parsed_response": "To autoscale Amazon DynamoDB, follow these steps:...",
    "prompt": "{\"input\":{\"text\":\"how to autoscale dynamodb\"},\"retrieveAndGenerateConfiguration\":...}",
    "prompt_type": "SELF_SERVICE_ANSWER_GENERATION",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
    "session_message_id": "mdee1234-5678-4eab-9333-ffeebb998877",
    "utterance": "[Customer] How can I autoscale DyanmoDB?"
}
```

#### TranscriptSessionPolled
<a name="transcript-session-polled-example"></a>

```
{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "connect_user_arn": "arn:aws:connect:us-east-1:204585150770:instance/seaa9988-2233-4f44-8899-abcabcabcabc/agent/agbbccdd-9999-4b23-aaee-112233445566",
    "event_timestamp": 1729530173623,
    "event_type": "TRANSCRIPT_SESSION_POLLED",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
    "session_name": "nabbccdd-9999-4b23-aaee-112233445566"
}
```

#### TriggerDetectionModelInvocation
<a name="trigger-detection-model-invocation-example"></a>

```
{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173634,
    "event_type": "TRANSCRIPT_TRIGGER_DETECTION_MODEL_INVOCATION",
    "is_valid_trigger": 1,
    "issue_probability": "0.87",
    "session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
    "session_event_ids": ["seaa9988-2233-4f44-8899-abcabcabcabc"],
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}
```

#### 表达
<a name="utterance-example"></a>

```
{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173623,
    "event_type": "TRANSCRIPT_UTTERANCE",
    "session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
    "utterance": "[Customer] My laptop won't connect to WiFi after the recent update"
}
```

## 调试助理日志的常见查询示例
<a name="example2-assistant-log"></a>

您可以使用查询与日志进行交互。例如，您可以使用 `SESSION_NAME` 查询会话中的所有活动。

以下是返回特定会话生成的所有日志的两个常用查询。
+  `filter session_name = "SessionName"`
+ `filter session_id = "SessionId"`