Monitora gli agenti Connect AI utilizzando CloudWatch Logs - Amazon Connect
Autorizzazioni IAM richiesteEnable logging (Attiva registrazione)Tipi di log supportatiControlla le quote di CloudWatch LogsCloudWatch Documentazione degli eventi utilizzando Interactive HandlerEsempi di query comuni per il debug dei log dell’assistente

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Monitora gli agenti Connect AI utilizzando CloudWatch Logs

Per ottenere visibilità sui consigli in tempo reale che gli agenti Connect AI forniscono ai tuoi agenti e sulle intenzioni dei clienti che rilevano attraverso la comprensione del linguaggio naturale, puoi interrogare CloudWatch Logs. CloudWatch I log ti danno visibilità sull'intero percorso di contatto: conversazione, fattori scatenanti, intenti, consigli. Puoi anche utilizzare queste informazioni per eseguire il debug o fornirle Supporto quando li contatti per ricevere assistenza.

Questo argomento spiega come abilitare la registrazione per gli agenti Connect AI.

Autorizzazioni IAM richieste

Prima di abilitare la registrazione per un assistente Connect, verifica di disporre delle seguenti AWS Identity and Access Management autorizzazioni. Sono necessari per l’account utente che ha effettuato l’accesso alla console Amazon Connect:

  • wisdom:AllowVendedLogDeliveryForResource: necessario per consentire la consegna dei log per la risorsa assistente.

Per visualizzare un esempio di ruolo IAM con tutte le autorizzazioni richieste per la destinazione della registrazione di log specifica, consulta Registrazione che richiede autorizzazioni aggiuntive [V2]. Questo argomento contiene esempi per diverse destinazioni di registrazione, come i log inviati a CloudWatch Logs e i log inviati ad Amazon S3. Gli esempi mostrano come consentire gli aggiornamenti alla risorsa di destinazione di registrazione specifica.

Abilita la registrazione per gli agenti Connect AI

Per abilitare la registrazione per gli agenti Connect AI, utilizzi l' CloudWatch API. Completa questa procedura:

  1. Ottieni l'ARN del tuo assistente (noto anche come dominio). Dopo aver creato un assistente, puoi ottenerne l'ARN dalla console Amazon Connect o chiamando l'GetAssistantAPI. L’ARN segue questo formato:

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

  2. Chiamata PutDeliverySource: utilizza questa CloudWatch API per creare una fonte di consegna per l'assistente. Passa l’ARN dell’assistente come resourceArn. Per logType, specifica EVENT_LOGS in modo che raccolga i log presso l’assistente.

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

  3. Chiamata PutDeliveryDestination: utilizza questa CloudWatch API per configurare dove archiviare i log. Puoi scegliere CloudWatch Logs, Amazon S3 o Amazon Data Firehose come destinazione per l'archiviazione dei log. È necessario specificare l’ARN di una delle opzioni di destinazione in cui archiviare i log. È possibile scegliere tra i outputFormat dei log uno dei seguenti: json, plain, w3c, raw, parquet.

    L'esempio seguente mostra come configurare i log da archiviare in un Amazon CloudWatch Logs Group e in formato 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. Chiamata CreateDelivery: utilizza questa CloudWatch API per collegare l'origine di consegna alla destinazione di consegna creata nei passaggi precedenti. Questa operazione API associa l’origine di consegna alla destinazione finale.

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

Tipi di log supportati

Gli agenti Connect AI supportano il seguente tipo di registro:

  • EVENT_LOGS: registri che tengono traccia degli eventi di un assistente Connect durante chiamate, chat, attività ed e-mail.

Controlla le quote dei log CloudWatch

Ti consigliamo di controllare CloudWatch gli endpoint e le quote di Amazon Logs per vedere se esistono quote per effettuare chiamate API relative alla consegna di CloudWatch Logs. Le quote impostano il numero massimo volte in cui è possibile chiamare un’API o creare una risorsa. Il superamento di questo limite comporta la generazione di un errore ServiceQuotaExceededException.

CloudWatch Documentazione degli eventi utilizzando Interactive Handler

Definizioni del tipo di eventi

Nella tabella seguente è descritto ciascun tipo di evento. Tieni presente che diversi tipi di eventi contengono campi diversi. Consulta la sezione Definizione di campo per informazioni dettagliate su ciascun campo.

EventType Definizione
TRANSCRIPT_CREATE_SESSION Registrato quando viene creata una nuova sessione Connect AI Agents. Questo segna l’inizio di una conversazione.
TRANSCRIPT_INTENT_TRIGGERING_REFERENCE Registrato quando nella conversazione viene rilevata l’intenzione specifica del cliente, eventualmente attivando risposte o flussi di lavoro automatici.
TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION Registrato quando viene invocato un modello linguistico di grandi dimensioni (LLM) per generare risposte o elaborare il contenuto della conversazione. Registra gli input e gli output dell’LLM.
TRANSCRIPT_QUERY_ASSISTANT Registrato quando viene richiamato uno dei seguenti agenti Connect AI: AnswerRecommendation,,, CaseSummarization, EmailGenerativeAnswer, EmailOverview EmailResponse, ManualSearch. NoteTaking
TRANSCRIPT_RECOMMENDATION Registrato quando il sistema fornisce una raccomandazione a un agente o cliente, che può includere articoli informativi, risposte generate o azioni suggerite.
TRANSCRIPT_RESULT_FEEDBACK Registrato quando viene fornito un feedback sull’utilità o la pertinenza dei risultati di una ricerca o di una query.
TRANSCRIPT_SELF_SERVICE_MESSAGE Registrato quando un cliente interagisce con un agente SelfService Connect AI
TRANSCRIPT_SESSION_POLLED Registrato quando il sistema rileva che un agente è connesso a una sessione (una sessione viene interrogata quando è stata effettuata una chiamata GetRecommendations API)
TRANSCRIPT_TRIGGER_DETECTION_MODEL_INVOCATION Registrato quando il modello di rilevamento del trigger viene invocato per determinare se una conversazione presenta degli intenti
TRANSCRIPT_UTTERANCE Registrato quando un messaggio viene inviato da un partecipante alla conversazione, registrando il contenuto effettivo della conversazione.

Definizione di campo

La seguente tabella descrive ciascun campo.

Campo Definizione
ai_agent_id Identificatore univoco per la risorsa agente Connect AI.
assistant_id Identificatore univoco per la risorsa dell'assistente Connect.
completion Il testo di completamento non elaborato restituito dall’LLM o generato per il messaggio.
connect_user_arn Nome della risorsa Amazon (ARN) dell’utente Connect che accede alla sessione.
event_timestamp Timestamp Unix (in millisecondi) in cui si è verificato l’evento.
event_type Tipo dell’evento, indicante l’azione o il processo che si è verificato nel sistema.
generation_id Identificatore univoco per una risposta specifica generata dall’IA.
intent Il testo o la descrizione dell’intento.
intent_clicked Valore booleano che indica se la raccomandazione è stata attivata da un intento cliccato.
intent_id Identificatore univoco per l’intento rilevato.
issue_probability Probabilità numerica (da 0,0 a 1,0) che sia stato rilevato un problema nella conversazione (una probabilità maggiore di 0,5 invocherà la generazione dell’intento)
is_recommendation_useful Valore booleano che indica se l’utente ha trovato utile il risultato.
is_valid_trigger Valore booleano che indica se l’analisi del modello di rilevamento ha prodotto un trigger valido.
model_id Identificatore del modello IA utilizzato per invocare l’LLM.
parsed_response La processed/parsed versione del modello linguistico Response, spesso in formato strutturato.
prompt Il prompt di input utilizzato per invocare l’LLM.
prompt_type Tipo di prompt AI utilizzato per elaborare il messaggio o la query.
raccomandazione Il contenuto effettivo del testo della raccomandazione fornito all’utente
recommendation_id Identificatore univoco per la raccomandazione.
risposta Il testo di risposta finale generato per l’utente dopo l’elaborazione.
session_event_id Identificatore univoco per un evento specifico all’interno della sessione.
session_event_ids Elenco di identificatori di eventi di sessione.
session_id Identificatore univoco per la sessione Connect AI agent.
session_message_id Identificatore univoco per un messaggio self-service all’interno di una sessione.
session_name Nome dell’opzione.
utterance Il testo effettivo del messaggio scambiato durante la conversazione.

Esempi di log di assistenti

Di seguito sono riportati alcuni esempi di log eventi diversi per ogni tipo di evento. Fare riferimento alla sezione Definizioni del tipo di eventi per spiegazioni dettagliate su ciascun tipo di evento.

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

Riformulazione della query


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

Rilevamento dell’intento


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

Generazione di intenti di risposta


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

Generazione di ricerca manuale


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

Raccomandazione


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

Esempi di query comuni per il debug dei log dell’assistente

È possibile interagire con i log utilizzando le query. Ad esempio, è possibile eseguire una query per tutti gli eventi all’interno di una sessione utilizzando SESSION_NAME.

Di seguito sono riportate due query comuni per restituire tutti i log generati per una sessione specifica.

  • filter session_name = "SessionName"

  • filter session_id = "SessionId"