기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Connect AI 에이전트 문제 해결
이 주제를 사용하여 Connect AI 에이전트의 일반적인 문제를 진단하고 해결할 수 있습니다.
**Topics**
+ [Connect AI 에이전트에 대한 로깅 및 추적](viewing-logs-for-connect-ai-agents-self-service.md)
+ [에이전트 셀프 서비스 문제 해결](ts-agentic-self-service.md)
+ [일반적인 문제](ts-common-self-service-issues.md)
+ [(레거시) 셀프 서비스 문제](ts-non-agentic-self-service.md)
# Connect AI 에이전트에 대한 로깅 및 추적
Connect AI 에이전트 문제를 효과적으로 해결하려면 다음 로깅 및 추적 옵션을 사용합니다.
+ **ListSpans API(오케스트레이터 AI 에이전트에 권장)**: [ListSpans](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_ListSpans.html) API를 사용하여 세션에 대한 AI 에이전트 실행 추적을 검색합니다. 이는 오케스트레이터 AI 에이전트 상호 작용을 디버깅하는 데 권장되는 시작점으로, 에이전트 오케스트레이션 흐름, LLM 상호 작용 및 도구 호출에 대한 세분화된 가시성을 제공하므로 요청을 통해 AI 에이전트가 추론한 방식과 선택 및 실행한 도구를 추적할 수 있습니다.
+ **CloudWatch Logs**:의 단계에 따라 Connect AI 에이전트에 대해 CloudWatch 로깅을 활성화합니다[Connect AI 에이전트 모니터링](monitor-ai-agents.md).
레거시 셀프 서비스 상호 작용은 이벤트 유형이 다음 형식인 로그 항목을 생성합니다`TRANSCRIPT_SELF_SERVICE_MESSAGE`.
```
{
"assistant_id": "{UUID}",
"event_timestamp": 1751414298692,
"event_type": "TRANSCRIPT_SELF_SERVICE_MESSAGE",
"session_id": "{UUID}",
"utterance": "[CUSTOMER]...",
"prompt": "{prompt used}",
"prompt_type": "SELF_SERVICE_PRE_PROCESS|SELF_SERVICE_ANSWER_GENERATION",
"completion": "{Response from model}",
"model_id": "{model id e.g.: us.amazon.nova-pro-v1:0}",
"session_message_id": "{UUID}",
"parsed_response": "{model response}"
}
```
에이전트 셀프 서비스 상호 작용은 이벤트 유형이 인 로그 항목을 생성합니다`TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION`. 이러한 항목에는 도구 구성이 포함된 프롬프트, 도구 호출 및 결과가 포함된 대화 기록, 모델 완성 및 AI 에이전트 구성과 같은 전체 오케스트레이션 컨텍스트가 포함됩니다. 다음 예제에서는 키 필드를 보여줍니다.
```
{
"assistant_id": "{UUID}",
"event_timestamp": 1772748470993,
"event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
"session_id": "{UUID}",
"prompt": "{full prompt including system instructions, tool configs, and conversation history}",
"prompt_type": "ORCHESTRATION",
"completion": "{model response with message and tool use}",
"model_id": "{model id e.g.: us.anthropic.claude-haiku-4-5-20251001-v1:0}",
"parsed_response": "{parsed customer-facing message}",
"generation_id": "{UUID}",
"ai_agent_id": "{UUID}"
}
```
+ **Amazon Lex 로깅(셀프 서비스만 해당)**: Amazon Lex [ V2의 오류 로그로 오류 로깅의 단계에 따라 Amazon Lex 로깅을](https://docs.aws.amazon.com/lexv2/latest/dg/error-logs.html) 활성화합니다.
+ **Amazon Connect 로깅**: Amazon Connect 흐름에 [로깅 동작 설정](set-logging-behavior.md) 흐름 블록을 추가하여 Amazon Connect 로깅을 활성화합니다.
# 에이전트 셀프 서비스 문제 해결
다음은 [에이전트 셀프 서비스에](agentic-self-service.md) 특정한 문제입니다.
## AI 에이전트가 고객에게 응답하지 않음
AI 에이전트가 요청을 처리하고 있지만 고객에게 응답이 표시되지 않는 경우 오케스트레이션 프롬프트에 필요한 메시지 형식 지정 지침이 누락되었을 수 있습니다.
오케스트레이터 AI 에이전트는 모델의 응답이 `` 태그로 래핑된 경우에만 고객에게 메시지를 표시합니다. 프롬프트가 이러한 태그를 사용하도록 모델에 지시하지 않으면 응답이 고객에게 렌더링되지 않습니다.
**해결** 방법: 오케스트레이션 프롬프트에 모델이 응답을 `` 태그로 래핑해야 하는 형식 지정 지침이 포함되어 있는지 확인합니다. 자세한 내용은 [메시지 구문 분석](use-orchestration-ai-agent.md#message-parsing) 단원을 참조하십시오.
## MCP 도구 호출 실패
AI 에이전트가 대화 중에 MCP 도구를 호출하지 못하는 경우 다음을 확인하세요.
+ **보안 프로필 권한** - AI 에이전트의 보안 프로필이 필요한 특정 MCP 도구에 대한 액세스 권한을 부여하는지 확인합니다. AI 에이전트는 액세스 권한이 있는 도구만 호출할 수 있습니다.
+ **게이트웨이 연결** - Amazon Bedrock AgentCore Gateway가 올바르게 구성되었고 검색 URL이 유효한지 확인합니다. 인바운드 인증 대상이 게이트웨이 ID로 설정되어 있는지 확인합니다. AgentCore 콘솔에서 게이트웨이 상태를 확인합니다.
+ **API 엔드포인트 상태** - MCP 도구 뒤의 백엔드 API 또는 Lambda 함수가 실행 중이고 올바르게 응답하는지 확인합니다. CloudWatch Logs에서 대상 서비스에 오류가 있는지 확인합니다.
## MCP 도구에 대한 IAM 권한
MCP 도구 호출이 액세스 거부 오류를 반환하는 경우 IAM 역할에 필요한 권한이 있는지 확인합니다.
+ **Amazon Bedrock AgentCore Gateway 역할** - 게이트웨이의 실행 역할에는 MCP 도구가 연결되는 백엔드 APIs 또는 Lambda 함수를 호출할 수 있는 권한이 있어야 합니다.
+ **Amazon Connect 서비스 연결 역할** - Amazon Connect 서비스 연결 역할에는 Amazon Bedrock AgentCore Gateway를 호출할 수 있는 권한이 있어야 합니다.
# 일반적인 문제
## 최신 AWS SDK를 Lambda 함수와 번들링
Lambda 함수에서 직접 Connect AI 에이전트 APIs 호출하는 경우 함수 코드와 함께 최신 버전의 AWS SDK를 패키징하고 번들링해야 합니다. Lambda 런타임 환경에는 최신 Connect AI 에이전트 API 모델 및 기능을 지원하지 않는 이전 버전의 SDK가 포함될 수 있습니다.
**증상**: 오래된 SDK 버전을 사용할 때 파라미터 검증 예외가 발생하거나 입력 파라미터가 자동으로 무시되도록 요청할 수 있습니다.
API 모델 드리프트를 방지하려면 Lambda 런타임에서 제공하는 AWS SDK에 의존하지 않고 최신 SDK를 배포 패키지에 종속성으로 포함하거나 Lambda 계층으로 포함하세요. SDK 번들링 단계는 언어에 따라 다릅니다. 예를 들어 Node.js[의 경우 종속성이 있는 배포 패키지 생성을](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-package.html#nodejs-package-create-dependencies) 참조하세요. 다른 언어는 해당 Lambda 배포 패키징 설명서를 참조하세요. 여러 함수에서 SDK를 공유하려면 [Lambda 계층](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html)을 참조하세요.
# (레거시) 셀프 서비스 문제
다음은 [레거시 셀프 서비스에](generative-ai-powered-self-service.md) 특정한 문제입니다.
## 고객이 예기치 않게 "에이전트에 에스컬레이션 중..." 메시지를 받는 경우
예기치 않은 에이전트 에스컬레이션은 셀프 서비스 봇 상호 작용 중에 오류가 발생하거나 모델이 `SELF_SERVICE_PRE_PROCESS`에 대해 유효한 `tool_use` 응답을 생성하지 않을 때 발생합니다.
### 문제 해결 단계
1. **AI 에이전트 로그 연결**: 연결된 로그 항목의 `completion` 속성을 검사합니다.
1. **중지 이유 확인**: `stop_reason`이 `tool_use`인지 확인합니다.
1. **구문 분석된 응답 확인**: 모델로부터 수신할 응답을 나타내므로 `parsed_response` 필드가 채워졌는지 확인합니다.
### Claude 3 Haiku와 관련된 알려진 문제
셀프 서비스 사전 처리에 Claude 3 Haiku를 사용하는 경우 `tool_use` JSON을 텍스트로 생성하는 알려진 문제가 있어 `tool_use` 대신 `end_turn`의 `stop_reason`이 됩니다.
**해결 방법**: 다음 지침을 추가하여 `` 태그 내에 `tool_use` JSON 문자열을 래핑하도록 사용자 지정 프롬프트를 업데이트합니다.
```
You MUST enclose the tool_use JSON in the tag
```
## 셀프 서비스 채팅 또는 음성 통화가 예기치 않게 종료됨
이 문제는 Amazon Lex의 제한 시간 또는 잘못된 Amazon Nova Pro 구성으로 인해 발생할 수 있습니다. 이러한 문제는 아래에서 설명됩니다.
### Amazon Lex의 제한 시간
+ **증상**: Amazon Connect 로그에 [고객 입력 가져오기](get-customer-input.md) 블록에 대한 "내부 서버 오류"가 표시됨
+ **원인**: 10초 제한 내에서 결과를 제공하는 동안 셀프 서비스 봇이 시간 초과되었습니다. 제한 시간 오류는 Connect AI 에이전트 로그에 표시되지 않습니다.
+ **해결 방법**: 복잡한 추론을 제거하여 프롬프트를 간소화하여 처리 시간을 단축합니다.
### Amazon Nova Pro 구성
사용자 지정 AI 프롬프트에 Amazon Nova Pro를 사용하는 경우 tool\$1use 예제가 [Python 호환 형식을](create-ai-prompts.md#nova-pro-aiprompt) 따르는지 확인합니다.