Objetivo del tema
Comprender qué son los subagentes en Qwen Code, cómo se configuran, qué ventajas aportan frente al uso de un único agente generalista y cómo se pueden usar para delegar trabajo especializado dentro de un proyecto.
Este tema se apoya en la documentación oficial disponible al 11 de abril de 2026, especialmente en Subagents dentro de Qwen Code Docs y en la referencia del tool task para comprender cómo Qwen Code delega trabajo especializado.
La documentación oficial define a los subagentes como asistentes especializados que manejan tipos concretos de tareas dentro de Qwen Code. En vez de pedirle todo al agente principal, podés delegar trabajos puntuales en agentes configurados con su propio enfoque, su propio prompt y, opcionalmente, sus propias herramientas.
La idea central es muy poderosa: un agente principal puede seguir siendo generalista, pero subdelegar ciertos tipos de trabajo en agentes especialmente preparados para testing, documentación, refactoring, seguridad, revisión de código o tecnologías concretas.
Los subagentes no reemplazan al agente principal. Lo complementan, permitiendo especialización, aislamiento de contexto y reutilización de experiencia.
La documentación oficial enumera varios beneficios de los subagentes. En términos prácticos, los más importantes son estos:
Estas ventajas hacen que los subagentes resulten especialmente interesantes cuando el trabajo empieza a dividirse naturalmente en especialidades.
La documentación resume el flujo de subagentes en cuatro etapas:
Esta arquitectura es interesante porque combina dos cosas que normalmente compiten entre sí:
Qwen Code puede delegar de dos maneras. La primera es automática: el agente principal interpreta tu pedido, compara ese pedido con las descripciones de los subagentes disponibles y deriva la tarea al que mejor encaja. La segunda es explícita: vos mismo pedís que intervenga un subagente concreto.
La documentación oficial indica que la delegación automática se apoya sobre todo en tres señales:
description de cada subagenteTambién muestra que se puede solicitar un subagente en forma directa. En castellano, ejemplos razonables serían estos:
haz que el subagente testing-expert cree pruebas unitarias para el módulo de pagos
usa el subagente documentation-writer para actualizar la referencia de la API
pedile al subagente react-specialist que optimice el rendimiento de este componente
Esto conviene remarcarlo porque evita una confusión frecuente: los subagentes no son solo una automatización interna. También pueden formar parte de un flujo de trabajo deliberado, donde el usuario decide qué especialista quiere activar.
Como en el curso ya vimos skills y comandos personalizados, conviene dejar clara la diferencia.
| Mecanismo | Para qué sirve | Quién lo activa |
|---|---|---|
| Subagente | Delegar trabajo especializado a otro agente. | El agente principal o el flujo configurado. |
| Skill | Aportar conocimiento o instrucciones especializadas. | El modelo, automáticamente. |
| Custom command | Crear atajos reutilizables para prompts o acciones frecuentes. | El usuario, explícitamente. |
Una forma simple de recordarlo es esta:
La documentación oficial indica un camino guiado muy simple para crear el primer subagente:
/agents create
Este comando abre un asistente que permite definir los datos principales del agente especializado. También existe un comando de administración para ver los subagentes ya disponibles:
/agents manage
Esto es importante porque muestra que Qwen Code no trata a los subagentes como una función oculta o exclusivamente técnica. Están integrados directamente en la experiencia del CLI.
La documentación indica que los subagentes pueden provenir de varias capas de configuración:
| Tipo | Ruta | Prioridad |
|---|---|---|
| Proyecto | .qwen/agents/ |
Alta |
| Usuario | ~/.qwen/agents/ |
Baja |
| Extensión | .qwen/extensions/<extension>/agents/ |
Depende de la extensión |
La documentación aclara que los subagentes de proyecto tienen precedencia sobre los de usuario. Eso permite que un repositorio defina agentes propios del dominio sin depender de la configuración personal de cada desarrollador. Además, las extensiones activas también pueden aportar subagentes listos para usar.
Este punto es importante porque amplía bastante el alcance del sistema. Qwen Code puede descubrir subagentes definidos por extensiones habilitadas. Esos agentes aparecen en /agents manage bajo la sección de agentes de extensión y siguen el mismo formato general que los agentes personales o de proyecto.
La consecuencia práctica es muy clara: un equipo puede instalar una extensión que ya venga con especialistas para un dominio concreto, por ejemplo despliegue en la nube, documentación interna, pipelines o revisión de infraestructura.
Al igual que las skills, los subagentes se configuran como archivos Markdown con YAML frontmatter. La documentación da una estructura básica como esta:
---
name: agent-name
description: descripción breve de cuándo y cómo usar este agente
tools:
- tool1
- tool2
- tool3
---
Aquí va el prompt del sistema.
Puede tener varios párrafos.
También puede usar variables como ${project_name} o ${timestamp}.
Esto significa que cada subagente define al menos tres cosas esenciales:
Opcionalmente también puede restringir o enumerar herramientas, lo que vuelve al subagente más controlado y más seguro. El uso de variables templadas es útil para inyectar contexto dinámico sin reescribir el agente cada vez.
La descripción no es un adorno. La documentación insiste en que debe explicar cuándo usar el subagente y qué tipo de trabajo realiza. Eso le da al agente principal una señal para decidir si conviene delegar una tarea hacia ese especialista.
Ejemplo débil:
description: Helps with coding
Ejemplo mejor:
description: Writes and improves automated tests for JavaScript and TypeScript projects. Use when you need unit, integration or regression tests.
La diferencia es la misma que en skills: cuanto más específica es la descripción, mejor puede actuar el sistema.
La documentación oficial muestra ejemplos de agentes como documentation writer, testing specialist o code reviewer. Adaptando esa lógica, un ejemplo razonable sería:
---
name: testing-expert
description: Crea y mejora pruebas automatizadas para módulos de backend. Úsalo cuando se necesiten tests unitarios, de integración o regresión.
tools: read_file, edit, shell_command
---
Eres un especialista en testing.
Tu responsabilidad es proponer y crear pruebas automatizadas claras,
mantener cobertura útil y evitar cambios innecesarios fuera del alcance.
Este ejemplo muestra muy bien la lógica del formato:
La documentación enumera varias familias de subagentes especialmente útiles. Entre los ejemplos más naturales están:
En la práctica, esto se traduce en escenarios como:
La documentación sugiere dos grandes maneras de diseñar subagentes:
Ambos enfoques son válidos. Lo importante es no mezclar demasiadas responsabilidades en el mismo agente, porque cuanto más amplio es el alcance, menos útil resulta la especialización.
El mejor subagente no es el más “inteligente”, sino el más claro en su responsabilidad.
La documentación oficial enumera varias buenas prácticas de diseño. Entre las más importantes:
Estas reglas son muy parecidas a las de skills, pero en subagentes importan todavía más, porque lo que está en juego no es solo conocimiento, sino ejecución delegada.
La documentación remarca que los subagentes pueden configurarse con acceso controlado a herramientas. Esto es importante por dos razones:
Por ejemplo:
Esto vuelve a los subagentes una pieza importante también desde el punto de vista de la seguridad operativa.
Uno de los puntos más interesantes de la documentación es que los subagentes mantienen historial separado respecto de la conversación principal. Eso significa que el trabajo especializado no arrastra todo su detalle al chat principal, aunque sí devuelve un resumen de resultados.
Este aislamiento de contexto tiene ventajas muy concretas:
La documentación también menciona visibilidad de progreso y estadísticas de ejecución, lo que ayuda a seguir el trabajo sin perder control.
En la referencia del tool task aparece además un matiz muy importante: cuando un subagente se ejecuta como tarea delegada, su ejecución es sin estado y de un solo uso. Es decir, recibe un prompt completo, realiza el trabajo, devuelve un resultado final y termina.
Esto conviene entenderlo bien. Un subagente no funciona como un segundo chat permanente que queda abierto al costado. Opera más bien como un especialista temporal que entra, ejecuta una misión concreta y luego entrega su informe al agente principal.
taskLa documentación para desarrolladores explica que el tool task es la pieza que permite lanzar subagentes especializados para trabajos complejos y, cuando hace falta, en paralelo. Esto es útil cuando hay tareas independientes que no necesitan esperar una a la otra.
task(
description="Revisión de código",
prompt="Revisa los cambios recientes en el módulo de usuarios y detecta problemas de calidad o seguridad.",
subagent_type="code-reviewer"
)
task(
description="Ejecución de pruebas",
prompt="Ejecuta la suite de pruebas y resume los fallos encontrados.",
subagent_type="test-runner"
)
No hace falta que el alumno memorize esta sintaxis de inmediato. Lo importante en este punto es comprender la arquitectura: los subagentes no solo especializan trabajo, también permiten repartirlo.
Para administración práctica, la documentación destaca estos comandos:
/agents create
/agents manage
/agents create abre un asistente guiado para construir un nuevo subagente. /agents manage permite listar y gestionar los ya existentes. Esto hace que la función sea accesible también para usuarios que no quieran editar archivos Markdown a mano desde el principio.
Los errores más comunes suelen estar relacionados con diseño demasiado amplio, metadatos débiles o expectativas equivocadas sobre automatización.
| Problema | Causa probable | Primer paso razonable |
|---|---|---|
| El subagente no se usa nunca | Descripción demasiado vaga o especialización poco distinguible. | Reescribir la descripción con un foco más concreto. |
| El subagente intenta hacer demasiado | Su prompt mezcla varias responsabilidades. | Separar en dos agentes más acotados. |
| El agente especializado ejecuta más de la cuenta | Acceso a herramientas demasiado amplio. | Reducir el conjunto de tools disponibles. |
| La configuración de proyecto no se aplica | El archivo está en la carpeta equivocada o hay otra definición que toma precedencia. | Verificar `.qwen/agents/` y `~/.qwen/agents/`. |
| Se espera una conversación continua con el especialista | Se entendió mal el modelo de ejecución del subagente. | Recordar que en el flujo task el subagente ejecuta, responde y termina. |
Los subagentes permiten convertir a Qwen Code en un sistema más modular y especializado. En lugar de concentrar todo en un único agente generalista, podés delegar partes del trabajo en asistentes configurados con responsabilidad, contexto y herramientas específicas.
En este tema vimos las ideas centrales:
Con esta base, el siguiente paso natural es estudiar los servidores MCP y las herramientas externas, que permiten ampliar todavía más el alcance operativo del agente.