Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Solución de problemas con el agente Connect AI
Utilice este tema para ayudar a diagnosticar y resolver problemas comunes con los agentes de Connect AI.
**Topics**
+ [Registro y seguimiento de los agentes de Connect AI](viewing-logs-for-connect-ai-agents-self-service.md)
+ [Solucione los problemas de autoservicio de los agentes](ts-agentic-self-service.md)
+ [Problemas comunes](ts-common-self-service-issues.md)
+ [Problemas de autoservicio (heredados)](ts-non-agentic-self-service.md)
# Registro y seguimiento de los agentes de Connect AI
Para solucionar los problemas del agente Connect AI de forma eficaz, utilice las siguientes opciones de registro y seguimiento.
+ **ListSpans API (recomendada para los agentes de IA de Orchestrator)**: utilice la [ListSpans](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_ListSpans.html)API para recuperar el seguimiento de la ejecución de los agentes de IA durante una sesión. Este es el punto de partida recomendado para depurar las interacciones entre los agentes de IA de Orchestrator, ya que proporciona una visibilidad pormenorizada de los flujos de orquestación de los agentes, las interacciones de la LLM y las invocaciones de herramientas, lo que te permite rastrear cómo el agente de IA razonó una solicitud y qué herramientas seleccionó y ejecutó.
+ **CloudWatch Registros**: habilite el CloudWatch registro para sus agentes de Connect AI siguiendo los pasos que se indican[Agentes de IA de Monitorear Connect](monitor-ai-agents.md).
Las interacciones de autoservicio antiguas generan entradas de registro con el tipo de evento `TRANSCRIPT_SELF_SERVICE_MESSAGE` en el siguiente 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}"
}
```
Las interacciones de autoservicio de los agentes generan entradas de registro con el tipo de evento. `TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION` Estas entradas incluyen el contexto completo de la organización, como el mensaje con las configuraciones de las herramientas, el historial de conversaciones con las llamadas a las herramientas y los resultados, la finalización del modelo y la configuración del agente de IA. El siguiente ejemplo muestra los campos clave:
```
{
"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 de Amazon Lex (solo de autoservicio)**: active el registro de Amazon Lex siguiendo los pasos que se indican en [Registrar errores con registros de errores en Amazon Lex V2](https://docs.aws.amazon.com/lexv2/latest/dg/error-logs.html).
+ **Registro de Amazon Connect**: active el registro de Amazon Connect añadiendo un bloque de flujo [Configurar el comportamiento del registro](set-logging-behavior.md) en su flujo de Amazon Connect.
# Solucione los problemas de autoservicio de los agentes
[Los siguientes problemas son específicos del autoservicio de los agentes.](agentic-self-service.md)
## El agente de IA no responde a los clientes
Si tu agente de IA está procesando las solicitudes pero los clientes no ven ninguna respuesta, es posible que en el mensaje de orquestación falten las instrucciones de formato de mensaje requeridas.
Los agentes de IA de Orchestrator solo muestran los mensajes a los clientes cuando la respuesta del modelo está envuelta en `` etiquetas. Si tu mensaje no indica al modelo que utilice estas etiquetas, las respuestas no se enviarán al cliente.
**Solución**: asegúrese de que su solicitud de orquestación incluya instrucciones de formato que obliguen al modelo a empaquetar las respuestas en `` etiquetas. Para obtener más información, consulte [Análisis de mensajes](use-orchestration-ai-agent.md#message-parsing).
## Fallos en la invocación de la herramienta MCP
Si su agente de IA no invoca las herramientas de MCP durante una conversación, compruebe lo siguiente:
+ **Permisos del perfil de seguridad**: compruebe que el perfil de seguridad del agente de IA permite el acceso a las herramientas de MCP específicas que necesita. El agente de IA solo puede invocar herramientas a las que tenga permiso explícito para acceder.
+ **Conectividad de puerta** de enlace: confirme que Amazon Bedrock AgentCore Gateway esté correctamente configurada y que la URL de descubrimiento sea válida. Compruebe que las audiencias de autenticación entrantes estén configuradas en el ID de la puerta de enlace. Compruebe el estado de la puerta de enlace en la AgentCore consola.
+ Estado del **punto final de la API**: compruebe que la API de backend o la función Lambda detrás de la herramienta MCP se esté ejecutando y respondiendo correctamente. Comprueba CloudWatch los registros para ver si hay errores en el servicio de destino.
## Permisos de IAM para las herramientas de MCP
Si las llamadas a la herramienta MCP devuelven errores de acceso denegado, compruebe que las funciones de IAM tienen los permisos necesarios:
+ Función **Amazon Bedrock AgentCore Gateway: la función** de ejecución de la puerta de enlace debe tener permiso para invocar las funciones de backend o APIs Lambda a las que se conectan las herramientas de MCP.
+ **Función vinculada al servicio Amazon Connect: la función vinculada** al servicio Amazon Connect debe tener permiso para invocar Amazon Bedrock Gateway. AgentCore
# Problemas comunes
## Combine el último AWS SDK con sus funciones de Lambda
Si llama a los agentes de Connect AI APIs directamente desde las funciones de Lambda, debe empaquetar y agrupar la última versión del AWS SDK junto con el código de la función. El entorno de ejecución de Lambda puede incluir una versión anterior del SDK que no sea compatible con los modelos y funciones más recientes de la API de los agentes de Connect AI.
**Síntomas**: Es posible que se produzcan excepciones en la validación de parámetros o que los parámetros de entrada de las solicitudes se ignoren de forma silenciosa cuando se utiliza una versión del SDK anticuada.
Para evitar que el modelo de API se desvíe, incluye el AWS SDK más reciente como dependencia en tu paquete de implementación o como capa Lambda, en lugar de confiar en el SDK que proporciona el entorno de ejecución de Lambda. Los pasos para empaquetar el SDK varían según el idioma. Por ejemplo, para Node.js, consulte [Crear un paquete de implementación con dependencias.](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-package.html#nodejs-package-create-dependencies) Para otros idiomas, consulte la documentación correspondiente del paquete de despliegue de Lambda. Para compartir el SDK entre varias funciones, consulte [Capas Lambda](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html).
# Problemas de autoservicio (heredados)
Los siguientes problemas son específicos del autoservicio [tradicional](generative-ai-powered-self-service.md).
## Los clientes reciben el mensaje “Escalando al agente...” de forma inesperada
El escalado inesperado de los agentes se produce cuando se genera un error durante la interacción del bot de autoservicio o cuando el modelo no genera una respuesta de `tool_use` válida para `SELF_SERVICE_PRE_PROCESS`.
### Pasos para la solución de problemas
1. **Compruebe los registros del agente Connect AI**: examine el `completion` atributo de la entrada de registro asociada.
1. **Valide el motivo de la parada**: confirme que `stop_reason` es `tool_use`.
1. **Verifique la respuesta analizada**: compruebe si el campo `parsed_response` se ha rellenado, ya que representa la respuesta que recibirá del modelo.
### Problema conocido con Claude 3 Haiku
Si utiliza Claude 3 Haiku para el preprocesamiento de autoservicio, se sabe que hay un problema conocido por el que genera el JSON de `tool_use` como texto, lo que da como resultado un `stop_reason` de `end_turn` en lugar de `tool_use`.
**Solución**: actualice su petición personalizada para incluir la cadena de JSON `tool_use` dentro de las etiquetas `` y añadiendo esta instrucción:
```
You MUST enclose the tool_use JSON in the tag
```
## El chat de autoservicio o la llamada de voz finalizan inesperadamente
Este problema puede producirse debido a tiempos de espera de Amazon Lex o a una configuración incorrecta de Amazon Nova Pro. Estos errores se describen a continuación.
### Tiempos de espera de Amazon Lex
+ **Síntomas**: los registros de Amazon Connect muestran un “error interno del servidor” para el bloque [Get customer input (Obtener entrada del cliente)](get-customer-input.md).
+ **Causa**: se ha agotado el tiempo de espera del bot de autoservicio mientras proporcionaba resultados dentro del límite de 10 segundos. Los errores de tiempo de espera no aparecerán en los registros de los agentes de Connect AI.
+ **Solución**: simplifique su petición eliminando los razonamientos complejos para reducir el tiempo de procesamiento.
### Configuración de Amazon Nova Pro
Si utiliza Amazon Nova Pro para sus peticiones de IA personalizadas, asegúrese de que los ejemplos de tool\$1use sigan un [formato compatible con Python](create-ai-prompts.md#nova-pro-aiprompt).