Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Risolvi i problemi relativi all'agente Connect AI
Utilizza questo argomento per diagnosticare e risolvere problemi comuni con gli agenti Connect AI.
**Topics**
+ [Registrazione e tracciamento per gli agenti Connect AI](viewing-logs-for-connect-ai-agents-self-service.md)
+ [Risolvi i problemi relativi al self-service di Agentic](ts-agentic-self-service.md)
+ [Problemi comuni](ts-common-self-service-issues.md)
+ [(Legacy) Problemi relativi al self-service](ts-non-agentic-self-service.md)
# Registrazione e tracciamento per gli agenti Connect AI
Per risolvere efficacemente i problemi degli agenti Connect AI, utilizza le seguenti opzioni di registrazione e tracciamento.
+ **ListSpans API (consigliata per gli agenti AI orchestratori): utilizza l'[ListSpans](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_ListSpans.html)API per recuperare le tracce di esecuzione degli agenti AI** per una sessione. Questo è il punto di partenza consigliato per il debug delle interazioni con gli agenti AI dell'orchestratore, in quanto fornisce una visibilità granulare sui flussi di orchestrazione degli agenti, sulle interazioni LLM e sulle chiamate degli strumenti, consentendoti di tracciare il modo in cui l'agente AI ha risposto a una richiesta e quali strumenti ha selezionato ed eseguito.
+ **CloudWatch Registri**: abilita CloudWatch la registrazione per i tuoi agenti Connect AI seguendo la procedura riportata di seguito. [Monitora gli agenti Connect AI](monitor-ai-agents.md)
Le interazioni self-service precedenti generano voci di registro con il tipo di evento `TRANSCRIPT_SELF_SERVICE_MESSAGE` nel seguente 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}"
}
```
Le interazioni self-service agentiche generano voci di registro con il tipo di evento. `TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION` Queste voci includono il contesto di orchestrazione completo, ad esempio il prompt con le configurazioni degli strumenti, la cronologia delle conversazioni con le chiamate e i risultati degli strumenti, il completamento del modello e la configurazione dell'agente AI. L'esempio seguente mostra i campi chiave:
```
{
"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}"
}
```
+ **Registrazione Amazon Lex (solo self-service)**: abilita la registrazione di Amazon Lex seguendo i passaggi in Registrazione degli [errori con i log degli errori in Amazon](https://docs.aws.amazon.com/lexv2/latest/dg/error-logs.html) Lex V2.
+ **Registrazione di log Amazon Connect**: abilita la registrazione di log di Amazon Connect aggiungendo un blocco di flusso [Imposta il comportamento di registrazione](set-logging-behavior.md) nel flusso di Amazon Connect.
# Risolvi i problemi relativi al self-service di Agentic
[I seguenti problemi sono specifici del self-service agentico.](agentic-self-service.md)
## L'agente AI non risponde ai clienti
Se il tuo agente AI sta elaborando le richieste ma i clienti non vedono alcuna risposta, nel prompt di orchestrazione potrebbero mancare le istruzioni di formattazione dei messaggi richieste.
Gli agenti AI di Orchestrator mostrano i messaggi ai clienti solo quando la risposta del modello è racchiusa in tag. `` Se il prompt non indica al modello di utilizzare questi tag, le risposte non verranno inviate al cliente.
**Soluzione**: assicurati che il prompt di orchestrazione includa istruzioni di formattazione che richiedano al modello di racchiudere le risposte nei tag. `` Per ulteriori informazioni, consulta [Analisi dei messaggi](use-orchestration-ai-agent.md#message-parsing).
## Errori di invocazione dello strumento MCP
Se il tuo agente AI non riesce a richiamare gli strumenti MCP durante una conversazione, controlla quanto segue:
+ **Autorizzazioni del profilo di sicurezza**: verifica che il profilo di sicurezza dell'agente AI consenta l'accesso agli strumenti MCP specifici di cui ha bisogno. L'agente AI può invocare solo strumenti a cui dispone di un'autorizzazione esplicita per accedere.
+ **Connettività gateway**: verifica che Amazon Bedrock AgentCore Gateway sia configurato correttamente e che l'URL di rilevamento sia valido. Verifica che i gruppi di destinatari di autenticazione in entrata siano impostati sull'ID del gateway. Controlla lo stato del gateway nella AgentCore console.
+ **Integrità dell'endpoint dell'API**: verifica che l'API di backend o la funzione Lambda alla base dello strumento MCP sia in esecuzione e risponda correttamente. Controlla i CloudWatch log per verificare la presenza di errori nel servizio di destinazione.
## Autorizzazioni IAM per gli strumenti MCP
Se le chiamate agli strumenti MCP restituiscono errori di accesso negato, verifica che i ruoli IAM dispongano delle autorizzazioni richieste:
+ Ruolo **Amazon Bedrock AgentCore Gateway: il ruolo** di esecuzione del gateway deve essere autorizzato a richiamare le funzioni di backend o APIs Lambda a cui si connettono gli strumenti MCP.
+ Ruolo collegato al **servizio Amazon Connect: il ruolo collegato** al servizio Amazon Connect deve avere l'autorizzazione per richiamare Amazon Bedrock Gateway. AgentCore
# Problemi comuni
## Combina l' AWS SDK più recente con le tue funzioni Lambda
Se chiami gli agenti Connect AI APIs direttamente dalle funzioni Lambda, devi impacchettare e raggruppare l'ultima versione dell' AWS SDK insieme al codice della funzione. L'ambiente di runtime Lambda può includere una versione precedente dell'SDK che non supporta i modelli e le funzionalità API Connect AI Agents più recenti.
**Sintomi**: è possibile che si verifichino eccezioni di convalida dei parametri o che i parametri di input della richiesta vengano ignorati silenziosamente quando si utilizza una versione SDK obsoleta.
Per evitare la deriva del modello API, includi l' AWS SDK più recente come dipendenza nel pacchetto di distribuzione o come livello Lambda anziché affidarti all'SDK fornito dal runtime Lambda. I passaggi per raggruppare l'SDK variano in base alla lingua. Ad esempio, per Node.js, vedi [Creazione di un pacchetto di distribuzione con dipendenze](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-package.html#nodejs-package-create-dependencies). Per altre lingue, consulta la documentazione corrispondente sui pacchetti di distribuzione Lambda. Per condividere l'SDK tra più funzioni, consulta Layer [Lambda](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html).
# (Legacy) Problemi relativi al self-service
[I seguenti problemi sono specifici del self-service preesistente.](generative-ai-powered-self-service.md)
## I clienti ricevono inaspettatamente il messaggio “Escalation all’agente...”
L’escalation imprevista dell’agente accade quando si verifica un errore durante l’interazione con il bot self-service o quando il modello non produce una risposta `tool_use` valida per `SELF_SERVICE_PRE_PROCESS`.
### Fasi per la risoluzione dei problemi
1. **Controlla i log dell'agente Connect AI**: esamina l'`completion`attributo nella voce di registro associata.
1. **Convalida il motivo dell’interruzione**: conferma che `stop_reason` sia `tool_use`.
1. **Verifica la risposta analizzata**: controlla se il campo `parsed_response` è compilato, poiché rappresenta la risposta che riceverai dal modello.
### Problema noto con Claude 3 Haiku
Se utilizzi Claude 3 Haiku per la pre-elaborazione self-service, esiste un problema noto a causa del quale il file JSON `tool_use` viene generato come testo, creando un `stop_reason` di `end_turn` invece di `tool_use`.
**Soluzione**: aggiorna il prompt personalizzato per inserire la stringa JSON `tool_use` all’interno dei tag `` aggiungendo questa istruzione:
```
You MUST enclose the tool_use JSON in the tag
```
## La chat self-service o la chiamata vocale terminano in modo imprevisto
Questo problema può verificarsi a causa di timeout da Amazon Lex o di una configurazione errata di Amazon Nova Pro. Questi problemi sono descritti di seguito.
### Timeout da Amazon Lex
+ **Sintomi**: i log di Amazon Connect mostrano un “Errore interno del server” per il blocco [Recupera input cliente](get-customer-input.md)
+ **Causa**: il tuo bot self-service è scaduto mentre forniva risultati entro il limite di 10 secondi. Gli errori di timeout non verranno visualizzati nei registri degli agenti di Connect AI.
+ **Soluzione**: semplifica il prompt eliminando i ragionamenti complessi per ridurre i tempi di elaborazione.
### Configurazione di Amazon Nova Pro
Se utilizzi Amazon Nova Pro per i tuoi prompt IA personalizzati, assicurati che gli esempi tool\$1use seguano un [formato compatibile con Python](create-ai-prompts.md#nova-pro-aiprompt).