As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Solucionar problemas do agente Connect AI Use este tópico para ajudar a diagnosticar e resolver problemas comuns com os agentes do Connect AI. **Topics** + [Registro e rastreamento para agentes do Connect AI](viewing-logs-for-connect-ai-agents-self-service.md) + [Solucionar problemas de autoatendimento de agentes](ts-agentic-self-service.md) + [Problemas comuns](ts-common-self-service-issues.md) + [Problemas de autoatendimento (antigos)](ts-non-agentic-self-service.md) # Registro e rastreamento para agentes do Connect AI Para solucionar problemas do agente Connect AI de forma eficaz, use as seguintes opções de registro e rastreamento. + **ListSpans API (recomendada para agentes de IA do orquestrador)**: use a [ListSpans](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_ListSpans.html)API para recuperar traços de execução do agente de IA para uma sessão. Esse é o ponto de partida recomendado para depurar as interações do agente de IA do orquestrador, pois fornece visibilidade granular dos fluxos de orquestração do agente, das interações do LLM e das invocações de ferramentas, permitindo rastrear como o agente de IA raciocinou por meio de uma solicitação e quais ferramentas ele selecionou e executou. + **CloudWatch Registros**: ative o CloudWatch registro para seus agentes do Connect AI seguindo as etapas em[Agentes de IA do Monitor Connect](monitor-ai-agents.md). As interações de autoatendimento antigas geram entradas de registro com o tipo de evento `TRANSCRIPT_SELF_SERVICE_MESSAGE` no seguinte formato: ``` { "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}" } ``` As interações de autoatendimento da Agent geram entradas de registro com o tipo de evento. `TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION` Essas entradas incluem o contexto completo da orquestração, como o prompt com as configurações da ferramenta, o histórico de conversas com chamadas e resultados da ferramenta, a conclusão do modelo e a configuração do agente de IA. O exemplo a seguir mostra os campos principais: ``` { "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}" } ``` + **Registro no Amazon Lex (somente por autoatendimento)**: habilite o registro no Amazon Lex seguindo as etapas em [Registro de erros com registros de erros no Amazon Lex V2](https://docs.aws.amazon.com/lexv2/latest/dg/error-logs.html). + **Registro em log do Amazon Connect**: habilite o registro em log do Amazon Connect adicionando um bloco de fluxo [Set logging behavior](set-logging-behavior.md) ao seu fluxo do Amazon Connect. # Solucionar problemas de autoatendimento de agentes Os problemas a seguir são específicos do [autoatendimento de agências](agentic-self-service.md). ## O agente de IA não está respondendo aos clientes Se seu agente de IA estiver processando solicitações, mas os clientes não estiverem vendo nenhuma resposta, o prompt de orquestração pode não ter as instruções de formatação de mensagem necessárias. Os agentes de IA do Orchestrator só exibem mensagens aos clientes quando a resposta do modelo é agrupada em `` tags. Se sua solicitação não instruir o modelo a usar essas tags, as respostas não serão renderizadas ao cliente. **Solução**: certifique-se de que seu prompt de orquestração inclua instruções de formatação que exijam que o modelo agrupe as respostas em tags. `` Para obter mais informações, consulte [Análise de mensagens](use-orchestration-ai-agent.md#message-parsing). ## Falhas na invocação da ferramenta MCP Se seu agente de IA não conseguir invocar as ferramentas MCP durante uma conversa, verifique o seguinte: + **Permissões do perfil de segurança** — Verifique se o perfil de segurança do agente de IA concede acesso às ferramentas MCP específicas de que ele precisa. O agente de IA só pode invocar ferramentas que ele tenha permissão explícita para acessar. + **Conectividade do gateway** — Confirme se o Amazon Bedrock AgentCore Gateway está configurado corretamente e se o URL de descoberta é válido. Verifique se os públicos de autenticação de entrada estão configurados com a ID do gateway. Verifique o status do gateway no AgentCore console. + **Integridade do endpoint da API** — Verifique se a API de back-end ou a função Lambda por trás da ferramenta MCP está sendo executada e respondendo corretamente. Verifique CloudWatch os registros em busca de erros no serviço de destino. ## Permissões do IAM para ferramentas MCP Se as chamadas da ferramenta MCP retornarem erros de acesso negado, verifique se as funções do IAM têm as permissões necessárias: + Função do **Amazon Bedrock AgentCore Gateway — A função** de execução do gateway deve ter permissão para invocar as funções de back-end ou APIs Lambda às quais suas ferramentas MCP se conectam. + Função **vinculada ao serviço Amazon Connect — A função vinculada ao** serviço Amazon Connect deve ter permissão para invocar o Amazon Bedrock Gateway. AgentCore # Problemas comuns ## Combine o AWS SDK mais recente com suas funções do Lambda Se você estiver chamando agentes do Connect AI APIs diretamente das funções do Lambda, deverá empacotar e agrupar a versão mais recente do AWS SDK junto com seu código de função. O ambiente de execução do Lambda pode incluir uma versão mais antiga do SDK que não é compatível com os modelos e recursos mais recentes da API Connect AI Agents. **Sintomas**: você pode enfrentar exceções de validação de parâmetros ou solicitar que os parâmetros de entrada sejam ignorados silenciosamente ao usar uma versão desatualizada do SDK. Para evitar mudanças no modelo de API, inclua o AWS SDK mais recente como uma dependência em seu pacote de implantação ou como uma camada Lambda, em vez de depender do SDK fornecido pelo tempo de execução do Lambda. As etapas para agrupar o SDK variam de acordo com o idioma. Por exemplo, para Node.js, consulte [Criação de um pacote de implantação com dependências](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-package.html#nodejs-package-create-dependencies). Para outras linguagens, consulte a documentação correspondente do pacote de implantação do Lambda. Para compartilhar o SDK em várias funções, consulte [Lambda Lambda Lambda](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html). # Problemas de autoatendimento (antigos) Os problemas a seguir são específicos do [autoatendimento antigo](generative-ai-powered-self-service.md). ## Os clientes estão recebendo a mensagem “Escalating to agent...” O encaminhamento inesperado para atendente ocorre quando há um erro durante a interação do bot de autoatendimento ou quando o modelo não produz uma resposta `tool_use` válida para `SELF_SERVICE_PRE_PROCESS`. ### Etapas de solução de problemas 1. **Verifique os registros do agente Connect AI**: examine o `completion` atributo na entrada de registro associada. 1. **Valide o motivo de parada**: confirme se `stop_reason` é `tool_use`. 1. **Verifique a resposta analisada**: verifique se o campo `parsed_response` está preenchido, pois isso representa a resposta que você receberá do modelo. ### Problema conhecido com o Claude 3 Haiku Se você estiver usando o Claude 3 Haiku para pré-processamento por autoatendimento, há um problema conhecido em que ele gera o JSON `tool_use` como texto, resultando em um `stop_reason` de `end_turn` em vez de `tool_use`. **Solução**: atualize o prompt personalizado para colocar a string JSON `tool_use` entre tags ``, adicionando a seguinte instrução: ``` You MUST enclose the tool_use JSON in the tag ``` ## O chat ou a chamada de voz de autoatendimento estão sendo encerrados inesperadamente Esse problema pode ocorrer devido ao tempo limite do Amazon Lex ou à configuração incorreta do Amazon Nova Pro. Esses problemas são descritos abaixo. ### Tempos limite do Amazon Lex + **Sintomas**: os logs do Amazon Connect mostram “Erro interno do servidor” para o bloco [Obter entrada do cliente](get-customer-input.md). + **Causa**: o bot de autoatendimento atingiu o tempo limite ao fornecer resultados dentro do limite de 10 segundos. Os erros de tempo limite não aparecerão nos registros do agente Connect AI. + **Solução**: simplifique o prompt, removendo raciocínios complexos para reduzir o tempo de processamento. ### Configuração do Amazon Nova Pro Se estiver usando o Amazon Nova Pro para seus prompts de IA personalizados, verifique se os exemplos de tool\$1use seguem o [formato compatível com Python](create-ai-prompts.md#nova-pro-aiprompt).