Administración de los agentes personalizados - Amazon Q Developer
Ubicaciones de archivos de los agentes personalizadosPrácticas recomendadas para la organización de los agentes personalizadosUso compartido de los agentes personalizados con los equipos

Administración de los agentes personalizados

En esta sección se explica cómo organizar, administrar y trabajar con los agentes personalizados de forma eficaz en el flujo de trabajo de desarrollo.

Ubicaciones de archivos de los agentes personalizados

Los archivos de configuración de los agentes personalizados se almacenan como archivos JSON en directorios específicos:

Agentes personalizados globales

~/.aws/amazonq/cli-agents/{agent-name}.json

Disponibles en todos los proyectos y directorios del sistema.

Agentes personalizados del proyecto

.amazonq/cli-agents/{agent-name}.json

Disponibles únicamente en el directorio del proyecto específico y sus subdirectorios.

Importante: El {agent-name} del nombre de archivo se incluye únicamente con fines de referencia. El nombre real del agente viene determinado por el campo name del propio archivo de configuración JSON, que es obligatorio.

Prioridad de los agentes personalizados y resolución de conflictos

Cuando la CLI de Amazon Q Developer busca un agente personalizado, sigue un orden de prioridad específico:

  1. En primer lugar, los agentes personalizados locales: comprueba si hay agentes personalizados en el directorio de trabajo actual.

  2. En segundo lugar, los agentes personalizados globales: recurre a los agentes personalizados del directorio principal.

  3. Agentes predeterminados e integrados: utiliza el agente predeterminado si no se encuentra ningún agente personalizado.

Si los directorios locales y globales incluyen agentes personalizados con el mismo nombre, el agente personalizado local tiene prioridad. La CLI de Amazon Q Developer mostrará un mensaje de advertencia cuando esto ocurra:

WARNING: Agent conflict for my-agent. Using workspace version.

Este sistema de prioridad le permite:

  • reemplazar los agentes personalizados globales por versiones específicas del proyecto,

  • realizar una prueba local de las modificaciones realizadas en los agentes personalizados antes de convertirlas en globales,

  • mantener diferentes configuraciones de los agentes personalizados para distintos proyectos.

Prácticas recomendadas para la organización de los agentes personalizados

Cuándo usar los agentes personalizados globales

Utilice los agentes personalizados globales para:

  • Flujos de trabajo de uso general: agentes personalizados que se utilizan en varios proyectos

  • Productividad personal: agentes personalizados adaptados al estilo de trabajo individual

  • Tareas de desarrollo habituales: revisión de código, depuración, generación de documentación, etc.

  • Flujos de trabajo específicos de herramientas: administración de AWS, operaciones de Git, flujos de trabajo de Docker, etc.

Cuándo usar los agentes personalizados locales

Utilice los agentes personalizados locales para:

  • Configuraciones específicas de proyectos: agentes personalizados que necesitan acceder a archivos específicos de proyectos

  • Colaboración en equipo: agentes personalizados que se comparten a través del control de versiones

  • Entornos de desarrollo: agentes personalizados con requisitos únicos para proyectos específicos

  • Pruebas y experimentación: modificaciones temporales realizadas en los agentes personalizados sin que se vea afectada la configuración global

Convenciones de nomenclatura de los agentes personalizados

Tenga en cuenta estas convenciones de nomenclatura para organizar mejor los agentes personalizados:

  • Nombres basados en el uso: aws-specialist.json, code-reviewer.json y documentation-writer.json.

  • Nombres específicos de la tecnología: python-dev.json, react-frontend.json y terraform-ops.json.

  • Nombres específicos del proyecto: project-alpha.json, mobile-app.json y api-backend.json.

  • Nombres específicos del entorno: development.json, staging.json y production.json.

Uso compartido de los agentes personalizados con los equipos

Los agentes personalizados locales se pueden compartir con los miembros del equipo a través de los sistemas de control de versiones. Este método permite a los equipos:

  • Estandarizar los entornos de desarrollo: asegúrese de que todos los miembros del equipo tengan acceso a las mismas herramientas y configuraciones.

  • Compartir el contexto específico del proyecto: incluya la documentación del proyecto, los estándares de codificación y los scripts personalizados.

  • Mantener la coherencia: asegúrese de que todos los miembros del equipo utilicen las mismas configuraciones y permisos de la herramienta.

  • Colaborar en las mejoras: utilice las solicitudes de extracción para revisar y mejorar las configuraciones de los agentes personalizados.

Prácticas recomendadas para el control de versiones

Al compartir agentes personalizados mediante el control de versiones, debe:

  • Incluir directorios de agentes personalizados: añada .aws/amazonq/agents/ al repositorio.

  • Documentar el objetivo de los agentes personalizados: utilice descripciones claras en los archivos de configuración de los agentes personalizados.

  • Revisar los cambios realizados en los agentes personalizados: trate los cambios de configuración realizados en los agentes personalizados como cambios de código.

  • Probar las configuraciones de los agentes personalizados: compruebe que los agentes personalizados compartidos funcionen correctamente para todos los miembros del equipo.

  • Evitar el uso de información confidencial: no incluya claves de API, contraseñas ni información personal en los agentes personalizados compartidos.