Ü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 zu 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 erklärt, wie die Protokollierung für Amazon Q in Connect aktiviert wird.

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 Connect-Konsole angemeldet ist:

  • wisdom:AllowVendedLogDeliveryForResource: Erforderlich, um die Übermittlung von Protokollen für die Assistentenressource zu ermöglichen.

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.

Protokollierung für Amazon Q in Connect aktivieren

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 Ihres 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 alsresourceArn. Geben Sie für EVENT_LOGS anlogType, dass Protokolle von Ihrem Assistenten gesammelt werden sollen.

    {
    "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 outputFormat eines der folgenden Protokolle wählen:json,,plain, w3craw,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. Dieser API-Vorgang verknüpft die Lieferquelle 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 im Connect-Assistenten bei Anrufen, Chats und E-Mails verfolgen.

Suchen Sie nach CloudWatch Protokollkontingenten

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. Kontingente legen fest, wie oft Sie eine API aufrufen oder eine Ressource erstellen können. Eine Überschreitung des Limits führt zu einem ServiceQuotaExceededException Fehler.

Dokumentieren von CloudWatch Ereignissen mithilfe von Interactive Handler

Definitionen von Ereignistypen

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 Felddefinitionen Abschnitt.

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 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 eine manuelle Suche oder direkte Anfrage an Amazon Q in Connect gestellt wird
TRANSCRIPT_RECOMMENDATION Wird protokolliert, wenn das System einem Agenten 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 feststellt, dass ein Agent mit einer Sitzung verbunden ist (Eine Sitzung wird abgefragt, wenn ein API-Aufruf getätigt wurde) GetRecommendations
TRANSCRIPT_TRIGGER_DETECTION_MODEL_INVOCATION Wird protokolliert, wenn das Triggererkennungsmodell aufgerufen wird, um festzustellen, ob eine Konversation Absichten hat
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 folgenden Tabelle werden die einzelnen Felder beschrieben.

Feld Definition
ai_agent_id Eindeutige Kennung für die Agentenressource Amazon Q in Connect AI.
assistant_id Eindeutige Kennung für die Assistentenressource Amazon Q in Connect.
Fertigstellung Der rohe Abschlusstext, 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), als das Ereignis eingetreten 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.
Absicht Der Text oder die Beschreibung der Absicht.
intenent_clicked Boolescher Wert, der angibt, ob die Empfehlung durch eine angeklickte Absicht ausgelöst wurde.
intent_id Eindeutiger Bezeichner für die erkannte Absicht.
issue_probability Numerische Wahrscheinlichkeit (0,0—1,0), dass in der Konversation ein Problem erkannt wurde (bei einer Wahrscheinlichkeit von mehr als 0,5 wird eine Absichtsgenerierung ausgelöst)
ist_recommendation_nützlich 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 Bezeichner des KI-Modells, das zum Aufrufen des LLM verwendet wurde.
parsed_response Die processed/parsed Version der Sprachmodellantwort, oft in strukturiertem Format.
zu etwas bringen Die Eingabeaufforderung, die zum Aufrufen des LLM verwendet wurde.
prompt_type Art der Amazon Q in Connect-Aufforderung, die für die Verarbeitung der Nachricht oder Anfrage verwendet wird.
Empfehlung Der tatsächliche Inhalt des Empfehlungstextes, der dem Benutzer zur Verfügung gestellt wird
recommendation_id Eindeutiger Bezeichner für die Empfehlung.
response Der endgültige Antworttext, der nach der Verarbeitung für den Benutzer generiert wurde.
session_event_id Eindeutiger Bezeichner für ein bestimmtes Ereignis innerhalb der Sitzung.
session_event_ids Liste der Identifikatoren von Sitzungsereignissen.
session_id Eindeutige Kennung für die Amazon Q in Connect-Sitzung.
session_message_id Eindeutiger Bezeichner für eine Self-Service-Nachricht innerhalb einer Sitzung.
Sitzungsname Name der Sitzung.
Äußerung Der eigentliche 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 Definitionen von Ereignistypen Abschnitt 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 von Absichten und Antworten


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

Manuelle Generierung von Suchanfragen


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

Im Folgenden finden Sie zwei häufig verwendete Abfragen, mit denen alle für eine bestimmte Sitzung generierten Protokolle zurückgegeben werden.

  • filter session_name = "SessionName"

  • filter session_id = "SessionId"