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

# 使用 CloudWatch Logs 監控 Connect AI 代理器
<a name="monitor-ai-agents"></a>

若要了解 Connect AI 代理器提供給客服人員的即時建議，以及他們透過自然語言理解而偵測到的客戶意圖，您可以查詢 CloudWatch Logs。您可以透過 CloudWatch Logs 了解整個聯絡過程：對話、觸發點、意圖、建議。您也可以使用此資訊進行偵錯，或在聯絡他們尋求協助 支援 時將其提供給 。

本主題說明如何啟用 Connect AI 代理器的記錄。

**Topics**
+ [所需的 IAM 許可](#permissions-cw-q)
+ [啟用日誌記錄](#enable-assistant-logging)
+ [支援的日誌類型](#supported-log-types-q)
+ [檢查 CloudWatch Logs 配額](#cwl-quotas)
+ [使用互動式處理常式記錄 CloudWatch Events](#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 Logs 的日誌和傳送至 Amazon S3 的日誌。範例顯示如何允許更新特定日誌記錄目的地資源。

## 啟用 Connect AI 代理器的記錄
<a name="enable-assistant-logging"></a>

若要啟用 Connect AI 代理器的記錄，您可以使用 CloudWatch API。完成下列步驟。

1. 取得*助理*的 ARN （也稱為其[*網域*](ai-agent-initial-setup.md#ai-agent-requirements))。[建立助理](ai-agent-initial-setup.md#enable-ai-agents-step1)之後，您可以從 Amazon Connect 主控台或呼叫 [GetAssistant](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_GetAssistant.html) API 取得其 ARN。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 Logs、Amazon S3 或 Amazon Data Firehose 作為儲存日誌的目的地。您必須為其中一個日誌存放地點選項指定 ARN。您可以選擇日誌的 `outputFormat` 作為下列其中一項：`json`、`plain`、`w3c`、`raw`、`parquet`。

   下列範例顯示如何設定日誌以 JSON 格式儲存在 Amazon CloudWatch Logs 群組。

   ```
   {
       "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 Logs 配額
<a name="cwl-quotas"></a>

建議您檢查 [Amazon CloudWatch Logs 端點和配額](https://docs.aws.amazon.com/general/latest/gr/cwl_region.html)，查看是否有任何配額可用於進行 CloudWatch Logs 交付相關 API 呼叫。配額會設定您可以呼叫 API 或建立資源的次數上限。超過此限制會導致 `ServiceQuotaExceededException` 錯誤。

## 使用互動式處理常式記錄 CloudWatch Events
<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 的輸入和輸出內容。 | 
| TRANSCRIPT\$1QUERY\$1ASSISTANT | 調用下列其中一個 Connect AI 代理器時記錄： AnswerRecommendation、CaseSummarization、EmailGenerativeAnswer、EmailOverview、EmailResponse、ManualSearch、NoteTaking。 | 
| TRANSCRIPT\$1RECOMMENDATION | 系統向客服人員或客戶提供建議時進行記錄，其中可能包括知識庫文章、產生的回應或建議動作。 | 
| TRANSCRIPT\$1RESULT\$1FEEDBACK | 提供搜尋或查詢結果實用性或相關性的相關意見回饋時進行記錄。 | 
| TRANSCRIPT\$1SELF\$1SERVICE\$1MESSAGE | 當客戶與 SelfService Connect AI 代理器互動時記錄 | 
| 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 Resource Name (ARN)。 | 
| event\$1timestamp | 事件發生時的 Unix 時間戳記 (以毫秒為單位)。 | 
| event\$1type | 事件類型，顯示系統中發生的動作或程序。 | 
| generation\$1id | 特定 AI 產生的回應的唯一識別碼。 | 
| intent | 意圖文字或說明。 | 
| intent\$1clicked | 布林值，其指出建議是否由所點選意圖觸發。 | 
| intent\$1id | 所偵測意圖的唯一識別碼。 | 
| issue\$1probability | 在對話中偵測到問題的數值機率 (0.0–1.0) (機率大於 0.5 將調用意圖產生) | 
| is\$1recommendation\$1useful | 布林值，其指出使用者是否認為結果有幫助。 | 
| is\$1valid\$1trigger | 布林值，其指出偵測模型分析是否產生有效的觸發。 | 
| model\$1id | 用於調用 LLM 的 AI 模型識別碼。 | 
| parsed\$1response | 語言模型回應的處理/剖析版本，通常採用結構化格式。 | 
| 提示 | 用於調用 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"`