Required IAM permissions Enable logging Supported log types Check for CloudWatch Logs quotas Documenting CloudWatch Events by using Interactive Handler Examples of common queries to debug assistant logs

Monitor Amazon Q in Connect by using CloudWatch Logs

To gain visibility into the real-time recommendations that Amazon Q in Connect provides to your agents, and the customer intents it detects through natural language understanding, you can query CloudWatch Logs. CloudWatch Logs give you visibility into the entire contact journey: the conversation, triggers, intents, recommendations. You can also use this information for debugging, or provide it to Support when you contact them for help.

This topic explains how to enable logging for Amazon Q in Connect.

Required IAM permissions
Enable logging
Supported log types
Check for CloudWatch Logs quotas
Documenting CloudWatch Events by using Interactive Handler
Examples of common queries to debug assistant logs

Required IAM permissions

Before you enable logging for an Amazon Q in Connect assistant, check that you have the following AWS Identity and Access Management permissions. They are required for the user account that is signed into the Amazon Connect console:

wisdom:AllowVendedLogDeliveryForResource: Required to allow logs to be delivered for the assistant resource.

To view an example IAM role with all the required permissions for your specific logging destination, see Logging that requires additional permissions [V2]. That topic contains examples for different logging destinations, such as logs sent to CloudWatch Logs and logs sent to Amazon S3 The examples show how to allow updates to your specific logging destination resource.

Enable logging for Amazon Q in Connect

To enable logging for Amazon Q in Connect, you use the CloudWatch API. Complete the following steps.

Get the ARN of your Amazon Q in Connect assistant (also known as its domain). After you create an assistant, you can obtain it's ARN from the Amazon Connect console or by calling the GetAssistant API. The ARN follows this format:

arn:aws:wisdom:your-region:your-account-id:assistant/assistant-id
Call PutDeliverySource: Use this CloudWatch API to create a delivery source for the assistant. Pass the ARN of the assistant as the resourceArn. For logType, specify EVENT_LOGS to collect logs from your assistant.
```
{
    "logType": "EVENT_LOGS",
    "name": "your-assistant-delivery-source",
    "resourceArn": "arn:aws:wisdom:your-region:your-account-id:assistant/assistant_id
}
```
Call PutDeliveryDestination: Use this CloudWatch API to configure where the logs are to be stored. You can choose CloudWatch Logs, Amazon S3, or Amazon Data Firehose as the destination for storing logs. You must specify the ARN of one of the destination options for where your logs are to be stored. You can choose the outputFormat of the logs to be one of the following: json, plain, w3c, raw, parquet.

The following example shows how to configure logs to be stored in an Amazon CloudWatch Logs Group and in JSON format.
```
{
    "deliveryDestinationConfiguration": {
        "destinationResourceArn": "arn:aws:logs:your-region:your-account-id:log-group:your-log-group-name:*"
    },
    "name": "string",
    "outputFormat": "json",
    "tags": {
        "key": "value"
    }
}
```
Call CreateDelivery: Use this CloudWatch API to link the delivery source to the delivery destination that you created in the previous steps. This API operation associates the delivery source with the end destination.
```
{
    "deliveryDestinationArn": "string",
    "deliverySourceName": "string",
    "tags": {
        "string": "string"
    }
}
```

Supported log types

Amazon Q in Connect supports the following log type:

EVENT_LOGS: Logs that track event of an Amazon Q in Connect assistant during calls and chats.

Check for CloudWatch Logs quotas

We recommend checking Amazon CloudWatch Logs endpoints and quotas to see whether there are any quotas for making CloudWatch Logs delivery-related API calls. Quotas set a maximum number of times you can call an API or create a resource. Exceeding the limit results in a ServiceQuotaExceededException error.

Documenting CloudWatch Events by using Interactive Handler

Event Type Definitions

The following table describes each event type. Note that different event types contain different fields. Refer to the Field Definitions section for detailed information about each field.

EventType	Definition
TRANSCRIPT_CREATE_SESSION	Logged when a new Amazon Q in Connect session is created. This marks the beginning of a conversation.
TRANSCRIPT_INTENT_TRIGGERING_REFERENCE	Logged when a specific customer intent is detected in the conversation, which may trigger automated responses or workflows.
TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION	Logged when a large language model (LLM) is invoked to generate responses or process conversation content. Records the inputs to and outputs from the LLM.
TRANSCRIPT_QUERY_ASSISTANT	Logged when a manual search or direct query is made to Amazon Q in Connect
TRANSCRIPT_RECOMMENDATION	Logged when the system provides a recommendation to an agent or customer, which may include knowledge articles, generated responses, or suggested actions.
TRANSCRIPT_RESULT_FEEDBACK	Logged when feedback is provided about a search or query result's usefulness or relevance.
TRANSCRIPT_SELF_SERVICE_MESSAGE	Logged when a customer interacts with self-service components of Amazon Q in Connect
TRANSCRIPT_SESSION_POLLED	Logged when the system detects an agent is connected to a session (A session is polled when a GetRecommendations API call has been made)
TRANSCRIPT_TRIGGER_DETECTION_MODEL_INVOCATION	Logged when the trigger detection model is invoked to determine if a conversation has intents
TRANSCRIPT_UTTERANCE	Logged when a message is sent by any participant in the conversation, recording the actual conversation content.

Field Definitions

The following table describes each field.

Field	Definition
ai_agent_id	Unique identifier for the Amazon Q in Connect AI agent resource.
assistant_id	Unique identifier for the Amazon Q in Connect assistant resource.
completion	The raw completion text returned by the LLM or generated for the message.
connect_user_arn	Amazon Resource Name (ARN) of the Connect user accessing the session.
event_timestamp	Unix timestamp (in milliseconds) when the event occurred.
event_type	Type of the event, indicating what action or process occurred in the system.
generation_id	Unique identifier for a specific AI-generated response.
intent	The intent text or description.
intent_clicked	Boolean indicating if the recommendation was triggered by a clicked intent.
intent_id	Unique identifier for the detected intent.
issue_probability	Numerical probability (0.0–1.0) that an issue was detected in the conversation (A probability greater than 0.5 will invoke intent generation)
is_recommendation_useful	Boolean indicating whether the user found the result helpful.
is_valid_trigger	Boolean indicating whether the detection model analysis resulted in a valid trigger.
model_id	Identifier of the AI model used to invoke the LLM.
parsed_response	The processed/parsed version of the language model response, often in structured format.
prompt	The input prompt used to invoke the LLM.
prompt_type	Type of Amazon Q in Connect prompt used for processing the message or query.
recommendation	The actual recommendation text content provided to the user
recommendation_id	Unique identifier for the recommendation.
response	The final response text generated for the user after processing.
session_event_id	Unique identifier for a specific event within the session.
session_event_ids	List of session event identifiers.
session_id	Unique identifier for the Amazon Q in Connect session.
session_message_id	Unique identifier for a self-service message within a session.
session_name	Name of the session.
utterance	The actual message text exchanged in the conversation.

Examples of assistant logs

Below are examples of different event logs for each event type. Refer to the Event Type Definitions section for detailed explanations of each event type.

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

Query Reformulation



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

Intent Detection



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

Intent Answer Generation



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

Manual Search Generation



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

Recommendation



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

Examples of common queries to debug assistant logs

You can interact with logs by using queries. For example, you can query for all events within a session by using SESSION_NAME.

Following are two common queries to return all the logs generated for a specific session.

filter session_name = "SessionName"
filter session_id = "SessionId"

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Integrate with step-by-step guides

Assign permissions