기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # CloudWatch Logs를 사용하여 Connect AI 에이전트 모니터링 Connect AI 에이전트가 에이전트에게 제공하는 실시간 권장 사항과 자연어 이해를 통해 탐지한 고객 의도에 대한 가시성을 확보하려면 CloudWatch Logs를 쿼리할 수 있습니다. CloudWatch Logs는 대화, 트리거, 의도, 권장 사항 등 전체 연락 여정에 대한 가시성을 제공합니다. 이 정보를 디버깅에 사용하거나 도움을 요청할 지원 때에 제공할 수도 있습니다. 이 주제에서는 Connect AI 에이전트에 대한 로깅을 활성화하는 방법을 설명합니다. **Topics** + [필수 IAM 권한](#permissions-cw-q) + [로깅 활성화](#enable-assistant-logging) + [지원되는 로그 유형](#supported-log-types-q) + [CloudWatch Logs 할당량 확인](#cwl-quotas) + [대화형 핸들러를 사용하여 CloudWatch 이벤트 문서화](#documenting-cw-events-ih) + [어시스턴트 로그를 디버깅하기 위한 일반적인 쿼리의 예](#example2-assistant-log) ## 필수 IAM 권한 Connect 어시스턴트에 대한 로깅을 활성화하기 전에 다음 AWS Identity and Access Management 권한이 있는지 확인합니다. Amazon Connect 콘솔에 로그인한 사용자 계정에 필요합니다. + `wisdom:AllowVendedLogDeliveryForResource`: 어시스턴트 리소스에 대한 로그 전달을 허용하는 데 필요합니다. 특정 로깅 대상에 필요한 모든 권한이 있는 예시 IAM 역할을 보려면 [Logging that requires additional permissions [V2]](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html#AWS-vended-logs-permissions-V2)를 참조하세요. 이 주제에는 CloudWatch Logs로 전송된 로그 및 Amazon S3로 전송된 로그와 같은 다양한 로깅 대상에 대한 예제가 포함되어 있습니다. 예제에서는 특정 로깅 대상 리소스에 대한 업데이트를 허용하는 방법을 보여 줍니다. ## Connect AI 에이전트에 대한 로깅 활성화 Connect AI 에이전트에 대한 로깅을 활성화하려면 CloudWatch API를 사용합니다. 다음 단계를 완료합니다. 1. *어시스턴트*([*도메*](ai-agent-initial-setup.md#ai-agent-requirements)인이라고도 함)의 ARN을 가져옵니다. [어시스턴트를 생성](ai-agent-initial-setup.md#enable-ai-agents-step1)한 후 Amazon Connect 콘솔에서 또는 [GetAssistant](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_GetAssistant.html) API를 직접적으로 호출하여 ARN을 가져올 수 있습니다. ARN은 다음 형식을 따릅니다. `arn:aws:wisdom:your-region:your-account-id:assistant/assistant-id` 1. [PutDeliverySource](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliverySource.html): 이 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 } ``` 1. [PutDeliveryDestination](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliveryDestination.html) 직접 호출: 이 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" } } ``` 1. [CreateDelivery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateDelivery.html) 직접 호출: 이 CloudWatch API를 사용하여 이전 단계에서 생성한 전송 대상에 전송 소스를 연결합니다. 이 API 작업은 전송 소스를 최종 대상과 연결합니다. ``` { "deliveryDestinationArn": "string", "deliverySourceName": "string", "tags": { "string": "string" } } ``` ## 지원되는 로그 유형 Connect AI 에이전트는 다음 로그 유형을 지원합니다. + `EVENT_LOGS`: 통화, 채팅, 작업 및 이메일 중에 Connect 어시스턴트의 이벤트를 추적하는 로그입니다. ## CloudWatch Logs 할당량 확인 [Amazon CloudWatch Logs 엔드포인트 및 할당량](https://docs.aws.amazon.com/general/latest/gr/cwl_region.html)을 확인하여 CloudWatch Logs 전송 관련 API 직접 호출을 수행할 할당량이 있는지 확인하는 것이 좋습니다. 할당량은 API를 직접적으로 호출하거나 리소스를 생성할 수 있는 최대 횟수를 설정합니다. 제한을 초과할 경우 `ServiceQuotaExceededException` 오류가 발생합니다. ## 대화형 핸들러를 사용하여 CloudWatch 이벤트 문서화 ### 이벤트 유형 정의 다음 테이블에 각 옵션이 설명되어 있습니다. 다른 이벤트 유형에는 다른 필드가 포함되어 있습니다. 각 필드에 대한 자세한 내용은 [필드 정의](#field-definitions) 섹션을 참조하세요. | EventType | 정의 | | --- | --- | | TRANSCRIPT\$1CREATE\$1SESSION | 새 Connect AI 에이전트 세션이 생성될 때 로깅됩니다. 이는 대화의 시작을 나타냅니다. | | TRANSCRIPT\$1INTENT\$1TRIGGERING\$1REFERENCE | 대화에서 특정 고객 의도가 감지되면 로깅되어 자동 응답 또는 워크플로가 트리거될 수 있습니다. | | TRANSCRIPT\$1LARGE\$1LANGUAGE\$1MODEL\$1INVOCATION | 대규모 언어 모델(LLM)이 간접적으로 호출되어 응답을 생성하거나 대화 콘텐츠를 처리할 때 로깅됩니다. LLM에 대한 입력과 LLM의 출력을 기록합니다. | | TRANSCRIPT\$1QUERY\$1ASSISTANT | AnswerRecommendation, CaseSummarization, EmailGenerativeAnswer, EmailOverview, EmailResponse, ManualSearch, NoteTaking 중 하나를 호출할 때 로깅됩니다. | | TRANSCRIPT\$1RECOMMENDATION | 시스템이 에이전트 또는 고객에게 권장 사항을 제공할 때 로깅됩니다. 여기에는 지식 문서, 생성된 응답 또는 제안된 작업이 포함될 수 있습니다. | | TRANSCRIPT\$1RESULT\$1FEEDBACK | 검색 또는 쿼리 결과의 유용성 또는 관련성에 대한 피드백이 제공되면 로깅됩니다. | | TRANSCRIPT\$1SELF\$1SERVICE\$1MESSAGE | 고객이 SelfService Connect AI 에이전트와 상호 작용할 때 로깅됨 | | TRANSCRIPT\$1SESSION\$1POLLED | 시스템이 에이전트가 세션에 연결되어 있음을 감지하면 로깅됩니다(GetRecommendations API 직접 호출이 수행되면 세션이 폴링됨). | | TRANSCRIPT\$1TRIGGER\$1DETECTION\$1MODEL\$1INVOCATION | 대화에 의도가 있는지 확인하기 위해 트리거 감지 모델을 간접적으로 호출할 때 로깅됩니다. | | TRANSCRIPT\$1UTTERANCE | 대화의 참가자가 메시지를 전송하여 실제 대화 콘텐츠를 기록할 때 로깅됩니다. | ### 필드 정의 다음 테이블에 각 옵션이 설명되어 있습니다. | Field | 정의 | | --- | --- | | ai\$1agent\$1id | Connect AI 에이전트 리소스의 고유 식별자입니다. | | assistant\$1id | Connect 어시스턴트 리소스의 고유 식별자입니다. | | completion | LLM에서 반환하거나 메시지에 대해 생성된 원시 완료 텍스트입니다. | | connect\$1user\$1arn | 세션에 액세스하는 Connect 사용자의 Amazon 리소스 이름(ARN)입니다. | | event\$1timestamp | 이벤트가 발생한 시점의 Unix 타임스탬프(밀리초)입니다. | | event\$1type | 시스템에서 발생한 작업 또는 프로세스를 나타내는 이벤트 유형입니다. | | generation\$1id | 특정 AI 생성 응답의 고유 식별자입니다. | | intent | 의도 텍스트 또는 설명입니다. | | intent\$1clicked | 추천이 클릭 의도에 의해 트리거되었는지 여부를 나타내는 부울입니다. | | intent\$1id | 감지된 의도의 고유 식별자입니다. | | issue\$1probability | 대화에서 문제가 감지된 수치적 확률(0.0\$11.0)(0.5보다 큰 확률은 의도 생성을 간접적으로 호출함)입니다. | | is\$1recommendation\$1useful | 사용자가 결과를 유용하게 찾았는지 여부를 나타내는 부울입니다. | | is\$1valid\$1trigger | 감지 모델 분석에서 유효한 트리거가 발생했는지 여부를 나타내는 부울입니다. | | model\$1id | LLM을 간접적으로 호출하는 데 사용되는 AI 모델의 식별자입니다. | | parsed\$1response | 종종 구조화된 형식의 언어 모델 응답의 처리/파싱된 버전입니다. | | prompt | LLM을 간접적으로 호출하는 데 사용되는 입력 프롬프트입니다. | | prompt\$1type | 메시지 또는 쿼리를 처리하는 데 사용되는 AI 프롬프트 유형입니다. | | recommendation | 사용자에게 제공된 실제 권장 사항 텍스트 콘텐츠 | | recommendation\$1ID | 권장 사항의 고유 식별자입니다. | | response | 처리 후 사용자에 대해 생성된 최종 응답 텍스트입니다. | | session\$1event\$1id | 세션 내 특정 이벤트의 고유 식별자입니다. | | session\$1event\$1ids | 세션 이벤트 식별자 목록입니다. | | session\$1id | Connect AI 에이전트 세션의 고유 식별자입니다. | | session\$1message\$1id | 세션 내 셀프 서비스 메시지의 고유 식별자입니다. | | session\$1name | 세션의 이름입니다. | | utterance | 대화에서 교환된 실제 메시지 텍스트입니다. | ### 어시스턴트 로그의 예 다음은 각 이벤트 유형에 대한 다양한 이벤트 로그의 예입니다. 각 이벤트 유형에 대한 자세한 설명은 [이벤트 유형 정의](#event-type-definitions) 섹션을 참조하세요. #### 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": "The customer is asking for information on how to autoscale DynamoDB.", "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\n - Step 2. yes\n - Step 3. To learn how to autoscale DynamoDB.", "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\n - Step 2. yes\n - Step 3. To learn how to autoscale DynamoDB.", "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"`