Solución de problemas - Amazon Q Developer
Errores de configuraciónProblemas de carga de agentes personalizadosProblemas con los permisos de las herramientasDepurar el comportamiento personalizado de los agentes¿Obtener ayuda adicional

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

En esta sección se describen los problemas más comunes que pueden surgir al trabajar con agentes personalizados y cómo resolverlos.

Errores de configuración

Sintaxis JSON no válida

Problema: el agente personalizado no se carga debido a errores de análisis de JSON.

Síntomas:

  • Mensajes de error que mencionan «JSON no válido» o «error de sintaxis»

  • El agente personalizado no aparece en /agent list

  • Recurra al comportamiento predeterminado de los agentes

Soluciones:

  • Valide su JSON con un validador o linter de JSON

  • Comprueba si hay errores comunes de JSON:

    • Faltan comas entre los elementos de la matriz o las propiedades de los objetos

    • Comas finales después del último elemento

    • Corchetes o llaves inigualables

    • Comillas sin escapatoria en los valores de cadena

  • Se utiliza /agent schema para verificar la estructura de configuración

Errores de validación del esquema

Problema: la configuración del agente personalizado no coincide con el esquema esperado.

Síntomas:

  • Advertencias sobre campos de configuración desconocidos

  • El comportamiento del agente personalizado no coincide con la configuración

  • Faltan errores en los campos obligatorios

Soluciones:

  • Compare su configuración con el esquema mediante /agent schema

  • Compruebe los nombres de los campos para ver si hay errores tipográficos (p. ej., allowedTools vsallowedTool)

  • Compruebe que los tipos de datos coincidan con los requisitos del esquema (matrices frente a cadenas, booleanos frente a cadenas)

  • Consulte la documentación sobre el formato del agente en la documentación complementaria de la CLI para desarrolladores de Amazon Q para comprobar la sintaxis correcta.

Problemas de carga de agentes personalizados

No se encontró el agente personalizado

Problema: el agente personalizado no aparece en la lista o no se puede usar.

Síntomas:

  • /agent listno muestra tu agente personalizado

  • /agent use [name]falla con «agente no encontrado»

  • Recurra al agente predeterminado sin previo aviso

Soluciones:

  • Compruebe que el archivo del agente personalizado esté en la ubicación correcta:

    • Global: ~/.aws/amazonq/cli-agents/[name].json

    • Local: amazonq/cli-agents/[name].json

  • Compruebe los permisos del archivo: asegúrese de que el archivo sea legible

  • Compruebe que el nombre del archivo coincide con el nombre del agente personalizado que está intentando usar

  • Asegúrese de que el archivo tenga una .json extensión

Se está cargando una versión incorrecta del agente personalizado

Problema: se está cargando una versión de su agente personalizado diferente a la esperada.

Síntomas:

  • El comportamiento del agente personalizado no coincide con los cambios de configuración recientes

  • Mensaje de advertencia sobre conflictos entre agentes personalizados

  • Disponibilidad o permisos de la herramienta inesperados

Soluciones:

  • Compruebe si hay conflictos de nombres de agentes personalizados entre los directorios locales y globales

  • Recuerde que los agentes personalizados locales tienen prioridad sobre los agentes personalizados globales

  • Úselo /agent list para ver qué versión se está cargando

  • Elimine o cambie el nombre de los archivos del agente personalizado conflictivos si es necesario

Problemas con los permisos de las herramientas

La herramienta no está disponible

Problema: el agente personalizado no puede acceder a la herramienta que has configurado.

Síntomas:

  • Mensajes de error sobre herramientas desconocidas o no disponibles

  • Un agente personalizado solicita permiso para instalar las herramientas allowedTools

  • Las herramientas del servidor MCP no funcionan

Soluciones:

  • Compruebe que los nombres de las herramientas estén escritos correctamente en la matriz tools

  • En el caso de las herramientas MCP, asegúrese de que el servidor esté configurado correctamente en mcpServers

  • Compruebe que los servidores MCP estén funcionando y sean accesibles

  • Utilice la sintaxis correcta para las herramientas de MCP: @server_name/tool_name

  • Verifique los nombres de las herramientas integradas con la documentación de las herramientas integradas en la documentación complementaria de Amazon Q Developer CLI

El comando /tools devuelve una lista vacía

Problema: el /tools comando no muestra ninguna herramienta disponible o muestra menos herramientas de las esperadas.

Síntomas:

  • /toolsdevuelve una lista vacía

  • Faltan las herramientas esperadas en la lista de herramientas

  • El agente personalizado parece no tener capacidades

Causas comunes:

  • toolsMatriz vacía en la configuración del agente personalizado

  • Introduce errores tipográficos en los nombres de las herramientas de la matriz tools

  • Los nombres de las herramientas del servidor MCP son incorrectos (falta el prefijo del servidor)

  • Problemas de configuración del servidor MCP que impiden la carga de la herramienta

Soluciones:

  • Compruebe que su configuración de agente personalizada incluya una tools matriz con nombres de herramientas válidos

  • Compruebe que los nombres de las herramientas estén escritos correctamente (distingue entre mayúsculas y minúsculas)

  • En el caso de las herramientas MCP, asegúrese de utilizar el formato correcto con el prefijo del servidor: server-name___tool-name

  • Pruebe con el agente predeterminado para confirmar que las herramientas están disponibles: entonces q chat /tools

  • Compruebe el estado del servidor MCP si utiliza herramientas externas

Solicitudes de permiso inesperadas

Problema: un agente personalizado solicita permiso para las herramientas que creías que estaban aprobadas previamente.

Síntomas:

  • Solicitudes de permiso para las herramientas enumeradas en allowedTools

  • Interrupciones del flujo de trabajo a pesar de la configuración personalizada del agente

Soluciones:

  • Asegúrese de que las herramientas estén listadas tanto en las matrices como en tools las matrices allowedTools

  • Compruebe si hay errores tipográficos en los nombres de las herramientas entre las dos matrices

  • En el caso de las herramientas MCP, utilice el nombre completo con el prefijo del servidor en allowedTools

  • Compruebe que se han aplicado correctamente toolAliases

Depurar el comportamiento personalizado de los agentes

Falta contexto o recursos

Problema: el agente personalizado no parece tener acceso a los archivos o al contexto esperados.

Soluciones:

  • Compruebe que las rutas de los archivos de la resources matriz sean correctas y que los archivos existan

  • Compruebe que los patrones globales de los recursos coincidan con los archivos previstos

  • Asegúrese de que los comandos hook se ejecuten correctamente y produzcan resultados

  • Pruebe los comandos hook manualmente para comprobar que funcionan en su entorno

  • Compruebe la configuración del tiempo de espera de los ganchos si los comandos se están cortando

Problemas con el servidor MCP

Problema: los servidores MCP no funcionan o las herramientas no están disponibles.

Soluciones:

  • Compruebe que los comandos del servidor MCP sean correctos y que los ejecutables estén en su PATH

  • Compruebe que las variables de entorno requeridas estén configuradas

  • Pruebe los servidores MCP de forma independiente para asegurarse de que funcionan

  • Revise los registros del servidor MCP para ver si hay mensajes de error

  • Aumente los valores de tiempo de espera si los servidores tardan en iniciarse

  • Para obtener más información sobre la solución de problemas de MCP, consulte Uso de MCP con Amazon Q Developer

Probando configuraciones de agentes personalizadas

Para probar sistemáticamente la configuración de su agente personalizado:

  1. Valide la sintaxis de JSON mediante un validador de JSON

  2. Compare la configuración con el esquema mediante /agent schema

  3. Pruebe la carga de un agente personalizado con /agent list

  4. Cambie al agente personalizado con /agent use [name]

  5. Pruebe cada herramienta de forma individual para verificar el acceso y los permisos

  6. Compruebe que los recursos y los enlaces proporcionen el contexto esperado

  7. Pruebe los flujos de trabajo comunes para asegurarse de que el agente personalizado se comporte como se espera

¿Obtener ayuda adicional

Si sigues teniendo problemas con los agentes: