¿Qué son los subagentes en Claude Code? Lo que necesitas saber

Subagentes (a menudo escritos subagentes or subagentes) son uno de los avances prácticos más claros en herramientas de desarrollo de agentes: permiten componer un pequeño equipo de asistentes de IA especializados dentro Código de ClaudeCada uno con su propia función, herramientas y ventana de contexto. La idea es simple pero eficaz: en lugar de pedirle a un modelo generalista que lo haga todo, se definen agentes compactos y de propósito único a los que el orquestador principal delega el trabajo (ya sea automáticamente o cuando se les solicita explícitamente). Esto cambia la forma en que se gestiona el contexto, las herramientas y la relación coste/latencia de los flujos de trabajo complejos.

¿Qué son los subagentes?

Definición corta. Un subagente es una "personalidad" de IA preconfigurada y especializada en tareas, a la que Claude Code puede delegar una tarea. Cada subagente tiene su propio indicador de sistema, su propia ventana de contexto (aislada), herramientas explícitamente asignadas y, opcionalmente, una selección de modelos. Los subagentes pueden crearse a nivel de proyecto o de usuario e invocarse automáticamente por Claude o explícitamente por el usuario.

Propiedades clave de un subagente

Propósito especializado y aviso del sistema. Describe el rol, las restricciones y el enfoque del subagente en su mensaje del sistema para que se comporte de manera predecible para su dominio estrecho (por ejemplo, revisor de código, depurador, científico de datos).
Ventana de contexto aislada. Cada subagente conserva su propio historial y contexto de conversación, lo que evita que el contexto del hilo principal se contamine con detalles de bajo nivel. Esto es fundamental para escalar flujos de trabajo que, de lo contrario, agotarían el contexto de una sola conversación.
Alcance y permisos de la herramienta. Puede otorgar o restringir qué herramientas internas o externas del Protocolo de Contexto de Modelo (MCP) puede usar un subagente. Esta es una función crucial de seguridad y gobernanza.
Configurar como código. Los subagentes se definen como archivos Markdown con contenido YAML (nombre, descripción, herramientas, modelo) y se almacenan en el nivel del proyecto (.claude/agents/) o nivel de usuario (~/.claude/agents/) Las definiciones del proyecto tienen prioridad.

¿Qué son la delegación automática y la invocación explícita?

Claude Code puede automáticamente delegar tareas a subagentes cuando se lo solicites o el subagente description coincide con la tarea, o puede explícitamente solicitar un agente (por ejemplo, > Use the code-reviewer subagent to check my recent changes). Hacer el description orientado a la acción ("Use PROACTIVELY", "MUST BE USED") para impulsar la delegación automática, dos formas complementarias de utilizar subagentes en Claude Code:

Delegación automática — Claude inspecciona la solicitud y delega el trabajo correspondiente a un subagente de forma proactiva.
Invocación explícita — llamas a un subagente por su nombre en tu mensaje/comando (por ejemplo, Use the code-reviewer subagent to check my changes).

Ambos enfoques implican diferentes ventajas y desventajas en términos de experiencia de usuario e ingeniería. A continuación, analizo cada uno.

Delegación automática

Cómo lo ven los usuarios. Emite un comando de alto nivel (por ejemplo, "Preparar una auditoría de seguridad para esta nueva biblioteca") y Claude detecta que uno o más subagentes son adecuados según la description campo en sus configuraciones. Si se configura para uso proactivo, el subagente se envía automáticamente y devuelve resultados como salidas estructuradas.

¿Por qué lo utilizan los equipos?

Reduce la carga cognitiva: no es necesario recordar ni escribir el nombre de cada subagente.
Permite una incorporación más fluida para flujos de trabajo compartidos en los que determinadas tareas siempre deben ser gestionadas por el mismo especialista.

Advertencias.

Debes diseñar el description y el sistema le solicita deliberadamente que seleccione de manera confiable el subagente correcto.
Una delegación demasiado entusiasta puede aumentar el uso de tokens y el ruido si muchos subagentes se activan para tareas similares; diseñe sus descripciones de manera conservadora.

Invocación explícita

Cómo lo ven los usuarios. Llamas explícitamente a un subagente: > Use the test-runner subagent to run the project testsLa orquestación es determinista: Claude invoca ese subagente nombrado con sus permisos y solicitud preconfigurados.

¿Por qué lo utilizan los equipos?

Control total: usted decide exactamente qué especialista se ejecutará, lo que simplifica la depuración y la reproducibilidad.
Es más fácil razonar sobre los costos y el acceso a las herramientas en CI o scripts automatizados.

Advertencias.

Más mecanografía y disciplina: los desarrolladores o la automatización deben conocer los nombres de subagentes correctos.
Menos oportunista: se pierde parte de la comodidad que supone que el agente principal habría detectado automáticamente un buen subagente.

Cómo funcionan los subagentes: descripción técnica general

A continuación se muestra una visión práctica y orientada a la implementación de lo que sucede cuando se crea y utiliza un subagente.

Definición de un subagente (configuración como código)

Un subagente es un archivo Markdown con contenido preliminar YAML. Los campos importantes incluyen:

name — un identificador único en minúsculas (con guion)
description — descripción en lenguaje natural utilizada para la correspondencia automática de delegación
tools — lista de comas opcional de herramientas permitidas (o se omiten para heredar todas las herramientas)
model — alias opcional (sonnet, opus, haiku) o inherit utilizar el modelo de la conversación principal

Un pequeño ejemplo (conceptual, no textual de los documentos):

---
name: code-reviewer
description: Expert code reviewer. Proactively reviews code for quality, security, and maintainability.
tools: Read, Grep, Bash
model: inherit
---
You are a senior code reviewer. Focus on security, correctness, and maintainability.

Estos archivos se encuentran en .claude/agents/ (alcance del proyecto) o ~/.claude/agents/ (ámbito de usuario). Los archivos de proyecto tienen prioridad, lo que facilita el uso compartido y el control de versiones de los subagentes.

Selección de modelos y herramientas

Campo modelo: Puede elegir un alias de modelo específico para el subagente o dejar que herede el modelo de la conversación principal. Esto le permite equilibrar el coste y la calidad (por ejemplo, usar un modelo más económico para subagentes que escanean grandes cantidades de datos y un modelo de mayor calidad para la síntesis final).
Alcance de la herramienta: Dotar a cada subagente de un conjunto mínimo de herramientas reduce el radio de acción y simplifica el razonamiento sobre seguridad. Las herramientas incluyen las primitivas estándar de Claude Code (Read, Grep, Bash, Edit, etc.) e integraciones proporcionadas por MCP.

Comportamiento en tiempo de ejecución y manejo del contexto

Cuando Claude delega en un subagente, ese subagente recibe:

Su indicador del sistema (el contenido YAML/Markdown).
Sólo el contexto que necesita (su propia ventana de contexto).
Acceso a la herramienta según lo permitido en su configuración.

Debido a que cada subagente mantiene un contexto aislado, las investigaciones largas o los análisis de archivos grandes se pueden descomponer en muchos contextos pequeños en lugar de forzar a un solo contexto a contener todo, una gran ventaja tanto para la confiabilidad como para la interpretabilidad.

Patrones arquitectónicos para subagente

La arquitectura más común es una orquestador (agente principal) que descompone una tarea de alto nivel, genera múltiples subagentes y luego sintetiza o verifica sus resultados. Dos patrones canónicos aparecen en la práctica:

1) Orquestador + Especialistas

Un agente (el orquestador) coordina múltiples subagentes en paralelo o en serie. El orquestador decide a qué especialista llamar, agrega los resultados, verifica la consistencia y realiza la integración final. Este es el enfoque común de "el gerente delega en los miembros del equipo" y coincide con muchos ejemplos y diseños recomendados en los materiales de Claude Code. Las ventajas incluyen paralelismo, una separación más clara de las preocupaciones y una contención de errores más sencilla (un subagente con errores solo afecta a su alcance).

Cuándo usarlo: tareas complejas con subproblemas independientes (por ejemplo, “generar pruebas”, “ejecutar análisis estático”, “reescribir un módulo” y luego “integrar y ejecutar pruebas de extremo a extremo”).

Compensaciones: La lógica de orquestación puede volverse compleja; los viajes de ida y vuelta adicionales pueden aumentar ligeramente la latencia.

2) Especialistas en tuberías y cadenas

Aquí, los subagentes se organizan en una secuencia donde la salida de uno se convierte en la entrada del siguiente (p. ej., especificación → andamiaje → implementación → prueba → optimización). Esto es esencialmente composición de funciones expresada como agentes, lo cual resulta útil cuando se necesitan transformaciones graduales y garantías estrictas sobre el flujo de datos entre etapas. Es conceptualmente más simple para flujos de trabajo lineales y, a veces, más fácil de depurar.

Cuándo usarlo: transformaciones deterministas de varios pasos (por ejemplo, traducir un documento de diseño en código estructurado, luego pruebas y luego optimizaciones).

Compensaciones: es menos natural para tareas que requieren una exploración amplia (investigación, lluvia de ideas) y un solo vínculo roto puede detener todo el proceso.

¿Qué hace que un subagente sea diferente de un simple indicador basado en roles?

1) Ventanas de contexto separadas

Cada subagente obtiene su propio búfer de contexto que almacena intercambios, archivos y metadatos relevantes para su función. Esto evita que el contexto de la sesión principal se contamine con mensajes intermedios confusos y permite conservar (o limitar) el historial de cada capacidad. Así, Claude Code permite mantener contextos duraderos y de alta señal para tareas especializadas sin tener que pagar el coste simbólico ni la sobrecarga cognitiva que supone tener todo en una sola solicitud.

2) Indicaciones del sistema y personajes

Los subagentes se crean con instrucciones a nivel de sistema que definen su función, tono y restricciones (p. ej., «Actuar únicamente como especialista en refactorización; no ejecutar comandos de shell» o «Generar pruebas unitarias al estilo de PyTest; usar únicamente interfaces públicas»). Estas instrucciones actúan como descripciones de funciones para el subagente y se aplican en tiempo de ejecución mediante el entorno de ejecución de Claude Code.

3) Vinculaciones de herramientas y alcance de permisos

Una diferencia práctica fundamental: a los subagentes se les puede conceder o denegar acceso a herramientas específicas (sistema de archivos, ejecución de procesos, API externas o conjuntos de datos privilegiados). Esto hace que los subagentes sean eficaces para privilegios mínimos Diseños: se puede bloquear la ejecución de comandos arbitrarios de un generador de documentación, mientras que a un subagente de CI se le otorga un entorno aislado. Muchas publicaciones de la comunidad recomiendan la combinación de subagentes con el Protocolo de Contexto de Modelo (MCP) o un servidor MCP basado en ganchos para gestionar el acceso seguro a secretos y E/S.

4) Elección del modelo y compensación coste-rendimiento

Dado que los subagentes son modulares, se pueden asignar diferentes modelos subyacentes según la complejidad de la tarea. Utilice un modelo Sonnet de alta capacidad para razonamiento profundo o un modelo Haiku ligero para tareas rápidas y repetitivas. Esta implementación heterogénea ayuda a equilibrar la latencia, el coste de tokens y la capacidad. Las actualizaciones de producto y los artículos de la comunidad de Anthropic enfatizan la implementación paralela de modelos más pequeños para un escalamiento rentable.

5) Patrones de comunicación

Los subagentes se comunican con el orquestador (o entre sí) mediante mensajes o archivos estructurados. Los patrones típicos incluyen:

devolviendo una carga útil JSON estructurada (preferible para orquestación programática),
escribir en un archivo con alcance en un espacio de trabajo compartido,
o enviar un mensaje final formateado al orquestador que incluya un puntaje de confianza y una justificación.
Los experimentos de la comunidad muestran que los equipos prefieren entregas explícitas y legibles por máquina para evitar ambigüedades.

Beneficios de rendimiento

Los subagentes no son solo una cuestión de diseño: brindan beneficios prácticos de rendimiento y calidad cuando se usan correctamente.

1) Reducción del tiempo de reloj de pared mediante paralelismo

Al enviar varios trabajadores simultáneamente (por ejemplo, un trabajador por carpeta del repositorio, por microservicio o por fragmento de datos), el orquestador reduce el tiempo necesario para completar grandes tareas compuestas. Casos de uso como la clasificación de informes de errores, la generación de documentación para varios módulos o la auditoría de múltiples servicios son ideales. Se obtienen mejoras significativas en los flujos de trabajo de los desarrolladores cuando las cargas de trabajo son realmente paralelizables.

Al asignar a cada rol su propio contexto, se evita la sobrecarga de recursos y se reduce el riesgo de alucinaciones causadas por el ruido histórico irrelevante. Esto se traduce en menos fallos relacionados con el contexto y resultados más consistentes para tareas especializadas. Los informes de la comunidad y la propia investigación de Anthropic demuestran que las configuraciones multiagente suelen superar a los agentes monolíticos en tareas de amplitud. Una evaluación interna de Anthropic reveló mejoras significativas en las tareas de investigación utilizando una arquitectura de agente principal y subagentes.

Advertencia: el paralelismo produce los mejores resultados cuando las subtareas son independientes. Si los trabajadores deben esperar constantemente unos de otros o compartir un estado pesado, se observarán rendimientos decrecientes.

2) Mejor utilización del contexto y menor desperdicio de tokens

En lugar de comprimir cada resultado de búsqueda intermedio en un único contexto global, los trabajadores conservan solo lo relevante dentro de su propia ventana y devuelven resultados depurados. Esto reduce el consumo de tokens para el orquestador y el riesgo de alcanzar los límites de contexto, una ventaja práctica al trabajar con bases de código extensas, registros extensos o repositorios de documentos extensos. La compactación/resumen del SDK amplía aún más la memoria efectiva de los agentes de larga duración.

3) Mayor precisión gracias a las indicaciones de especialistas

Un subagente diseñado como especialista de ámbito limitado puede ajustarse (mediante sus indicaciones del sistema y su conjunto de herramientas) para optimizar la precisión en su dominio: comprobaciones de seguridad, estilo de código o extracción de cumplimiento. Las indicaciones de ámbito limitado tienden a reducir la alucinación porque el margen de acción permitido del agente y los resultados esperados están limitados. Las organizaciones reportan resultados de mayor calidad en tareas como la revisión automatizada de código cuando utilizan subagentes específicos del dominio en lugar de encargarle todo a un generalista.

Cómo utilizan los equipos los subagentes: ejemplos de flujos de trabajo

A continuación se presentan ejemplos concretos para hacerlo menos abstracto.

Ejemplo A: Canal de refactorización (Orquestador + Especialistas)

El orquestador recibe una solicitud de “refactorización del componente X”.
Llamadas del orquestador analysis-subagent (sin permisos de escritura) para identificar puntos críticos de complejidad y dependencias riesgosas.
Llamadas del orquestador refactor-subagent (escribir permisos en un entorno sandbox tipo rama) para producir archivos refactorizados.
Llamadas del orquestador test-gen-subagent (sólo lectura en el código) para producir pruebas unitarias.
Orchestrator ejecuta CI con ci-runner-subagent (ejecución en espacio aislado) y agrega resultados para una revisión humana.
Este patrón aísla cada fase, contiene el riesgo y mantiene ordenados los registros de auditoría.

Ejemplo B — Investigación + prototipo (Pipeline)

literature-subagent Raspa y resume referencias (sin escritura de archivos, acceso web regulado).
prototype-subagent construye un PoC mínimo a partir del resumen.
benchmark-subagent ejecuta microbenchmarks en un entorno sandbox e informa los resultados.
Esta cadena refuerza la naturaleza secuencial de las tareas de investigación al tiempo que mantiene claras las responsabilidades.

Mejores prácticas y patrones

Diseño y configuración

Comience con roles pequeños y específicos. Asigna a cada subagente la responsabilidad de una tarea específica. Las responsabilidades limitadas facilitan enormemente la depuración.
Control de versiones de su .claude/agents/ carpeta. Trate las definiciones de subagente como código: revise, pruebe y fije las versiones. Esto reduce la desviación y facilita las auditorías.
Fije las herramientas y los modelos de forma intencionada. Use model: inherit Cuando desee un comportamiento consistente con la conversación principal, especifique un alias de modelo de menor costo para los análisis en segundo plano. Bloquee las herramientas para minimizar la superficie de ataque.

Patrones operativos

Utilice la invocación explícita para la automatización determinista. Si está ejecutando trabajos o ganchos de CI, llame a subagentes específicos para garantizar resultados predecibles.
Utilice la delegación automática en sesiones interactivas. Para el trabajo exploratorio, deje que Claude elija subagentes para reducir la fricción, pero asegúrese de que description Los campos están diseñados para que la automatización no se active inesperadamente.
Diseñar salidas estructuradas para síntesis. Obligar a los subagentes a escribir en archivos o producir JSON que el orquestador pueda leer; esto simplifica el paso de reducción y la auditoría.

Pruebas, monitoreo y gobernanza

Crear evaluaciones representativas. Rastrear dónde fallan los subagentes y crear pruebas que ejerciten esos modos de fallo. Anthropic recomienda conjuntos de pruebas representativos y mejoras iterativas.
Supervisar el uso de tokens y herramientas. Instrumente el uso de cada subagente y agregue alertas para detectar costos descontrolados o condiciones de límite de velocidad.

Cuándo NO utilizar subagentes

Los subagentes son poderosos pero no siempre son la herramienta adecuada.

Tareas sencillas: Para indicaciones breves y puntuales o transformaciones triviales, los subagentes agregan una complejidad innecesaria.
Restricciones de latencia estrictas: Los viajes de ida y vuelta de orquestación agregan sobrecarga; si necesita respuestas de una sola vuelta y con una latencia extremadamente baja, un enfoque monolítico puede ser más simple.
Equipos pequeños con poca infraestructura: Sin herramientas para secretos, observabilidad y entornos aislados, los subagentes pueden aumentar el riesgo operativo. Los artículos de la comunidad enfatizan la importancia de empezar con poco y añadir subagentes cuando se necesita modularidad.

Dónde utilizar el código Claude CLI es más recomendable

Fue un placer anunciar que CometAPI ahora es totalmente compatible con la potente CLI de Claude Code. Solo necesita instalar Claude Code y autenticarse con la clave API de Comet y la dirección base obtenidas para utilizar el modelo API de Comet en Claude Code.

¿Por qué utilizar Claude Code a través de CometAPI?

Principales características de inteligencia artificial: genere, depure y optimice código fácilmente utilizando modelos creados específicamente para desarrolladores.

Selección de modelos flexible: Nuestra amplia gama de modelos le permite desarrollar de forma más fluida.
Integración perfecta: Las API siempre están disponibles. Integre Claude Code directamente en su flujo de trabajo en minutos.
Usar Claude Code a través de CometAPI ahorrará más costosLa API de Claude proporcionada por CometAPI tiene un 20% de descuento sobre el precio oficial y se actualiza con el último modelo oficial.

¿Listo para usar Claude Code CLI? Consulta el Guía de API para obtener instrucciones detalladas.

Si quieres conocer más consejos, guías y novedades sobre IA síguenos en VK, X y Discord!

Vea también ¿Cómo instalar y ejecutar Claude Code a través de CometAPI?

Conclusión: ¿Por qué son importantes los subagentes ahora?

Los subagentes hacen que la promesa de los flujos de trabajo agénticos sea práctica para los equipos: permiten razonar sobre roles, permisos, contexto, costos y paralelización de forma explícita y como objetos de primera clase. Cuando se usan con criterio, los subagentes permiten una mayor velocidad de desarrollo, mejor calidad en tareas de varios pasos y una gobernanza más predecible. La contrapartida es que es necesario diseñar, probar y supervisar estos subagentes, al igual que el software de producción; pero esa inversión convierte la ingeniería rápida en una práctica de ingeniería confiable.