¿Qué es un subagente y cómo se usa en agentes de código?

Un subagente trabaja en un contexto aparte y te devuelve el resultado

Cuando le das una tarea grande a un agente de programación, hay dos caminos: la conversación principal lo hace todo ella misma, o le pasa una parte del trabajo a un subagente (subagent). El subagente hace esa parte en su propio contexto; los archivos que lee y los tests que ejecuta no llenan la conversación principal.

La documentación de Cursor lo dice en dos frases: «Intermediate output stays in the subagent. The parent only sees the final summary.» A 18 de octubre de 2026, hay subagentes en cinco herramientas: Claude Code, Codex de OpenAI, Cursor, Gemini CLI de Google y GitHub Copilot. Claude Code, Cursor y Copilot hablan de la ventana de contexto propia del subagente; Gemini CLI habla de un bucle de contexto aparte, y Codex lanza los agentes en paralelo y reúne sus resultados en una sola respuesta.

Por eso compensa en dos tipos de trabajo: los que generan mucha salida (ejecutar tests, revisar logs, leer decenas de archivos) y las investigaciones independientes entre sí. Los ejemplos salen del repositorio en el que desarrollamos diffox y que usamos a diario; allí trabajamos con Claude Code.

El subagente no ve tu conversación, así que la tarea tiene que entenderse sola

El error más común con un subagente es dar por hecho que sabe lo que se habló en la conversación principal. Según la documentación de Claude Code, el subagente empieza con una ventana de contexto nueva: no ve el historial de tu conversación, ni las skills que ya se llamaron, ni los archivos que Claude ya leyó. Al empezar, tiene esto:

Por eso, el texto de la tarea tiene que decir por sí solo el objetivo, qué archivos puede tocar y qué tiene que informar. Lo que en la conversación principal llamaste «ese error» no existe para el subagente: escribe la ruta del archivo, el mensaje de error y la salida que esperas. La documentación de Cursor dice lo mismo: los subagentes empiezan con un contexto limpio y no tienen acceso al historial anterior de la conversación. La documentación de Codex, Gemini CLI y Copilot no lo dice; trabajes con la herramienta que trabajes, lo seguro es escribir la tarea de forma que se entienda sola. La documentación de Codex, por su parte, recomienda además pedirle al subagente un resumen en lugar de la salida intermedia.

Dónde se definen los subagentes, quién decide delegar y cuáles vienen incluidos

En las cinco, un subagente se define con un archivo, a nivel de proyecto o de usuario. Donde de verdad se diferencian es en si el agente principal delega el trabajo por su cuenta:

Fuente: la documentación de subagentes de cada herramienta, 18 de octubre de 2026. En Codex, la definición es un archivo TOML; en las demás, un archivo Markdown con cabecera YAML. El agente de navegador de Gemini CLI viene desactivado por defecto. La lista de agentes incluidos de Copilot cambia de una página a otra: la página de referencia cuenta siete y la guía práctica, cuatro.

La diferencia está en la tercera columna. En Codex depende del nivel de effort: la página de modelos dice que el nivel más alto, Ultra, hace el trabajo repartiéndolo entre subagentes; la página de subagentes, en cambio, dice que el Codex local lanza un subagente ante una petición directa, como «lanza dos agentes», o por una indicación en AGENTS.md o en una skill. En las otras cuatro, el agente principal también puede delegar por su cuenta; la documentación de Copilot añade que el modelo puede no delegar y hacer el trabajo él mismo.

Las definiciones pasan de una herramienta a otra: Cursor también lee las carpetas .claude/agents/ y .codex/agents/ (si hay dos con el mismo nombre, gana .cursor/), y Copilot CLI también lee .claude/agents/. Así que un archivo que escribas en .claude/agents/ lo leen Claude Code, Cursor y Copilot CLI; lo que la documentación no garantiza es que los campos del frontmatter funcionen igual en las tres.

El 18 de junio de 2026, Google dejó de dar servicio en Gemini CLI a los usuarios gratuitos y a los suscriptores de Google AI Pro y Ultra, y los dirigió a Antigravity CLI; con una clave de API de pago o una licencia de empresa puedes seguir usando Gemini CLI. El 28 de octubre de 2026 leímos la documentación de subagentes de Antigravity. Los subagentes se definen en .agents/agents/ para un proyecto y en ~/.gemini/config/agents/ para el usuario. El agente principal le pasa una tarea a un subagente según su descripción; vienen incluidos tres agentes: research, browser y self. Un subagente no recibe el historial de conversación del agente principal y empieza con un contexto limpio; si su definición no indica modelo, usa el del agente principal. Se pueden anidar hasta 10 niveles.

Un buen subagente tiene una tarea acotada, pocas herramientas y un informe corto

El archivo de definición fija tres cosas: cuándo se llama al subagente (la descripción), a qué tiene acceso (las herramientas) y qué devuelve (el prompt). En Claude Code tiene este aspecto; los campos obligatorios son name y description:

---
name: test-runner
description: Ejecuta los tests e informa solo de los que fallan
tools: Read, Grep, Glob, Bash
model: haiku
---

Ejecuta la batería de tests. Informa solo de los tests que fallan, cada
uno con su mensaje de error. No edites ningún archivo.

• La descripción es un disparador. Claude Code y Gemini CLI delegan según la descripción. Escribe en ella cuándo hay que llamar al agente, no qué es.
• Limita las herramientas. En Claude Code, el campo tools restringe las herramientas que puede usar el subagente; si no lo pones, hereda todas las herramientas disponibles para los subagentes. No le des una herramienta de escritura a un agente que solo va a leer.
• Los permisos vienen del agente principal. En Codex, el subagente hereda los permisos, el proveedor y los servidores MCP del agente principal; el archivo de definición no puede cambiarlos. El sandbox y el ajuste de aprobaciones también son los del agente principal.
• Pide un informe corto. Que la última frase del prompt diga qué hay que devolver: los tests que fallan, los archivos encontrados, una decisión. Si una salida intermedia larga vuelve a la conversación principal, se pierde lo que se ganaba con el subagente.
• Puedes desactivar el uso automático. En el agente en la nube de Copilot, un agente con disable-model-invocation: true solo se ejecuta cuando se elige a mano. En Copilot, el prompt de un agente personalizado puede tener como máximo 30.000 caracteres.

El modelo, la concurrencia y el anidamiento dependen de la herramienta

Si no pones un modelo en la definición, según la documentación el subagente usa el modelo del agente principal en Claude Code, Codex, Cursor y Copilot. La página de subagentes de Gemini CLI dice lo mismo, pero la página de modelos de esa misma documentación dice que el comando /model y la opción --model no cambian el modelo de los subagentes; las dos páginas no encajan del todo. Lo que sí cambia según la herramienta es cuántos subagentes pueden ejecutarse a la vez y si un subagente puede lanzar otro:

Fuente: la documentación de subagentes de cada herramienta, 18 de octubre de 2026. «La documentación no lo dice»: en las páginas que leímos ese día no encontramos ninguna frase con este dato. La página de referencia de Copilot CLI da una profundidad de 4 en la sección de variables de entorno y de 6 en la tabla de límites. Gemini CLI limita por defecto cada subagente a 30 turnos y 10 minutos.

Claude Code busca el modelo en cuatro sitios, por este orden: el parámetro model de esa llamada, el campo model de la definición, la variable de entorno CLAUDE_CODE_SUBAGENT_MODEL y, por último, el modelo de la conversación principal. También está escrito qué pasa al llegar al límite: con 20 subagentes en marcha no se puede lanzar otro, y el error le dice a Claude que no vuelva a intentarlo. Gemini CLI no permite las llamadas anidadas, para evitar bucles infinitos y un gasto excesivo de tokens.

En la mayoría de las herramientas, el effort no cambia el número de subagentes

Las cinco herramientas tienen un ajuste que decide cuánto piensa el modelo antes de llegar a una respuesta: el effort, o nivel de razonamiento. Su relación con los subagentes se resume en dos preguntas: ¿hereda el subagente el nivel del agente principal? ¿Puede elegir el suyo?

Fuente: la documentación de modelos y de subagentes de cada herramienta, 18 de octubre de 2026. En Cursor, los nombres de los niveles cambian según el modelo.

La documentación de Claude Code, Cursor, Gemini CLI y Copilot no relaciona el effort con el número de subagentes. La de Claude Code describe así la diferencia que vio en los niveles altos: «tested more edge cases and verified more of its work before answering. It also made more choices on its own.» No menciona el número de subagentes. En Copilot, los subagentes en paralelo no dependen del effort, sino de un modo aparte: con el comando /fleet, el agente principal decide por sí mismo si puede dividir el trabajo en partes.

La excepción es el nivel más alto de Codex, ultra. La página de modelos usa la misma frase para la CLI, la aplicación y el IDE: «Ultra mode goes beyond a single-agent run. It uses subagents to accelerate complex work.» En ChatGPT Work, Ultra también activa la delegación automática del trabajo adecuado a subagentes. En los demás niveles, según la página de subagentes, el Codex local lanza un subagente cuando se lo pides o cuando lo indica AGENTS.md o una skill.

Ultracode, el ajuste de Claude Code que reparte el trabajo entre decenas de subagentes

En el control deslizante /effort de Claude Code, junto a los niveles de effort, hay también un interruptor de ultracode. La documentación no lo define como un nivel, sino como un ajuste aparte: «a Claude Code setting rather than a model effort level». Cuando está activado, Claude planifica un flujo de trabajo dinámico para cada tarea sustancial, sin que se lo pidas: escribe un script que divide el trabajo y dirige a los subagentes, y un entorno de ejecución lo lleva a cabo en segundo plano; mientras tanto, tu sesión sigue respondiendo.

Hay cuatro formas de activarlo:

• Para una sola tarea: escribe la palabra ultracode en tu prompt; el nivel de effort de la sesión no cambia. La palabra solo cuenta en el prompt que escribes tú.
• Para toda la sesión: /effort ultracode o el interruptor del control deslizante.
• Al arrancar: claude --effort ultracode; esto también pone el nivel de effort en xhigh.
• En todas las sesiones: "ultracode": true en el archivo de configuración.

La documentación dice claramente lo que cuesta: cada petición gasta más tokens y tarda más, y con una suscripción llegas antes al límite de la sesión o al semanal. Con ultracode activado no se aplica el límite de 20 subagentes; el flujo de trabajo tiene sus propios límites: por defecto, 16 agentes a la vez y como máximo 1.000 agentes por ejecución. Con ultracode desactivado, más de 25 agentes o una estimación de 1,5 millones de tokens hacen aparecer el aviso «Large workflow»; con ultracode activado, tampoco se muestra ese aviso.

Los flujos de trabajo dinámicos llegaron a finales de mayo de 2026, y el resumen semanal los anunció como «research preview»; el 18 de octubre de 2026, la página de flujos de trabajo no llevaba ninguna etiqueta de estado. No los confundas con dos cosas de nombre parecido: ultrathink solo pide pensar más a fondo en ese turno y no cambia el nivel de effort; /code-review ultra es un comando aparte que ejecuta agentes de revisión en la nube, y Claude no lo lanza por su cuenta.

¿Pueden hablar entre sí los subagentes? Depende de la herramienta

En las cinco, el resultado del subagente vuelve a quien lo llamó. Las herramientas se diferencian en tres preguntas: ¿pueden los subagentes escribirse entre sí?, ¿puede el agente principal escribir más tarde a un subagente en marcha o ya terminado?, ¿hay una función de equipos?

Fuente: la documentación de cada herramienta, 18 de octubre de 2026. En Copilot, para escribir a los agentes hermanos tiene que estar activada la comunicación compartida entre hermanos; la documentación no dice cómo se activa.

La función agent teams de Claude Code es la versión más avanzada de esto: una sesión es la líder del equipo, los miembros son sesiones aparte, cada uno trabaja en su propia ventana de contexto y se escriben por su nombre. No se puede escribir a todos a la vez; a cada destinatario le llega un mensaje aparte. El criterio de la propia documentación: «Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.» Los agent teams son experimentales, vienen desactivados por defecto y gastan más tokens, porque cada miembro es una instancia aparte de Claude.

Que puedan escribirse no significa que tengas que depender de ello. Lo más sólido sigue siendo dividir el trabajo en partes independientes y unir los resultados en el agente principal. La documentación de fleet de Copilot dice lo mismo: la coordinación se basa en un estado explícito, no en una memoria compartida implícita, y los subagentes no guardan estado entre llamadas; dale a cada uno el contexto completo.

Los agentes en paralelo trabajan sin riesgo con worktrees y archivos separados

Los subagentes que solo leen pueden trabajar uno al lado del otro en el mismo directorio. El problema empieza cuando varios agentes editan archivos y hacen commit: comparten el mismo directorio, la misma rama y el mismo index de git. Es un problema de git que no depende de la herramienta que uses. En nuestro repositorio tenemos cuatro reglas para esto.

Un worktree aparte. En Claude Code, si pones isolation: worktree en la definición, al subagente se le abre un worktree temporal, es decir, un directorio de trabajo aparte del repositorio; si el subagente termina sin hacer cambios, se borra solo. Según la documentación, por defecto ese worktree no sale de la rama en la que trabajas, sino de la rama por defecto del repositorio.

Archivos separados. Nuestra regla para los agentes que comparten directorio: cada commit se hace con sus propias rutas (git commit --only <rutas>), porque un git commit a secas se lleva todo el index, incluido el trabajo que preparó otro agente. Al repartir el trabajo, dale a cada agente un conjunto de archivos distinto.

Una tarea que se entienda sola. En Claude Code y en Cursor, el subagente no ve el historial de tu conversación; el texto de la tarea tiene que decir por sí solo el objetivo, qué archivos puede tocar y qué tiene que informar. Los hooks del archivo de configuración, en cambio, le llegan solos: en Claude Code, el hook PreToolUse también se ejecuta antes de las llamadas a herramientas del subagente.

Limpieza. Un worktree con cambios se queda en el disco. El 27 de agosto de 2026 se habían acumulado 41 worktrees en nuestro repositorio, 37 de ellos de una sola ronda de revisión. Como el desorden no lo crean las personas, sino los flujos de trabajo, la solución se puso ahí: cada sesión empieza con un script que borra las ramas de los pull requests ya fusionados y los worktrees de trabajos ya terminados.

No todo trabajo necesita un subagente

Un subagente le ahorra contexto a la conversación principal, pero monta el suyo desde cero; además, escribir la tarea y leer el resultado también cuesta. La documentación de Claude Code recomienda la conversación principal en estos casos:

• Si hace falta mucho ir y venir. Vas a pulir el trabajo junto con el agente, paso a paso.
• Si las fases comparten el mismo contexto. La planificación, la implementación y los tests se apoyan en la misma información.
• Si el cambio es pequeño y concreto. Unas pocas líneas en un archivo.
• Si importa la velocidad. El subagente empieza de cero, y reunir el contexto lleva tiempo.

Un subagente encaja en trabajos que responden por sí solos a una sola pregunta: «ejecuta los tests y tráeme los que fallan», «¿quién llama a este módulo?», «compara estas tres bibliotecas». La revisión de diffox se basa en esta misma idea: divide la revisión de código con IA entre agentes especializados, y cada uno mira el cambio con su propia pregunta. Cómo se eligen lo contamos en nuestro artículo sobre la arquitectura.