翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# CloudWatch Logs を使用して Connect AI エージェントをモニタリングする
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 許可
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 エージェントのログ記録を有効にする
Connect AI エージェントのログ記録を有効にするには、CloudWatch API を使用します。以下の手順を実行します。
1. *アシスタント* ([*ドメイン*](ai-agent-initial-setup.md#ai-agent-requirements)とも呼ばれます) の ARN を取得します。[アシスタントを作成](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 を選択できます。ログの保存先として、保存先オプション 1 つの ARN を指定する必要があります。ログの `outputFormat` は以下のいずれかを選択できます: `json`、`plain`、`w3c`、`raw`、`parquet`。
次の例は、Amazon CloudWatch Logs グループに JSON 形式でログを保存するように設定する方法を示しています。
```
{
"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"
}
}
```
## サポートされているログのタイプ
Connect AI エージェントは、次のログタイプをサポートしています。
+ `EVENT_LOGS`: 通話、チャット、タスク、E メール中の Connect アシスタントのイベントを追跡するログ。
## CloudWatch Logs のクォータを確認する
[Amazon CloudWatch Logs のエンドポイントとクォータ](https://docs.aws.amazon.com/general/latest/gr/cwl_region.html)をチェックして、CloudWatch Logs の配信関連の API コールを行うためのクォータがあるかどうかを確認することをお勧めします。クォータは、API を呼び出したり、リソースを作成したりできる最大回数を設定します。制限を超えると `ServiceQuotaExceededException` エラーが発生します。
## インタラクティブハンドラーを使用した CloudWatch Events の文書化
### イベントタイプの定義
次の表で各イベントタイプについて説明します。イベントタイプごとに異なるフィールドが含まれていることに注意してください。各フィールドの詳細については、「[フィールドの定義](#field-definitions)」セクションを参照してください。
| EventType | 定義 |
| --- | --- |
| TRANSCRIPT\$1CREATE\$1SESSION | 新しい Connect AI エージェントセッションが作成されるとログに記録されます。これは会話の始まりです。 |
| TRANSCRIPT\$1INTENT\$1TRIGGERING\$1REFERENCE | 会話で特定の顧客のインテントが検出されるとログに記録され、自動応答やワークフローがトリガーされる可能性があります。 |
| TRANSCRIPT\$1LARGE\$1LANGUAGE\$1MODEL\$1INVOCATION | レスポンスの生成や会話コンテンツの処理のために大規模言語モデル (LLM) が呼び出されるとログに記録されます。LLM への入力と出力を記録します。 |
| TRANSCRIPT\$1QUERY\$1ASSISTANT | 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 | 会話の参加者がメッセージを送信したときにログに記録され、実際の会話の内容が記録されます。 |
### フィールドの定義
次の表に各フィールドの説明を示します。
| フィールド | 定義 |
| --- | --- |
| ai\$1agent\$1id | Connect AI エージェントリソースの一意の識別子。 |
| assistant\$1id | Connect Assistant リソースの一意の識別子。 |
| completion | LLM によって返されるか、メッセージ用に生成された未加工の完了テキスト。 |
| connect\$1user\$1arn | セッションにアクセスする Connect ユーザーの Amazon リソースネーム (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 | 言語モデルレスポンスの処理/解析バージョン。多くの場合、構造化形式です。 |
| prompt | LLM の呼び出しに使用される入力プロンプト。 |
| prompt\$1type | メッセージまたはクエリの処理に使用される AI プロンプトのタイプ。 |
| recommendation | ユーザーに提供される実際のレコメンデーションテキストコンテンツ |
| recommendation\$1id | レコメンデーションの一意の識別子。 |
| response | 処理後にユーザーに対して生成された最終レスポンステキスト。 |
| session\$1event\$1id | セッション内の特定のイベントの一意の識別子。 |
| session\$1event\$1ids | セッションイベント識別子のリスト。 |
| session\$1id | Connect AI エージェントセッションの一意の識別子。 |
| session\$1message\$1id | セッション内のセルフサービスメッセージの一意の識別子。 |
| session\$1name | セッションの名前。 |
| utterance | 会話で交換された実際のメッセージテキスト。 |
### アシスタントログの例
以下は、イベントタイプごとに異なるイベントログの例です。各イベントタイプの詳細な説明については、「[イベントタイプの定義](#event-type-definitions)」セクションを参照してください。
#### CreateSession
```
{
"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
```
{
"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
クエリの再構築
```
{
"ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
"assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
"completion": "The customer is asking for information on how to autoscale DynamoDB.",
"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\n - Step 2. yes\n - Step 3. To learn how to autoscale DynamoDB.",
"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\n - Step 2. yes\n - Step 3. To learn how to autoscale DynamoDB.",
"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
```
{
"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"
}
```
#### 推奨事項
```
{
"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
```
{
"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
```
{
"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
```
{
"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
```
{
"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"
}
```
#### Utterance
```
{
"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"
}
```
## アシスタントログをデバッグするための一般的なクエリの例
クエリを使用してログを操作できます。例えば、`SESSION_NAME` を使用して、セッション内のすべてのイベントをクエリすることができます。
以下は、特定のセッション用に生成されたすべてのログを返すための 2 つの一般的なクエリです。
+ `filter session_name = "SessionName"`
+ `filter session_id = "SessionId"`