Subagentes de Gemini CLI: aislamiento de contexto, límites de herramientas y un especialista README

Gemini CLI puede dividir una tarea entre asistentes especializados en lugar de acumular todo en una sola conversación. La transformación consiste en pasar de un agente multiusos a una pequeña red de especialistas, y se basa en tres conceptos: cómo se gestiona el contexto, cómo se aíslan las herramientas y cómo se organiza el trabajo de forma interactiva. Esta primera introducción aborda los aspectos básicos y crea un especialista funcional mínimo.

Por qué una conversación larga falla

En una sesión ordinaria de LLM, los datos de la sesión son, en efecto, globales. Cada archivo leído, cada comando ejecutado y cada aclaración quedan registrados en una historia lineal.

Pida al asistente que depure una fuga de memoria y, diez minutos después, pídale que resuma una transcripción de reunión. Ahora la solicitud de resumen se encuentra entre fragmentos de código y registros dejados tras la depuración. Esto es deterioro del contexto, y conlleva tres consecuencias negativas:

• Latencia. El modelo vuelve a leer material no relacionado en cada turno.
• Deriva de la atención. Su enfoque se dispersa entre temas que no tienen nada que ver entre sí.
• Tokenes desperdiciados. Los mismos registros de depuración se generan una y otra vez.

El problema se discute ampliamente, y la solución en Gemini CLI son los subagentes.

Imagínese una firma de consultoría. Un gerente que lee personalmente cada documento, realiza cada análisis y responde a cada correo electrónico eventualmente no puede recordar lo que sucedió el primer día. Un gerente que asigna cada tarea a un especialista y recibe solo un informe de una página puede seguir trabajando durante mucho más tiempo sin perder el hilo. Los subagentes aplican el mismo patrón de gestión a un asistente de programación: el especialista realiza el trabajo complicado en privado, y solo la conclusión llega al registro compartido.

Hub y radios

Gemini CLI utiliza un diseño de tipo hub y radios. La sesión principal es el hub, que actúa como gestor, mientras que los subagentes son los radios, que funcionan como especialistas.

El reinicio del contexto

Cuando el gestor llama a un subagente, este se abre con una ventana de contexto vacía. Solo recibe la tarea y las instrucciones relevantes. Al finalizar, envía un breve resumen al gestor. Los pasos intermedios, como leer veinte archivos o ejecutar cinco búsquedas, se descartan del historial, de modo que el contexto principal permanece ligero. La exploración prolongada sigue consumiendo tokens dentro de la propia ventana del especialista, pero esos tokens se gastan una sola vez y luego se eliminan, en lugar de trasladarse a cada turno posterior de la conversación principal.

De qué está compuesto un subagente

Un subagente se define en un archivo Markdown que comienza con frontmatter YAML. El frontmatter contiene metadatos de alto nivel: el nombre del agente, una descripción de su propósito y las herramientas que puede utilizar, entre otros ajustes. El archivo funciona como un contrato que describe para qué sirve el especialista y qué puede manejar. La documentación oficial incluye una referencia al formato del archivo de definición de agentes si se desea conocer la lista completa de campos de antemano.

Hay dos campos que merecen especial atención. La descripción es lo que lee el administrador al decidir si una tarea corresponde a este especialista; por lo tanto, una descripción vaga conduce a una delegación errónea o omitida, mientras que una precisa garantiza una asignación fiable. La lista de herramientas representa el límite de seguridad, ya que un subagente solo puede actuar a través de las herramientas que se le han asignado. Trate el archivo como lo haría con una descripción del puesto de trabajo combinada con una placa de acceso.

Hello world: un especialista en README

El primer especialista realizará una sola tarea: examinar el directorio actual y redactar un README.md sólido, sin posibilidad de modificar nada.

Preparar la carpeta

Los subagentes de un proyecto único se encuentran en .gemini/agents/ dentro de dicho proyecto. Para que estén disponibles en todas partes para su usuario, créelos en ~/.gemini/agents en su lugar. Elija una carpeta que contenga archivos de código fuente para que el agente tenga algo que analizar, muévalo allí y cree el directorio a nivel de proyecto:

mkdir .gemini/agents

Escribir la definición

Cree .gemini/agents/readme-architect.md con el siguiente contenido:

---
name: readme-architect
description: Specialized in analyzing project structures and writing professional README.md files.
tools:
- read_file
- glob
model: inherit
---

You are a Technical Writer. Your goal is to look at the files in the current
directory and draft a README.md that includes:
1. Project Name.
2. Installation instructions.
3. A brief description of the file structure.

Do not modify any files; only provide the Markdown text.
---

Varios puntos al respecto:

1. name y description son self-explanatory.
2. La entrada tools enumera las únicas herramientas que puede utilizar este agente; en este caso read_file y glob para buscar archivos. Este campo es opcional, pero si se omite, el subagente hereda todas las herramientas de su padre. Al listar solo dos, se asegura de que este no pueda escribir ni guardar nada.
3. La configuración model permite asignar un modelo específico al subagente. Aquí, el agente simplemente hereda el modelo de la sesión principal.
4. El Markdown que se encuentra debajo del frontmatter es el prompt de sistema del subagente, y define cómo se comportará.

En resumen, un subagente consta de metadatos en la parte superior y una instrucción que define su comportamiento debajo de ellos. Dado que se trata simplemente de un archivo de texto dentro del repositorio, se puede revisar, versionar y compartir con los compañeros de equipo de la misma manera que cualquier otro archivo de proyecto, lo que facilita la estandarización de los especialistas de un equipo.

La orden /agents

La orden /agents funciona como un centro de control para la red de especialistas. Permite inspeccionar, gestionar y verificar los subagentes.

Detección y verificación

Después de guardar el archivo, compruebe que el administrador haya detectado al nuevo miembro. Inicie Gemini CLI. Si el archivo se encuentra en la ubicación correcta, la CLI detectará al nuevo agente al iniciar y mostrará un cuadro de información. Elija “Aceptar y habilitar”.

Luego ejecute /agents list. Esto consulta el registro local, y readme-architect debería aparecer. Eso confirma que el administrador ve al agente como una herramienta disponible. Si el nombre no aparece, las causas más comunes son un archivo guardado en la carpeta incorrecta, un bloque de frontmatter con un error de escritura o guiones faltantes, o una sesión iniciada antes de que existiera el archivo y que necesita reiniciarse.

Nota: la versión actual de la CLI también incluye tres subagentes integrados, codebase_investigator, cli_help y generalist. Los subagentes personalizados son el tema de este texto, por lo que quedan fuera de su alcance, aunque la documentación oficial los describe.

Gestión de agentes en tiempo de ejecución

Un agente puede resultar demasiado entusiasta, o es posible que no quieras que el administrador lo utilice por sí solo. Ejecuta /agents disable readme-architect. Esto lo elimina del grupo de delegación automática, de modo que el administrador no usará a ese experto a menos que lo invoques explícitamente con la sintaxis @. /agents enable readme-architect lo vuelve a incluir.

Al escribir solo /agents se muestran los demás comandos disponibles, que vale la pena probar rápidamente:

▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
 > /agents
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
 reload    Reload the agent registry
 list      List available local and remote agents
 enable    Enable a disabled agent
 disable   Disable an enabled agent
 config    Configure an agent
 workspace (/directory)

Los subagentes aparecen como herramientas

Una vez que se activan los subagentes, aparecen como herramientas del agente principal. Ejecute /tools y busque readme-architect en la lista. Un ejemplo de una configuración es el siguiente:

▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
 > /tools
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
Available Gemini CLI tools:

  - Activate Skill (activate_skill)
  - Ask User (ask_user)
  - CLI Help Agent (cli_help)
  - Codebase Investigator Agent (codebase_investigator)
  - Edit (replace)
  - Enter Plan Mode (enter_plan_mode)
  - FindFiles (glob)
  - Generalist Agent (generalist)
  - GoogleSearch (google_web_search)
  - ReadFile (read_file)
  - ReadFolder (list_directory)
  - readme-architect (readme-architect)
  - SaveMemory (save_memory)
  - SearchText (grep_search)
  - Shell (run_shell_command)
  - WebFetch (web_fetch)
  - WriteFile (write_file)

Probándolo

Para ver cómo funcionan el aislamiento de contexto y las restricciones de herramientas, ejecute:

@readme-architect Analice este proyecto y redacte un README.

Aspectos a observar:

1. El interfaz cambia. La CLI pasa a un modo de subtarea y transfiere el trabajo, mostrando una línea que indica que delegará el análisis y la redacción del README al subagente readme-architect.
2. Uso de herramientas. El agente solo utiliza las herramientas que se le han proporcionado, read_file y glob.
3. Un resultado. Después de un rato, se recibe el trabajo terminado. Un ejemplo de una carpeta:

╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ≡ Agent Completed (ctrl+o to expand)                                                                                                                                                    │
│ ✓ readme-architect · Completed successfully                                                                                                                                             │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ The readme-architect has drafted a README for your project:

  MyTasks Math Utility

  A lightweight JavaScript utility library for performing basic arithmetic operations.

  Installation

  Since this project consists of a single utility file without external dependencies, you can integrate it into your environment as follows:

   1. Clone or download this repository.
   2. Copy math.js into your project's directory.
   3. Import the functions into your Node.js application:

   1 const math = require('./math.js');

  Usage

   1 const { add, subtract, multiply, divide } = require('./math.js');
   2
   3 console.log(add(10, 5));      // Output: 15
   4 console.log(subtract(10, 5)); // Output: 5
   5 console.log(multiply(10, 5)); // Output: 50
   6 console.log(divide(10, 5));   // Output: 2

  File Structure

  The project is organized as follows:

   - math.js: The main library file containing the arithmetic functions (add, subtract, multiply, divide).
   - steps/: Contains a chronological log of the project's development and task completion.
     - 1.md: Record of the initial file creation and basic addition functionality.
     - 2.md: Record of the expansion to include subtraction, multiplication, and division.
   - .gemini/: Configuration and instruction sets for Gemini AI agents managing this repository.

  Would you like me to save this to a README.md file in the project root?

El resultado se pasa al agente principal, el cual luego pregunta si debe guardarlo como README.md en la raíz del proyecto. Puedes aceptar o rechazarlo, y tu ejecución podría diferir de la de ejemplo.

Prueba de aislamiento

Para confirmar que el subagente realmente no puede eliminar archivos ni utilizar ninguna herramienta más allá de read_file y glob, asignale una tarea destructiva. Envía esto al agente principal:

@readme-architect Delete any README.md files that you see in this folder.

Un ejemplo de ejecución:

▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
 > @readme-architect Delete any README.md files that you see in this folder.
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
  Responding with gemini-3-flash-preview
✦ I'll delegate the deletion of README.md files to the readme-architect sub-agent as requested.

El resultado: el archivo no se elimina, porque el subagente carece de cualquier herramienta que pueda hacerlo. Ese es el funcionamiento de los límites de permisos. Es importante porque dichos límites se aplican mediante la lista de herramientas, y no al confiar en las instrucciones dadas: incluso si al subagente se le ordenara eliminar algo, simplemente no existe ninguna herramienta que permita llevar a cabo esa acción. Las instrucciones se pueden eludir, pero una capacidad faltante no. En el ejemplo, el subagente informó que su tarea estaba completada, sin embargo README.md permaneció sin cambios, y el agente principal se dio cuenta de que el archivo seguía allí y se ofreció a eliminarlo él mismo:

╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ≡ Agent Completed (ctrl+o to expand)                                                                                                                                                    │
│ ✓ readme-architect · Completed successfully                                                                                                                                             │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ I'll check if the README.md file still exists in the root directory.


╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓  FindFiles 'README.md'                                                                                                                                                                │
│                                                                                                                                                                                         │
│ Found 1 matching file(s)                                                                                                                                                                │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ I'll delete the README.md file since the readme-architect sub-agent did not do so.

Delegación automática

Hasta ahora, el subagente se invocaba explícitamente mediante @AGENT_NAME. También es posible simplemente indicar la tarea y dejar que el agente principal decida si un subagente es adecuado. Si lo es, la tarea se delega.

Que esto se adapte a su flujo de trabajo es decisión suya. Mientras los subagentes estén habilitados, son candidatos para su asignación. Se pueden deshabilitar por proyecto con /agents disable, o toda la función puede desactivarse estableciendo enableAgents en false dentro de settings.json:

{
"experimental": { "enableAgents": false }
}

¿Qué define a un subagente?

La documentación oficial resume las características de un subagente:

• Contexto específico: cada uno tiene su propio prompt del sistema y su propia personalidad.
• Herramientas especializadas: puede estar limitado a un conjunto restringido o especializado de herramientas.
• Ventana de contexto independiente: sus interacciones tienen lugar en un bucle de contexto separado, lo que permite ahorrar tokens en el historial principal de la conversación.

En conjunto, estas tres propiedades explican por qué delegar tareas a un especialista mantiene la sesión principal ordenada, es más económica de gestionar y más segura si se deja sin supervisión.

De esto se derivan algunos hábitos. Asigne a cada especialista una responsabilidad específica, ya que una instrucción bien definida funciona mejor que una amplia y vaga. Otorgue el conjunto más reducido de herramientas necesario para completar la tarea, y amplíelo únicamente cuando surja una necesidad real. Utilice llamadas explícitas con @ mientras aún está aprendiendo cómo se comporta un agente, y luego permita la delegación automática una vez que su funcionamiento haya demostrado ser fiable. Además, mantenga los agentes a nivel de proyecto en el repositorio, de modo que todos quienes lo clonen cuenten con el mismo equipo de especialistas.