CloudWatch Logs を使用して Amazon Q in Connect をモニタリングする - Amazon Connect
必要な IAM 許可 ログ記録の有効化サポートされているログのタイプCloudWatch Logs のクォータを確認するインタラクティブハンドラーを使用した CloudWatch Events のドキュメント化アシスタントログをデバッグするための一般的なクエリの例

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

CloudWatch Logs を使用して Amazon Q in Connect をモニタリングする

Amazon Q in Connect がエージェントに提供するリアルタイムの推奨事項と、自然言語を理解して検出する顧客の意図を可視化するには、CloudWatch Logs をクエリできます。CloudWatch Logs を使用すると、会話、トリガー、インテント、推奨事項など、コンタクトジャーニー全体を確認できます。また、この情報をデバッグに使用することも、サポートを依頼 サポート するときに に提供することもできます。

このトピックでは、Amazon Q in Connect のロギングを有効にする方法について説明します。

必要な IAM 許可

Amazon Q in Connect アシスタントのログ記録を有効にする前に、次の AWS Identity and Access Management アクセス許可があることを確認してください。Amazon Connect コンソールにサインインしているユーザーアカウントに必要です。

  • wisdom:AllowVendedLogDeliveryForResource: アシスタントリソースのログの提供を許可するために必要です。

特定のロギング先に必要なすべてのアクセス許可を持つ IAM ロールの例を表示するには、「追加のアクセス許可が必要なロギング [V2]」を参照してください。そのトピックには、CloudWatch Logs に送信されたログや Amazon S3 に送信されたログなど、さまざまなロギング先の例が含まれています。この例は、特定のロギング先リソースの更新を許可する方法を示しています。

Amazon Q in Connect のロギングを有効にする

Amazon Q in Connect のロギングを有効化するには、CloudWatch API を使用します。以下の手順を実行します。

  1. Amazon Q in Connect アシスタント (ドメイン とも呼ばれます) の ARN を取得します。アシスタントを作成したら、Amazon Connect コンソールから、または GetAssistant API を呼び出すことで、その ARN を取得できます。ARN はこの形式に従います。

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

  2. PutDeliverySource を呼び出す: この 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
}

  3. PutDeliveryDestination を呼び出す: この 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"
    }
}

  4. CreateDelivery を呼び出す: この CloudWatch API を使用して、配信ソースを前のステップで作成した配信先にリンクします。この API オペレーションは、配信ソースを最終配信先と関連付けます。

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

サポートされているログのタイプ

Amazon Q in Connect は、以下のログのタイプをサポートしています。

  • EVENT_LOGS: 通話とチャット中に Amazon Q in Connect アシスタントのイベントを追跡するログ。

CloudWatch Logs のクォータを確認する

Amazon CloudWatch Logs のエンドポイントとクォータをチェックして、CloudWatch Logs の配信関連の API コールを行うためのクォータがあるかどうかを確認することをお勧めします。クォータは、API を呼び出したり、リソースを作成したりできる最大回数を設定します。制限を超えると ServiceQuotaExceededException エラーが発生します。

インタラクティブハンドラーを使用した CloudWatch Events のドキュメント化

イベントタイプの定義

次の表に、各イベントタイプを示します。イベントタイプごとに異なるフィールドが含まれていることに注意してください。各フィールドの詳細については、フィールド定義「」セクションを参照してください。

EventType 定義
TRANSCRIPT_CREATE_SESSION 新しい Amazon Q in Connect セッションが作成されるとログに記録されます。これは会話の始まりです。
TRANSCRIPT_INTENT_TRIGGERING_REFERENCE 会話で特定の顧客のインテントが検出されるとログに記録され、自動応答やワークフローがトリガーされる可能性があります。
TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION レスポンスの生成や会話コンテンツの処理のために大規模言語モデル (LLM) が呼び出されるとログに記録されます。LLM への入力と LLM からの出力を記録します。
トランスクリプトクエリアシスタント Amazon Q in Connect に手動検索または直接クエリが行われたときにログに記録されます
TRANSCRIPT_RECOMMENDATION システムがエージェントまたは顧客にレコメンデーションを提供するときにログに記録されます。これには、ナレッジ記事、生成されたレスポンス、または推奨されるアクションが含まれる場合があります。
トランスクリプト結果フィードバック 検索またはクエリ結果の有用性または関連性に関するフィードバックが提供されたときにログに記録されます。
トランスクリプト_SELF_SERVICE_MESSAGE 顧客が Amazon Q in Connect のセルフサービスコンポーネントとやり取りしたときにログに記録されます
TRANSCRIPT_SESSION_POLLED エージェントがセッションに接続されていることをシステムが検出したときにログに記録されます (GetRecommendations API コールが行われたときにセッションがポーリングされます）
TRANSCRIPT_TRIGGER_DETECTION_MODEL_INVOCATION 会話にインテントがあるかどうかを判断するためにトリガー検出モデルが呼び出されたときにログに記録されます。
TRANSCRIPT_UTTERANCE 会話の参加者がメッセージを送信したときにログに記録され、実際の会話の内容が記録されます。

フィールド定義

次の表に、各フィールドを示します。

フィールド 定義
ai_agent_id Amazon Q in Connect AI エージェントリソースの一意の識別子。
Assistant_id Amazon Q in Connect アシスタントリソースの一意の識別子。
完了 LLM によって返されるか、メッセージ用に生成された未加工の完了テキスト。
connect_user_arn セッションにアクセスする Connect ユーザーの Amazon リソースネーム (ARN)。
event_timestamp イベントが発生したときの Unix タイムスタンプ (ミリ秒単位）。
event_type システムで発生したアクションまたはプロセスを示すイベントのタイプ。
generation_id 特定の AI 生成レスポンスの一意の識別子。
intent インテントのテキストまたは説明。
intent_clicked レコメンデーションがクリックされたインテントによってトリガーされたかどうかを示すブール値。
intent_id 検出されたインテントの一意の識別子。
issue_probability 会話で問題が検出された数値確率 (0.0～1.0) (0.5 を超える確率はインテント生成を呼び出します）
is_recommendation_useful ユーザーが結果を役に立ったかどうかを示すブール値。
is_valid_trigger 検出モデル分析が有効なトリガーになったかどうかを示すブール値。
model_id LLM の呼び出しに使用される AI モデルの識別子。
parsed_response 言語モデルレスポンスの処理/解析バージョン。多くの場合、構造化形式です。
プロンプト LLM の呼び出しに使用される入力プロンプト。
prompt_type メッセージまたはクエリの処理に使用される Amazon Q in Connect プロンプトのタイプ。
レコメンデーション ユーザーに提供される実際のレコメンデーションテキストコンテンツ
Recommendation_id レコメンデーションの一意の識別子。
レスポンス 処理後にユーザーに対して生成された最終レスポンステキスト。
session_event_id セッション内の特定のイベントの一意の識別子。
session_event_ids セッションイベント識別子のリスト。
session_id Amazon Q in Connect セッションの一意の識別子。
session_message_id セッション内のセルフサービスメッセージの一意の識別子。
session_name セッションの名前。
発話 会話で交換された実際のメッセージテキスト。

アシスタントログの例

以下は、イベントタイプごとに異なるイベントログの例です。各イベントタイプの詳細な説明については、イベントタイプの定義「」セクションを参照してください。

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": "<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


{
    "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"