Überwachen Sie Amazon Q in Connect mithilfe von CloudWatch Protokollen - Amazon Connect
Erforderliche IAM-BerechtigungenEnable logging (Protokollierung aktivieren)Unterstützte ProtokolltypenSuchen Sie nach CloudWatch ProtokollkontingentenDokumentieren von CloudWatch Ereignissen mithilfe von Interactive HandlerBeispiele für häufig vorkommende Abfragen von Protokollen des Debug-Assistenten

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Überwachen Sie Amazon Q in Connect mithilfe von CloudWatch Protokollen

Um Einblick in die Empfehlungen zu erhalten, die Amazon Q in Connect Ihren Agenten in Echtzeit gibt, und darüber, welche Kundenabsichten es durch natürliches Sprachverständnis erkennt, können Sie CloudWatch Logs abfragen. CloudWatch Mithilfe von Protokollen erhalten Sie einen Überblick über den gesamten Kontaktverlauf: Konversation, Auslöser, Absichten und Empfehlungen. Sie können diese Informationen auch zum Debuggen verwenden oder sie Ihnen zur Verfügung stellen, Support wenn Sie sich an sie wenden, um Hilfe zu erhalten.

In diesem Thema wird erläutert, wie Sie die Protokollierung für Amazon Q in Connect aktivieren.

Erforderliche IAM-Berechtigungen

Bevor Sie die Protokollierung für einen Amazon Q in Connect-Assistenten aktivieren, überprüfen Sie, ob Sie über die folgenden AWS Identity and Access Management Berechtigungen verfügen. Sie sind für das Benutzerkonto erforderlich, das an der Amazon-Connect-Konsole angemeldet ist:

  • wisdom:AllowVendedLogDeliveryForResource: Erforderlich, um die Bereitstellung von Protokollen für die Assistentenressource zu erlauben.

Ein Beispiel für eine IAM-Rolle mit allen erforderlichen Berechtigungen für Ihr spezielles Protokollierungsziel finden Sie unter Protokollierung, für die zusätzliche Berechtigungen erforderlich sind [V2]. Dieses Thema enthält Beispiele für verschiedene Protokollierungsziele, z. B. an Logs gesendete CloudWatch Logs und Logs, die an Amazon S3 gesendet werden. Die Beispiele zeigen, wie Sie Aktualisierungen Ihrer spezifischen Logging-Zielressource zulassen können.

Aktivieren der Protokollierung in Amazon Q in Connect

Um die Protokollierung für Amazon Q in Connect zu aktivieren, verwenden Sie die CloudWatch API. Führen Sie folgende Schritte aus:

  1. Rufen Sie den ARN des Amazon-Q in-Connect-Assistenten ab (auch als Domain bezeichnet). Nachdem Sie einen Assistenten erstellt haben, können Sie seinen ARN von der Amazon Connect Connect-Konsole oder durch Aufrufen der GetAssistantAPI abrufen. Der ARN folgt diesem Format:

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

  2. Anruf PutDeliverySource: Verwenden Sie diese CloudWatch API, um eine Lieferquelle für den Assistenten zu erstellen. Übergeben Sie den ARN des Assistenten als resourceArn. Geben Sie als logType den Wert EVENT_LOGS an, um Protokolle vom Assistenten zu erfassen.

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

  3. Aufruf PutDeliveryDestination: Verwenden Sie diese CloudWatch API, um zu konfigurieren, wo die Protokolle gespeichert werden sollen. Sie können CloudWatch Logs, Amazon S3 oder Amazon Data Firehose als Ziel für das Speichern von Protokollen wählen. Sie müssen den ARN einer der Zieloptionen angeben, wo Ihre Protokolle gespeichert werden sollen. Sie können das outputFormat der Protokolle aus folgenden Optionen auswählen: json, plain, w3c, raw, parquet.

    Das folgende Beispiel zeigt, wie Logs so konfiguriert werden, dass sie in einer Amazon CloudWatch Logs-Gruppe und im JSON-Format gespeichert werden.

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

  4. Aufruf CreateDelivery: Verwenden Sie diese CloudWatch API, um die Lieferquelle mit dem Lieferziel zu verknüpfen, das Sie in den vorherigen Schritten erstellt haben. Diese API-Operation verknüpft die Bereitstellungsquelle mit dem Endziel.

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

Unterstützte Protokolltypen

Amazon Q in Connect unterstützt den folgenden Protokolltyp:

  • EVENT_LOGS: Protokolle, die das Ereignis eines Amazon-Q-in-Connect-Assistenten bei Anrufen, Chats und E-Mails verfolgen.

Suchen Sie nach CloudWatch Log-Kontingenten

Wir empfehlen, die Endpunkte und Kontingente von Amazon CloudWatch Logs zu überprüfen, um festzustellen, ob es Kontingente für API-Aufrufe im Zusammenhang mit der CloudWatch Logs-Lieferung gibt. Über Kontingente wird festgelegt, wie oft Sie eine API aufrufen oder eine Ressource erstellen können. Eine Überschreitung dieser Grenze führt zu einem ServiceQuotaExceededException-Fehler.

Dokumentieren von CloudWatch Ereignissen mithilfe von Interactive Handler

Ereignistypdefinitionen

In der folgenden Tabelle werden die einzelnen Ereignistypen beschrieben. Beachten Sie, dass verschiedene Ereignistypen unterschiedliche Felder enthalten. Ausführliche Informationen zu den einzelnen Feldern finden Sie im Abschnitt Felddefinitionen.

EventType Definition
TRANSCRIPT_CREATE_SESSION Wird protokolliert, wenn eine neue Amazon-Q-in-Connect-Sitzung erstellt wird. Dies markiert den Beginn einer Konversation.
TRANSCRIPT_INTENT_TRIGGERING_REFERENCE Wird protokolliert, wenn in der Konversation eine bestimmte Kundenabsicht erkannt wird, was zu automatisierten Antworten oder Workflows führen kann.
TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION Wird protokolliert, wenn ein großes Sprachmodell (Large Language Model, LLM) aufgerufen wird, um Antworten zu generieren oder Konversationsinhalte zu verarbeiten. Zeichnet die Eingaben und Ausgaben des LLM auf.
TRANSCRIPT_QUERY_ASSISTANT Wird protokolliert, wenn in Amazon Q in Connect eine manuelle Suche durchgeführt oder eine direkte Anfrage gestellt wird
TRANSCRIPT_RECOMMENDATION Wird protokolliert, wenn das System einem Kundendienstmitarbeiter oder Kunden eine Empfehlung gibt, die Wissensartikel, generierte Antworten oder Aktionsvorschläge beinhalten kann.
TRANSCRIPT_RESULT_FEEDBACK Wird protokolliert, wenn Feedback zur Nützlichkeit oder Relevanz eines Such- oder Abfrageergebnisses gegeben wird.
TRANSCRIPT_SELF_SERVICE_MESSAGE Wird protokolliert, wenn ein Kunde mit Self-Service-Komponenten von Amazon Q in Connect interagiert
TRANSCRIPT_SESSION_POLLED Wird protokolliert, wenn das System erkennt, dass ein Agent mit einer Sitzung verbunden ist (Eine Sitzung wird abgefragt, wenn ein GetRecommendations API-Aufruf getätigt wurde)
TRANSCRIPT_TRIGGER_DETECTION_MODEL_INVOCATION Wird protokolliert, wenn das Triggererkennungsmodell aufgerufen wird, um festzustellen, ob eine Konversation Absichten aufweist
TRANSCRIPT_UTTERANCE Wird protokolliert, wenn eine Nachricht von einem beliebigen Teilnehmer der Konversation gesendet wird, wobei der tatsächliche Inhalt der Konversation aufgezeichnet wird.

Felddefinitionen

In der Tabelle unten ist jedes Element beschrieben.

Feld Definition
ai_agent_id Eindeutige Kennung für die KI-Agent-Ressource von Amazon Q in Connect.
assistant_id Eindeutige Kennung für die KI-Assistentenressource von Amazon Q in Connect.
completion Der Abschlusstext im Rohformat, der vom LLM zurückgegeben oder für die Nachricht generiert wurde.
connect_user_arn Amazon-Ressourcenname (ARN) des Connect-Benutzers, der auf die Sitzung zugreift.
event_timestamp Unix-Zeitstempel (in Millisekunden), der angibt, wann das Ereignis aufgetreten ist.
event_type Art des Ereignisses, das angibt, welche Aktion oder welcher Prozess im System stattgefunden hat.
generation_id Eindeutige Kennung für eine bestimmte KI-generierte Antwort.
intent Der Text oder die Beschreibung der Absicht.
intent_clicked Boolescher Wert, der angibt, ob die Empfehlung durch eine angeklickte Absicht ausgelöst wurde.
intent_id Eine eindeutige ID für die erkannte Absicht.
issue_probability Numerische Wahrscheinlichkeit (0,0–1,0), dass in der Konversation ein Problem erkannt wurde (bei einer Wahrscheinlichkeit über 0,5 wird eine Absichtsgenerierung ausgelöst)
is_recommendation_useful Boolescher Wert, der angibt, ob der Benutzer das Ergebnis hilfreich fand.
is_valid_trigger Boolescher Wert, der angibt, ob die Analyse des Erkennungsmodells zu einem gültigen Trigger geführt hat.
model_id ID des KI-Modells, das zum Aufrufen des LLM verwendet wurde.
parsed_response Die processed/parsed Version der Sprachmodellantwort, oft in strukturiertem Format.
prompt Der Prompt, der zum Aufrufen des LLM verwendet wurde.
prompt_type Art des Amazon-Q-in-Connect-Prompts, der für die Verarbeitung der Nachricht oder Anfrage verwendet wird.
recommendation Der tatsächliche Inhalt des Empfehlungstextes, der dem Benutzer bereitgestellt wurde
recommendation_id Eindeutige ID für die Empfehlung.
response Der endgültige Antworttext, der nach der Verarbeitung für den Benutzer generiert wurde.
session_event_id Eindeutige ID für ein bestimmtes Ereignis innerhalb der Sitzung.
session_event_ids Liste der Sitzungsereignis-IDs.
session_id Eindeutige ID für die KI-Assistentenressource von Amazon Q in Connect.
session_message_id Eindeutige ID für eine Self-Service-Nachricht innerhalb einer Sitzung.
session_name Name der Sitzung.
utterance Der tatsächliche Nachrichtentext, der in der Konversation ausgetauscht wurde.

Beispiele für Assistentenprotokolle

Im Folgenden finden Sie Beispiele für unterschiedliche Ereignisprotokolle für jeden Ereignistyp. Im Abschnitt Ereignistypdefinitionen finden Sie ausführliche Erläuterungen zu den einzelnen Ereignistypen.

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

Neuformulierung der Abfrage


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

Erkennung von Absichten


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

Generierung einer Antwort auf eine Absicht


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

Generierung einer manuellen Suche


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

Empfehlung


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

Beispiele für häufig vorkommende Abfragen von Protokollen des Debug-Assistenten

Sie können mithilfe von Abfragen mit Protokollen interagieren. Sie können beispielsweise alle Ereignisse innerhalb einer Sitzung abfragen, indem Sie SESSION_NAME verwenden.

Im Folgenden finden Sie zwei häufig verwendete Abfragen, um alle für eine bestimmte Sitzung generierten Protokolle zurückzugeben.

  • filter session_name = "SessionName"

  • filter session_id = "SessionId"