Qué es un Agente y un Subagente en IA (con ejemplos reales)

Llevas dos horas trabajando con tu agente de IA en el mismo proyecto. Le pediste que investigara cómo está armado el sistema de autenticación, después que revisara treinta archivos buscando un bug, y ahora, cuando le pides algo simple, empieza a responder raro. Se le "olvidan" cosas que le dijiste al principio. Repite pasos que ya habían quedado resueltos.

No es que el modelo se haya vuelto menos capaz. Es que su ventana de contexto —todo lo que puede "tener en la cabeza" en ese momento— se llenó de ruido: los treinta archivos que leyó, las ramas muertas que exploró, los intentos fallidos.

Para esto existen los agentes y subagentes.

Qué es un agente

Un agente es, en el sentido más simple, con quien hablas: la instancia de IA que recibe tu mensaje, decide qué hacer, y puede usar herramientas (leer archivos, correr comandos, buscar en internet) para resolver lo que le pediste. Cuando abres Claude Code o OpenCode y escribes algo, estás hablando con un agente principal.

Ese agente principal tiene una particularidad importante: puede delegar. En vez de hacer todo él mismo, puede invocar a otra instancia — separada, con su propio espacio de trabajo — para que resuelva una parte específica de la tarea y le devuelva solo el resultado. A esa instancia delegada se le llama subagente.

Qué es un subagente

Un subagente es una instancia aparte del mismo modelo, con tres cosas propias:

• Su propia ventana de contexto — no ve nada de lo que hablaste con el agente principal.
• Sus propias herramientas permitidas — puede tener acceso solo a lectura, o a lectura y escritura, según cómo lo configures.
• Su propio system prompt — instrucciones específicas para la tarea que va a resolver.

Cuando el subagente termina, no te muestra todo lo que hizo paso a paso. Te devuelve un resumen — el resultado final — y todo el proceso intermedio (los archivos que leyó, los intentos que descartó) se queda aislado en su propio contexto, sin ensuciar tu conversación principal.

El problema real que resuelven: el contexto se ensucia

Cuando le pides al agente que busque algo en el código, tiene que leer archivo tras archivo. Cada uno de esos archivos se queda en el contexto de la conversación — aunque el 90% de lo que leyó no tenía nada que ver con lo que buscabas.

Un subagente resuelve esto así: explora en su propia ventana, a veces leyendo decenas de miles de tokens, y al terminar solo devuelve un resumen condensado — normalmente entre 1,000 y 2,000 tokens — con lo que realmente importa. Todo el ruido de la búsqueda se queda aislado ahí, nunca llega a tu conversación principal.

Es la diferencia entre pedirle a alguien "investiga esto y contame lo importante" (subagente) versus tenerlo narrándote en voz alta cada archivo que abre mientras busca (agente principal sin ayuda).

Cómo se ve un subagente por dentro

Un subagente es un archivo Markdown con frontmatter YAML. En Claude Code vive en .claude/agents/ (para el proyecto) o ~/.claude/agents/ (para todos tus proyectos). El frontmatter define su configuración; el cuerpo del archivo es su system prompt.

Plantilla para copiar — revisor de código

---
name: code-reviewer
description: Revisa el código en busca de calidad, seguridad y mantenibilidad. Úsalo justo después de escribir o modificar código.
tools: Read, Grep, Glob, Bash
model: inherit
---
Eres un revisor de código senior que garantiza altos estándares de calidad y seguridad.

Cuando te invoquen:
1. Corre `git diff` para ver los cambios recientes.
2. Concéntrate en los archivos modificados, no en todo el repositorio.
3. Empieza la revisión de inmediato, sin pedir contexto adicional.

Prioriza en este orden: errores de seguridad, bugs funcionales, luego legibilidad.

Nota algo clave en el campo tools: este subagente solo puede leer y buscar, no editar. No puede "corregir" lo que encuentra — solo reportarlo. Eso es intencional: un revisor que puede modificar el código mientras lo revisa es un revisor con conflicto de interés.

Plantilla para copiar — debugger (con permiso de escritura)

Compara el ejemplo anterior con este. Acá la tarea sí requiere modificar archivos, así que el subagente sí recibe Edit:

---
name: debugger
description: Investiga errores y fallos de tests, encuentra la causa raíz y aplica la corrección mínima necesaria. Úsalo cuando aparezca un error o un test empiece a fallar.
tools: Read, Grep, Glob, Bash, Edit
model: inherit
---
Eres un especialista en debugging. Sigue este proceso en orden:

1. Reproduce el error corriendo el comando o test que falla.
2. Lee el stack trace completo antes de asumir nada.
3. Busca en el código la línea exacta donde se origina el problema (no donde se manifiesta el síntoma).
4. Aplica la corrección más pequeña posible que resuelva la causa raíz.
5. Vuelve a correr el test o comando para confirmar que ahora pasa.

No reescribas código que no esté relacionado con el error, aunque veas oportunidades de mejora — repórtalas al final como sugerencia, no las apliques.

La diferencia de tools entre estos dos subagentes no es un detalle menor: es la forma de controlar qué puede y qué no puede hacer cada uno, sin tener que confiar en que "se va a comportar bien".

Plantilla para copiar — auditor de contratos (no técnico)

Los subagentes no son solo para código. Este ejemplo aísla una tarea de lectura pesada — igual que harías con treinta archivos de código, pero con un documento largo:

---
name: auditor-contratos
description: Revisa contratos largos y extrae solo las cláusulas de riesgo. Úsalo cuando el usuario comparta un contrato de más de 5 páginas.
tools: Read
model: inherit
---
Lee el contrato completo y devuelve exclusivamente:
1. Una lista priorizada de cláusulas de riesgo (la más importante primero).
2. Para cada una: qué dice, por qué es riesgosa, y una sugerencia de qué preguntar antes de firmar.

No resumas el contrato completo ni cites secciones que no sean de riesgo — el objetivo es que el usuario reciba solo lo que necesita decidir, no las 40 páginas completas en su conversación.

Nota lo que pasa acá: el subagente puede leer un documento entero de 40 páginas en su propio contexto, y a tu conversación principal solo llega la lista de riesgos. Las 40 páginas nunca la contaminan.

Cómo se activa

Hay dos caminos:

• Automático: el agente principal lee la description de cada subagente disponible y decide delegar cuando la tarea calza. Por eso conviene escribir descriptions específicas — "úsalo cuando..." — en vez de vagas.
• Explícito: le pides directamente, mencionando el nombre — "usa el subagente code-reviewer para revisar esto" — o con @nombre-del-subagente.

En ambos casos, el subagente arranca con contexto limpio. No ve tu conversación anterior ni los archivos que el agente principal ya leyó. Todo lo que necesita tiene que ir explícito en el prompt de delegación — igual que cuando delegas una tarea a alguien nuevo en un equipo: si no le das el contexto, no lo tiene.

Subagentes en paralelo (ejemplo con números reales)

Imagina que terminaste de escribir una función de checkout para una tienda online y quieres una revisión completa antes de hacer merge. En vez de pedirle todo a un solo agente uno-por-uno, lanzas tres subagentes al mismo tiempo, cada uno con una sola responsabilidad:

Subagente	Tools	Qué revisa	Qué devuelve
style-checker	Read, Grep	Convenciones de nombres, formato, imports sin usar	Lista de líneas a corregir
security-scanner	Read, Grep, Bash	Inyección SQL, secretos hardcodeados, validación de inputs	Lista de vulnerabilidades por severidad
test-coverage	Read, Bash	Corre la suite de tests y mide qué porcentaje del nuevo código quedó cubierto	Porcentaje de cobertura + funciones sin testear

Los tres corren a la vez, cada uno en su propio contexto, sin pisarse entre sí. Si el más lento tarda 40 segundos, tu revisión completa tarda 40 segundos — no la suma de los tres.

Lo que no hacen estos tres subagentes es invocar a otros subagentes por su cuenta — para evitar que uno dispare diez, esos diez disparen cien, y el sistema se salga de control. Esa es la regla por defecto tanto en Claude Code como en OpenCode (donde se controla explícitamente con el parámetro subagent_depth, que por defecto vale 1: los agentes principales pueden lanzar subagentes, pero esos subagentes no pueden lanzar más).

Implementación en OpenCode

OpenCode usa una terminología parecida pero con sus propios nombres: primary agents (con los que hablas directo, cambias entre ellos con la tecla Tab) y subagents (los que un agente principal invoca). El campo que lo define en el frontmatter es mode.

Plantilla para copiar — OpenCode

---
description: Revisa código buscando buenas prácticas y errores potenciales
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
permission:
  edit: deny
  bash: deny
---
Estás en modo revisión de código. Enfócate en:
- Calidad del código y buenas prácticas
- Bugs potenciales y casos borde
- Legibilidad y mantenibilidad

No modifiques archivos — solo reporta lo que encuentres.

Se guarda en .opencode/agents/ (proyecto) o ~/.config/opencode/agents/ (global). Diferencias clave frente a Claude Code:

• OpenCode reemplazó el campo tools por permisos por patrón (allow/ask/deny), con más granularidad: puedes permitir lectura pero pedir confirmación antes de correr comandos de bash, por ejemplo.
• Si no defines un modelo, el subagente hereda el del agente principal que lo invocó.
• Trae subagentes ya listos para usar sin configurar nada: General (investigación y tareas de varios pasos), Explore (solo lectura, para recorrer el código) y Scout (solo lectura, para investigar documentación externa y dependencias).

Un detalle importante si vienes de Claude Code: los subagentes de .claude/agents/ no se leen automáticamente en OpenCode. Si armaste subagentes para Claude Code y quieres usarlos en OpenCode, hay que migrarlos a mano (cambiar tools por permission, agregar mode, especificar el modelo).

Cuándo delegar y cuándo no

No todo debería convertirse en un subagente. Esta es la señal más simple: si la tarea genera mucho ruido que no necesitas ver (leer muchos archivos, explorar código, investigar un documento largo), delega. Si es un intercambio rápido de ida y vuelta, o el siguiente paso depende exactamente del resultado del paso anterior, resuélvelo en la conversación principal — delegar ahí solo agrega demora sin beneficio real.

Hay un caso particular donde delegar de más sale caro: cuando varios subagentes tienen que escribir sobre lo mismo. Dos subagentes editando el mismo archivo al mismo tiempo generan conflictos, igual que dos personas escribiendo la misma hoja de cálculo a la vez sin coordinarse. Para lectura e investigación, paralelizar en subagentes funciona muy bien. Para escritura de código que depende de decisiones compartidas, suele ser más confiable mantener todo en un solo hilo.

Lo que no debes hacer

• No armes un subagente para cada micro-tarea. Si tienes veinte subagentes con descriptions parecidas, el agente principal empieza a dudar cuál usar y la delegación automática se vuelve poco confiable. Un puñado de subagentes bien definidos funciona mejor que un ejército de especialistas casi idénticos.
• No asumas que el subagente "sabe" lo que ya hablaste. Arranca en blanco. Si necesita un dato de la conversación, tiene que ir explícito en el prompt que lo invoca.
• No delegues algo que necesitas revisar paso a paso. Si te interesa ver el razonamiento completo, no solo el resultado, quédate en el hilo principal.