Gemini CLI Subagents

¿Qué son los subagentes de Gemini CLI?

Los subagentes son agentes expertos especializados que operan junto a tu sesión principal de Gemini CLI. Cuando le das a Gemini CLI una tarea amplia o compleja, el agente principal puede delegar subtareas específicas al subagente más relevante, actuando como orquestador.

Cada subagente se ejecuta de forma aislada con su propia ventana de contexto separada, instrucciones del sistema personalizadas y un conjunto curado de herramientas. Su trabajo —que puede involucrar muchas llamadas a herramientas, búsquedas o ejecuciones de pruebas— se consolida en una única respuesta devuelta a la sesión principal.

Características principales

• Delegación a expertos especializados: Gemini CLI puede descomponer una tarea grande en subtareas y enrutarlas a subagentes específicos.
• Entornos de ejecución aislados: Cada subagente se ejecuta con su propia ventana de contexto, instrucciones del sistema y herramientas curadas, lo que ayuda a evitar que la sesión principal se sature.
• Consolidación de herramientas y contexto: Los pasos intermedios realizados por los subagentes se consolidan en una sola respuesta para el agente principal.
• Ejecución paralela de subagentes: Gemini CLI admite ejecutar múltiples subagentes simultáneamente (ya sea subagentes diferentes o múltiples instancias del mismo subagente).
• Definiciones personalizadas de subagentes: Puedes crear tus propios subagentes usando archivos Markdown simples con YAML frontmatter.

Cómo usar los subagentes de Gemini CLI

1. Crea una definición de subagente usando un archivo Markdown (.md) con YAML frontmatter que especifique campos como name, description, tools y model (como se muestra en el ejemplo proporcionado para un “frontend-specialist”).
2. Agrega la definición en una de las ubicaciones compatibles:
   • Para flujos de trabajo personales: ~/.gemini/agents
   • Para compartir en equipo/proyecto: .gemini/agents
   • Para extensiones: incluye archivos Markdown de definición de agentes en el directorio agents/ de una extensión.
3. Usa Gemini CLI como siempre: proporciona tu tarea general en la sesión principal de Gemini CLI; Gemini CLI puede entonces despachar subagentes para manejar subtareas relevantes.
4. (Si es necesario) ejecuta trabajo en paralelo: cuando las tareas se dividen naturalmente en múltiples pistas independientes de investigación/refactorización/pruebas, Gemini CLI puede despachar múltiples subagentes al mismo tiempo.

Casos de uso

• Investigación en múltiples temas: Delega hilos de investigación separados a diferentes subagentes y ejecútalos en paralelo, luego recibe salidas consolidadas en la sesión principal.
• Refactorización de múltiples componentes: Divide una refactorización en tareas distintas a nivel de componente y deja que subagentes especializados trabajen en cada área sin saturar la ventana de contexto principal.
• Exploración y análisis de código: Usa subagentes expertos para investigar secciones de código y devolver resúmenes o resultados formateados mientras el agente principal mantiene la toma de decisiones y la síntesis final.
• Pruebas y validación: Descarga secuencias de pasos relacionados con pruebas (que pueden involucrar muchas llamadas a herramientas) a subagentes para que la sesión principal siga siendo receptiva.
• Automatización específica de flujos de trabajo con personalidades personalizadas: Crea un agente especialista reutilizable (p. ej., una personalidad frontend/UI-UX) para imponer un enfoque consistente y uso de herramientas en flujos de trabajo de proyectos repetidos.

Preguntas frecuentes

¿En qué se diferencian los subagentes de la sesión principal de Gemini CLI?
Los subagentes son agentes expertos especializados que se ejecutan junto a tu sesión principal. Operan de forma aislada con su propia ventana de contexto, instrucciones del sistema y herramientas, y luego devuelven resultados consolidados.

¿Puede Gemini CLI ejecutar más de un subagente a la vez?
Sí. Gemini CLI admite ejecución paralela, incluyendo la generación de múltiples subagentes o múltiples instancias del mismo subagente simultáneamente.

¿Cómo se configuran los subagentes personalizados?
Los subagentes personalizados se definen con archivos Markdown (.md) que incluyen YAML frontmatter. Puedes colocarlos en ~/.gemini/agents para uso personal, .gemini/agents para compartir a nivel de proyecto, o en el directorio agents/ de una extensión.

¿Qué pasa con el trabajo intermedio que realizan los subagentes?
Los subagentes pueden ejecutar muchas llamadas a herramientas, búsquedas de archivos o ejecuciones de pruebas, pero su ejecución se consolida en una sola respuesta de vuelta al agente principal.

¿Tienen los subagentes sus propias herramientas e instrucciones del sistema?
Sí. Cada subagente se ejecuta con su propio conjunto curado de herramientas e instrucciones del sistema personalizadas, distintas de la sesión principal.

Alternativas

• Solicitud a un solo agente sin delegación: Puedes pedirle a Gemini CLI que maneje todo en un solo contexto. Esto evita la configuración de agentes personalizados, pero puede requerir indicaciones largas o sufrir por el crecimiento del contexto.
• División manual del flujo de trabajo: Puedes ejecutar indicaciones separadas e independientes para cada subtarea y luego fusionar los resultados tú mismo. Esto puede imitar la delegación, pero tú manejas la orquestación y consolidación.
• Frameworks multiagente de propósito general: Los enfoques multiagente basados en herramientas o frameworks también pueden enrutar tareas a roles especializados, aunque el flujo de trabajo y la configuración diferirían de las definiciones de subagentes y el modelo de aislamiento de Gemini CLI.
• Roles de agente basados en chat (no subagentes): Si tu caso de uso es principalmente asistencia basada en roles en lugar de ejecución paralela de herramientas aisladas, es posible que la solicitud de roles más simple sea suficiente, con menos control sobre el aislamiento y las salidas de subtrabajos consolidadas.