Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Résoudre les problèmes liés à l'agent Connect AI
Utilisez cette rubrique pour diagnostiquer et résoudre les problèmes courants liés aux agents Connect AI.
**Topics**
+ [Journalisation et suivi pour les agents Connect AI](viewing-logs-for-connect-ai-agents-self-service.md)
+ [Résoudre les problèmes liés à l'agentic en libre-service](ts-agentic-self-service.md)
+ [Problèmes courants](ts-common-self-service-issues.md)
+ [(Legacy) Problèmes liés au libre-service](ts-non-agentic-self-service.md)
# Journalisation et suivi pour les agents Connect AI
Pour résoudre efficacement les problèmes liés à l'agent Connect AI, utilisez les options de journalisation et de suivi suivantes.
+ **ListSpans API (recommandée pour les agents Orchestrator AI)** : utilisez l'[ListSpans](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_ListSpans.html)API pour récupérer les traces d'exécution des agents AI pour une session. Il s'agit du point de départ recommandé pour le débogage des interactions entre les agents d'IA d'Orchestrator, car il fournit une visibilité granulaire sur les flux d'orchestration des agents, les interactions LLM et les invocations d'outils, ce qui vous permet de suivre le raisonnement de l'agent AI dans le cadre d'une demande et les outils qu'il a sélectionnés et exécutés.
+ **CloudWatch Journaux** : activez la CloudWatch journalisation pour vos agents Connect AI en suivant les étapes décrites dans[Surveillez les agents Connect AI](monitor-ai-agents.md).
Les anciennes interactions en libre-service génèrent des entrées de journal avec le type d'`TRANSCRIPT_SELF_SERVICE_MESSAGE`événement au format suivant :
```
{
"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}"
}
```
Les interactions en libre-service d'Agentic génèrent des entrées de journal avec le type d'événement. `TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION` Ces entrées incluent le contexte d'orchestration complet, tel que l'invite avec les configurations des outils, l'historique des conversations avec les appels aux outils et les résultats, l'achèvement du modèle et la configuration de l'agent AI. L'exemple suivant montre les champs clés :
```
{
"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}"
}
```
+ **Journalisation Amazon Lex (en libre-service uniquement)** : activez la journalisation Amazon Lex en suivant les étapes de la section [Journalisation des erreurs avec les journaux d'erreurs dans Amazon Lex V2](https://docs.aws.amazon.com/lexv2/latest/dg/error-logs.html).
+ **Journalisation Amazon Connect** : activez la journalisation Amazon Connect en ajoutant un bloc de flux [Définir le comportement de journalisation](set-logging-behavior.md) dans votre flux Amazon Connect.
# Résoudre les problèmes liés à l'agentic en libre-service
Les problèmes suivants sont spécifiques au self-service [agentic](agentic-self-service.md).
## L'agent AI ne répond pas aux clients
Si votre agent d'intelligence artificielle traite les demandes mais que les clients ne voient aucune réponse, il se peut que l'invite d'orchestration ne contienne pas les instructions de formatage des messages requises.
Les agents Orchestrator AI n'affichent des messages aux clients que lorsque la réponse du modèle est encapsulée dans des `` balises. Si votre invite n'indique pas au modèle d'utiliser ces balises, aucune réponse ne sera rendue au client.
**Solution** : assurez-vous que votre invite d'orchestration inclut des instructions de mise en forme qui obligent le modèle à encapsuler les réponses dans des `` balises. Pour de plus amples informations, veuillez consulter [Analyse syntaxique des messages](use-orchestration-ai-agent.md#message-parsing).
## Défaillances d'invocation de l'outil MCP
Si votre agent d'intelligence artificielle ne parvient pas à invoquer les outils MCP au cours d'une conversation, vérifiez les points suivants :
+ **Autorisations du profil de sécurité** — Vérifiez que le profil de sécurité de l'agent AI autorise l'accès aux outils MCP spécifiques dont il a besoin. L'agent AI ne peut invoquer que les outils auxquels il est explicitement autorisé à accéder.
+ **Connectivité à la passerelle** : vérifiez que la AgentCore passerelle Amazon Bedrock est correctement configurée et que l'URL de découverte est valide. Vérifiez que les audiences d'authentification entrantes sont définies sur l'ID de passerelle. Vérifiez l'état de la passerelle dans la AgentCore console.
+ **État du point de terminaison** de l'API : vérifiez que l'API principale ou la fonction Lambda qui sous-tend l'outil MCP s'exécute et répond correctement. Vérifiez CloudWatch les journaux pour détecter les erreurs dans le service cible.
## Autorisations IAM pour les outils MCP
Si les appels de l'outil MCP renvoient des erreurs d'accès refusé, vérifiez que les rôles IAM disposent des autorisations requises :
+ Rôle **Amazon Bedrock AgentCore Gateway : le rôle** d'exécution de la passerelle doit être autorisé à appeler les fonctions principales ou APIs Lambda auxquelles vos outils MCP se connectent.
+ Rôle **lié au service Amazon Connect — Le rôle lié** au service Amazon Connect doit être autorisé à invoquer la passerelle Amazon Bedrock. AgentCore
# Problèmes courants
## Intégrez le dernier AWS SDK à vos fonctions Lambda
Si vous appelez des agents Connect AI APIs directement depuis les fonctions Lambda, vous devez empaqueter et regrouper la dernière version du AWS SDK avec votre code de fonction. L'environnement d'exécution Lambda peut inclure une ancienne version du SDK qui ne prend pas en charge les derniers modèles et fonctionnalités d'API des agents Connect AI.
**Symptômes** : vous pouvez rencontrer des exceptions de validation des paramètres ou demander que les paramètres d'entrée soient ignorés silencieusement lorsque vous utilisez une version obsolète du SDK.
Pour éviter toute dérive du modèle d'API, incluez le dernier AWS SDK en tant que dépendance dans votre package de déploiement ou en tant que couche Lambda plutôt que de vous fier au SDK fourni par le moteur d'exécution Lambda. Les étapes pour regrouper le SDK varient en fonction de la langue. Par exemple, pour Node.js, voir [Création d'un package de déploiement avec dépendances](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-package.html#nodejs-package-create-dependencies). Pour les autres langues, reportez-vous à la documentation du package de déploiement Lambda correspondante. Pour partager le SDK entre plusieurs fonctions, consultez la section [Lambda layers](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html).
# (Legacy) Problèmes liés au libre-service
Les problèmes suivants sont spécifiques aux [anciens systèmes de libre-service.](generative-ai-powered-self-service.md)
## Les clients reçoivent de façon inattendue le message « Transférer à l’agent... »
Un transfert d’agent inattendu se produit lorsqu’une erreur a lieu lors de l’interaction avec le bot en libre-service ou lorsque le modèle ne produit pas de réponse `tool_use` valide pour `SELF_SERVICE_PRE_PROCESS`.
### Étapes de résolution des problèmes
1. **Vérifiez les journaux de l'agent Connect AI** : examinez l'`completion`attribut dans l'entrée de journal associée.
1. **Validez le motif de l’arrêt** : confirmez que `stop_reason` est `tool_use`.
1. **Vérifiez la réponse analysée** : Vérifiez si le champ `parsed_response` est rempli, car il représente la réponse que vous recevrez du modèle.
### Problème connu avec Claude 3 Haiku
Si vous utilisez Claude 3 Haiku pour le prétraitement en libre-service, il existe un problème connu selon lequel il génère le JSON `tool_use` sous forme de texte, ce qui se traduit par un `stop_reason` de `end_turn` au lieu de `tool_use`.
**Solution** : Mettez à jour votre invite personnalisée pour inclure la chaîne JSON `tool_use` dans les balises `` en ajoutant cette instruction :
```
You MUST enclose the tool_use JSON in the tag
```
## Le chat ou l’appel vocal en libre-service s’arrête de façon inattendue
Ce problème peut être dû à des délais impartis par Amazon Lex ou à une configuration incorrecte d'Amazon Nova Pro. Ces problèmes sont décrits ci-dessous.
### Délais d’attente d’Amazon Lex
+ **Symptômes** : les journaux Amazon Connect indiquent une « erreur interne du serveur » pour le bloc [Obtenir les données client](get-customer-input.md)
+ **Cause** : votre bot en libre-service a expiré alors qu’il fournissait des résultats dans le délai de 10 secondes. Les erreurs de temporisation n'apparaîtront pas dans les journaux des agents Connect AI.
+ **Solution** : Simplifiez votre invite en supprimant les raisonnements complexes afin de réduire le temps de traitement.
### Configuration d’Amazon Nova Pro
Si vous utilisez Amazon Nova Pro pour vos invites d’IA personnalisées, assurez-vous que les exemples tool\$1use suivent un [format compatible avec Python.](create-ai-prompts.md#nova-pro-aiprompt)