필수 IAM 권한 로깅 활성화 지원되는 로그 유형 CloudWatch Logs 할당량 확인 대화형 핸들러를 사용하여 CloudWatch 이벤트 문서화 어시스턴트 로그를 디버깅하기 위한 일반적인 쿼리의 예

CloudWatch Logs를 사용하여 Connect AI 에이전트 모니터링

Connect AI 에이전트가 에이전트에게 제공하는 실시간 권장 사항과 자연어 이해를 통해 탐지한 고객 의도에 대한 가시성을 확보하려면 CloudWatch Logs를 쿼리할 수 있습니다. CloudWatch Logs는 대화, 트리거, 의도, 권장 사항 등 전체 연락 여정에 대한 가시성을 제공합니다. 이 정보를 디버깅에 사용하거나 도움을 요청할 지원 때에 제공할 수도 있습니다.

이 주제에서는 Connect AI 에이전트에 대한 로깅을 활성화하는 방법을 설명합니다.

필수 IAM 권한

Connect 어시스턴트에 대한 로깅을 활성화하기 전에 다음 AWS Identity and Access Management 권한이 있는지 확인합니다. Amazon Connect 콘솔에 로그인한 사용자 계정에 필요합니다.

wisdom:AllowVendedLogDeliveryForResource: 어시스턴트 리소스에 대한 로그 전달을 허용하는 데 필요합니다.

특정 로깅 대상에 필요한 모든 권한이 있는 예시 IAM 역할을 보려면 Logging that requires additional permissions [V2]를 참조하세요. 이 주제에는 CloudWatch Logs로 전송된 로그 및 Amazon S3로 전송된 로그와 같은 다양한 로깅 대상에 대한 예제가 포함되어 있습니다. 예제에서는 특정 로깅 대상 리소스에 대한 업데이트를 허용하는 방법을 보여 줍니다.

Connect AI 에이전트에 대한 로깅 활성화

Connect AI 에이전트에 대한 로깅을 활성화하려면 CloudWatch API를 사용합니다. 다음 단계를 완료합니다.

어시스턴트(도메인이라고도 함)의 ARN을 가져옵니다. 어시스턴트를 생성한 후 Amazon Connect 콘솔에서 또는 GetAssistant API를 직접적으로 호출하여 ARN을 가져올 수 있습니다. ARN은 다음 형식을 따릅니다.

arn:aws:wisdom:your-region:your-account-id:assistant/assistant-id
PutDeliverySource: 이 CloudWatch API를 사용하여 어시스턴트의 전송 소스를 생성합니다. 어시스턴트의 ARN을 resourceArn으로 전달합니다. logType의 경우 EVENT_LOGS를 지정하여 어시스턴트에서 로그를 수집합니다.
```
{
    "logType": "EVENT_LOGS",
    "name": "your-assistant-delivery-source",
    "resourceArn": "arn:aws:wisdom:your-region:your-account-id:assistant/assistant_id
}
```
PutDeliveryDestination 직접 호출: 이 CloudWatch API를 사용하여 로그를 저장할 위치를 구성합니다. 로그 저장 대상으로 CloudWatch Logs, Amazon S3 또는 Amazon Data Firehose를 선택할 수 있습니다. 로그를 저장할 대상 옵션 중 하나의 ARN을 지정해야 합니다. 로그의 outputFormat을 json, plain, w3c, raw, parquet 중 하나로 선택할 수 있습니다.

다음 예제에서는 Amazon CloudWatch Logs 그룹 및 JSON 형식으로 저장할 로그를 구성하는 방법을 보여 줍니다.
```
{
    "deliveryDestinationConfiguration": {
        "destinationResourceArn": "arn:aws:logs:your-region:your-account-id:log-group:your-log-group-name:*"
    },
    "name": "string",
    "outputFormat": "json",
    "tags": {
        "key": "value"
    }
}
```
CreateDelivery 직접 호출: 이 CloudWatch API를 사용하여 이전 단계에서 생성한 전송 대상에 전송 소스를 연결합니다. 이 API 작업은 전송 소스를 최종 대상과 연결합니다.
```
{
    "deliveryDestinationArn": "string",
    "deliverySourceName": "string",
    "tags": {
        "string": "string"
    }
}
```

지원되는 로그 유형

Connect AI 에이전트는 다음 로그 유형을 지원합니다.

EVENT_LOGS: 통화, 채팅, 작업 및 이메일 중에 Connect 어시스턴트의 이벤트를 추적하는 로그입니다.

CloudWatch Logs 할당량 확인

Amazon CloudWatch Logs 엔드포인트 및 할당량을 확인하여 CloudWatch Logs 전송 관련 API 직접 호출을 수행할 할당량이 있는지 확인하는 것이 좋습니다. 할당량은 API를 직접적으로 호출하거나 리소스를 생성할 수 있는 최대 횟수를 설정합니다. 제한을 초과할 경우 ServiceQuotaExceededException 오류가 발생합니다.

대화형 핸들러를 사용하여 CloudWatch 이벤트 문서화

이벤트 유형 정의

다음 테이블에 각 옵션이 설명되어 있습니다. 다른 이벤트 유형에는 다른 필드가 포함되어 있습니다. 각 필드에 대한 자세한 내용은 필드 정의 섹션을 참조하세요.

EventType	정의
TRANSCRIPT_CREATE_SESSION	새 Connect AI 에이전트 세션이 생성될 때 로깅됩니다. 이는 대화의 시작을 나타냅니다.
TRANSCRIPT_INTENT_TRIGGERING_REFERENCE	대화에서 특정 고객 의도가 감지되면 로깅되어 자동 응답 또는 워크플로가 트리거될 수 있습니다.
TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION	대규모 언어 모델(LLM)이 간접적으로 호출되어 응답을 생성하거나 대화 콘텐츠를 처리할 때 로깅됩니다. LLM에 대한 입력과 LLM의 출력을 기록합니다.
TRANSCRIPT_QUERY_ASSISTANT	AnswerRecommendation, CaseSummarization, EmailGenerativeAnswer, EmailOverview, EmailResponse, ManualSearch, NoteTaking 중 하나를 호출할 때 로깅됩니다.
TRANSCRIPT_RECOMMENDATION	시스템이 에이전트 또는 고객에게 권장 사항을 제공할 때 로깅됩니다. 여기에는 지식 문서, 생성된 응답 또는 제안된 작업이 포함될 수 있습니다.
TRANSCRIPT_RESULT_FEEDBACK	검색 또는 쿼리 결과의 유용성 또는 관련성에 대한 피드백이 제공되면 로깅됩니다.
TRANSCRIPT_SELF_SERVICE_MESSAGE	고객이 SelfService Connect AI 에이전트와 상호 작용할 때 로깅됨
TRANSCRIPT_SESSION_POLLED	시스템이 에이전트가 세션에 연결되어 있음을 감지하면 로깅됩니다(GetRecommendations API 직접 호출이 수행되면 세션이 폴링됨).
TRANSCRIPT_TRIGGER_DETECTION_MODEL_INVOCATION	대화에 의도가 있는지 확인하기 위해 트리거 감지 모델을 간접적으로 호출할 때 로깅됩니다.
TRANSCRIPT_UTTERANCE	대화의 참가자가 메시지를 전송하여 실제 대화 콘텐츠를 기록할 때 로깅됩니다.

필드 정의

다음 테이블에 각 옵션이 설명되어 있습니다.

Field	정의
ai_agent_id	Connect AI 에이전트 리소스의 고유 식별자입니다.
assistant_id	Connect 어시스턴트 리소스의 고유 식별자입니다.
completion	LLM에서 반환하거나 메시지에 대해 생성된 원시 완료 텍스트입니다.
connect_user_arn	세션에 액세스하는 Connect 사용자의 Amazon 리소스 이름(ARN)입니다.
event_timestamp	이벤트가 발생한 시점의 Unix 타임스탬프(밀리초)입니다.
event_type	시스템에서 발생한 작업 또는 프로세스를 나타내는 이벤트 유형입니다.
generation_id	특정 AI 생성 응답의 고유 식별자입니다.
intent	의도 텍스트 또는 설명입니다.
intent_clicked	추천이 클릭 의도에 의해 트리거되었는지 여부를 나타내는 부울입니다.
intent_id	감지된 의도의 고유 식별자입니다.
issue_probability	대화에서 문제가 감지된 수치적 확률(0.0~1.0)(0.5보다 큰 확률은 의도 생성을 간접적으로 호출함)입니다.
is_recommendation_useful	사용자가 결과를 유용하게 찾았는지 여부를 나타내는 부울입니다.
is_valid_trigger	감지 모델 분석에서 유효한 트리거가 발생했는지 여부를 나타내는 부울입니다.
model_id	LLM을 간접적으로 호출하는 데 사용되는 AI 모델의 식별자입니다.
parsed_response	종종 구조화된 형식의 언어 모델 응답의 처리/파싱된 버전입니다.
prompt	LLM을 간접적으로 호출하는 데 사용되는 입력 프롬프트입니다.
prompt_type	메시지 또는 쿼리를 처리하는 데 사용되는 AI 프롬프트 유형입니다.
recommendation	사용자에게 제공된 실제 권장 사항 텍스트 콘텐츠
recommendation_ID	권장 사항의 고유 식별자입니다.
response	처리 후 사용자에 대해 생성된 최종 응답 텍스트입니다.
session_event_id	세션 내 특정 이벤트의 고유 식별자입니다.
session_event_ids	세션 이벤트 식별자 목록입니다.
session_id	Connect AI 에이전트 세션의 고유 식별자입니다.
session_message_id	세션 내 셀프 서비스 메시지의 고유 식별자입니다.
session_name	세션의 이름입니다.
utterance	대화에서 교환된 실제 메시지 텍스트입니다.

어시스턴트 로그의 예

다음은 각 이벤트 유형에 대한 다양한 이벤트 로그의 예입니다. 각 이벤트 유형에 대한 자세한 설명은 이벤트 유형 정의 섹션을 참조하세요.

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

쿼리 재구성



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

의도 감지



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

의도 답변 생성



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

수동 검색 생성



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

권장 사항



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

발화



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

어시스턴트 로그를 디버깅하기 위한 일반적인 쿼리의 예

쿼리를 사용하여 로그와 상호 작용할 수 있습니다. 예를 들어 SESSION_NAME을 사용하여 세션 내의 모든 이벤트를 쿼리할 수 있습니다.

다음은 특정 세션에 대해 생성된 모든 로그를 반환하는 두 가지 일반적인 쿼리입니다.

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

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

단계별 가이드와 통합

에이전트 애플리케이션에서 Connect AI 에이전트 액세스