Supervise Amazon Q en Connect mediante CloudWatch registros - Amazon Connect
Permisos de IAM necesariosHabilitar el registroTipos de registro admitidosComprueba las cuotas CloudWatch de registrosDocumentar CloudWatch eventos mediante Interactive HandlerEjemplos de consultas habituales para depurar los registros de los asistentes

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Supervise Amazon Q en Connect mediante CloudWatch registros

Para obtener visibilidad de las recomendaciones en tiempo real que Amazon Q in Connect proporciona a sus agentes y de las intenciones de los clientes que detecta mediante la comprensión del lenguaje natural, puede consultar CloudWatch los registros. CloudWatch Los registros le permiten ver todo el recorrido del contacto: la conversación, los factores desencadenantes, las intenciones y las recomendaciones. También puedes usar esta información para depurar errores o proporcionársela Soporte cuando te pongas en contacto con ellos para solicitar ayuda.

En este tema se explica cómo habilitar el registro de Amazon Q en Connect.

Permisos de IAM necesarios

Antes de activar el registro de un asistente de Amazon Q in Connect, comprueba que tienes los siguientes AWS Identity and Access Management permisos. Son necesarios para la cuenta de usuario con la que se ha iniciado sesión en la consola de Amazon Connect:

  • wisdom:AllowVendedLogDeliveryForResource: necesario para permitir la entrega de registros para el recurso asistente.

Para ver un ejemplo de rol de IAM con todos los permisos necesarios para su destino de registro específico, consulte Logging that requires additional permissions [V2]. Este tema contiene ejemplos de diferentes destinos de registro, como los registros enviados a CloudWatch Logs y los registros enviados a Amazon S3. Los ejemplos muestran cómo permitir las actualizaciones de su recurso de destino de registro específico.

Habilitación del registro en Amazon Q en Connect

Para habilitar el registro de Amazon Q en Connect, usa la CloudWatch API. Siga estos pasos:

  1. Obtenga el ARN de su asistente de Amazon Q en Connect (también conocido como su dominio). Tras crear un asistente, puede obtener su ARN en la consola de Amazon Connect o llamando a la GetAssistantAPI. El ARN tiene el siguiente formato:

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

  2. Llamada PutDeliverySource: utilice esta CloudWatch API para crear una fuente de entrega para el asistente. Pase el ARN del asistente como resourceArn. Para logType, especifique EVENT_LOGS para recopilar los registros de su asistente.

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

  3. Llamada PutDeliveryDestination: utilice esta CloudWatch API para configurar dónde se almacenarán los registros. Puede elegir CloudWatch Logs, Amazon S3 o Amazon Data Firehose como destino para almacenar los registros. Debe especificar el nombre del recurso de Amazon de una de las opciones de destino en las que se almacenarán sus registros. El outputFormat de los registros puede ser uno de los siguientes: json, plain, w3c, raw, parquet.

    El siguiente ejemplo muestra cómo configurar los registros para que se almacenen en un grupo de Amazon CloudWatch Logs y en 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. Llamada CreateDelivery: utilice esta CloudWatch API para vincular la fuente de entrega al destino de entrega que creó en los pasos anteriores. Esta operación de la API asocia el origen de la entrega con el destino final.

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

Tipos de registro admitidos

Amazon Q en Connect admite los siguientes tipos de registro:

  • EVENT_LOGS: registros que rastrean los eventos de un asistente de Amazon Q en Connect durante las llamadas y los chats.

Comprueba las cuotas CloudWatch de registros

Recomendamos comprobar los puntos de enlace y las cuotas de Amazon CloudWatch Logs para comprobar si hay alguna cuota para realizar CloudWatch llamadas a la API relacionadas con la entrega de Logs. Los límites de cuota establecen un número máximo de veces que puede llamar a una API o crear un recurso. Si se supera el límite de la política de bucket, se produce un error de ServiceQuotaExceededException.

Documentar CloudWatch eventos mediante Interactive Handler

Definiciones de tipos de eventos

En la siguiente tabla se describe cada tipo de evento. Tenga en cuenta que los distintos tipos de eventos contienen campos diferentes. Consulte la Definiciones de campo sección para obtener información detallada sobre cada campo.

EventType Definición
TRANSCRIPT_CREATE_SESSION Se registra cuando se crea una nueva sesión de Amazon Q in Connect. Esto marca el comienzo de una conversación.
TRANSCRIPT_INTENT_TRIGGERING_REFERENCE Se registra cuando se detecta una intención específica de un cliente en la conversación, lo que puede provocar respuestas o flujos de trabajo automatizados.
TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION Se registra cuando se invoca un modelo de lenguaje grande (LLM) para generar respuestas o procesar el contenido de una conversación. Registra las entradas y salidas del LLM.
TRANSCRIPT_QUERY_ASSISTANT Se registra cuando se realiza una búsqueda manual o una consulta directa a Amazon Q en Connect
TRANSCRIPT_RECOMMENDATION Se registra cuando el sistema proporciona una recomendación a un agente o cliente, que puede incluir artículos de información, respuestas generadas o acciones sugeridas.
TRANSCRIPT_RESULT_FEEDBACK Se registra cuando se proporcionan comentarios sobre la utilidad o relevancia de un resultado de búsqueda o consulta.
TRANSCRIPT_SELF_SERVICE_MESSAGE Se registra cuando un cliente interactúa con los componentes de autoservicio de Amazon Q en Connect
TRANSCRIPT_SESSION_POLLED Se registra cuando el sistema detecta que un agente está conectado a una sesión (se sondea una sesión cuando se realiza una llamada a la API) GetRecommendations
TRANSCRIPT_TRIGGER_DETECTION_MODEL_INVOCATION Se registra cuando se invoca el modelo de detección de activadores para determinar si una conversación tiene intenciones
TRANSCRIPT_UTTERANCE Se registra cuando un participante de la conversación envía un mensaje y graba el contenido real de la conversación.

Definiciones de campo

En la siguiente tabla se describe cada campo.

Campo Definición
ai_agent_id Identificador único del recurso de agente Amazon Q in Connect AI.
assistant_id Identificador único del recurso de asistente Amazon Q in Connect.
completion El texto de finalización sin procesar devuelto por el LLM o generado para el mensaje.
connect_user_arn Nombre de recurso de Amazon (ARN) del usuario de Connect que accede a la sesión.
event_timestamp Marca de tiempo de Unix (en milisegundos) del momento en que ocurrió el evento.
event_type Tipo de evento, que indica qué acción o proceso se produjo en el sistema.
generation_id Identificador único para una respuesta específica generada por la IA.
Intención El texto o la descripción de la intención.
intent_clicked Un valor booleano que indica si la recomendación se activó por una intención en la que se hizo clic.
intent_id Identificador único de la intención detectada.
probabilidad_problema Probabilidad numérica (0,0—1,0) de que se haya detectado un problema en la conversación (una probabilidad superior a 0,5 provocará la generación de intenciones)
¿es útil la recomendación Un valor booleano que indica si el resultado ha sido útil para el usuario.
is_valid_trigger Un valor booleano que indica si el análisis del modelo de detección produjo un disparador válido.
model_id Identificador del modelo de IA utilizado para invocar el LLM.
parsed_response La processed/parsed versión de la respuesta del modelo de lenguaje, a menudo en formato estructurado.
petición El indicador de entrada utilizado para invocar el LLM.
tipo_de_solicitud Tipo de mensaje de Amazon Q in Connect utilizado para procesar el mensaje o la consulta.
recomendación El contenido real del texto de recomendación proporcionado al usuario
recommendation_id Identificador único de la recomendación.
respuesta El texto de respuesta final generado para el usuario después del procesamiento.
session_event_id Identificador único para un evento específico de la sesión.
session_event_ids Lista de identificadores de eventos de sesión.
session_id Identificador único para la sesión de Amazon Q in Connect.
session_message_id Identificador único para un mensaje de autoservicio dentro de una sesión.
nombre_de_sesión Nombre de la sesión.
Enunciados El texto real del mensaje intercambiado en la conversación.

Ejemplos de registros de asistentes

A continuación, se muestran ejemplos de diferentes registros de eventos para cada tipo de evento. Consulte la Definiciones de tipos de eventos sección para obtener una explicación detallada de cada tipo de 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

Reformulación de consultas


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

Detección de intenciones


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

Generación de respuestas intencionales


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

Generación manual de búsquedas


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

Recomendación


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

Ejemplos de consultas habituales para depurar los registros de los asistentes

Puede interactuar con los registros realizando consultas. Por ejemplo, puede consultar todos los eventos de una sesión mediante SESSION_NAME.

Las siguientes son dos consultas comunes para devolver todos los registros generados para una sesión específica.

  • filter session_name = "SessionName"

  • filter session_id = "SessionId"