Delegar trabajo a subagentes en el Claude Agent SDK
Un subagente es un agente hijo con su propio contexto aislado al que un agente padre puede delegar una subtarea.
En lugar de que un solo agente intente mantener una tarea completa, incluyendo cada paso intermedio de cada subproblema, en una única ventana de contexto, un padre puede delegar piezas autocontenidas a subagentes y solo recibir sus resultados finales.
Resumen
Los subagentes existen por dos razones relacionadas: aislamiento de contexto y paralelismo.
El aislamiento significa que el razonamiento exploratorio de un subagente, los intentos fallidos y las llamadas a herramientas intermedias nunca contaminan el contexto del padre; el padre ve un resultado limpio.
El paralelismo significa que los subagentes independientes pueden ejecutarse de forma concurrente, ya que ninguno depende del estado intermedio del otro.
Esta página cubre cómo definir subagentes, cuándo una tarea es un buen candidato para la delegación y cómo fluyen el ámbito de las herramientas y los resultados entre el padre y el hijo.
Receta
Tarjeta de receta de referencia rápida, lista para copiar y pegar.
from claude_agent_sdk import query, AgentOptions, SubagentConfig
options = AgentOptions(
allowed_tools=["file_edit", "bash"],
subagents=[
SubagentConfig(
name="frontend-reviewer",
description="Revisa los cambios en componentes React en cuanto a corrección y estilo.",
allowed_tools=["file_edit"],
),
SubagentConfig(
name="backend-reviewer",
description="Revisa los cambios en rutas de API en cuanto a corrección y seguridad.",
allowed_tools=["file_edit", "bash"],
),
],
)
async for message in query(
prompt="Revisa los cambios de frontend y backend de este PR utilizando los dos subagentes revisores.",
options=options,
):
print(message)Cuándo usar esto:
- Una tarea se divide limpiamente en dos o más piezas independientes que no necesitan ver los pasos intermedios de las demás.
- Una pieza de lo contrario inundaría el contexto del padre con razonamiento exploratorio irrelevante para el resto de la tarea.
- Quieres un conjunto de herramientas más reducido y con un ámbito diferente para una parte del trabajo que para otra.
- Quieres ejecutar piezas independientes de forma concurrente en lugar de una tras otra.
Ejemplo de trabajo
import asyncio
from claude_agent_sdk import query, AgentOptions, SubagentConfig
async def audit_monorepo_packages(repo_path: str, packages: list[str]) -> None:
subagents = [
SubagentConfig(
name=f"audit-{pkg}",
description=f"Audita el paquete {pkg} en busca de dependencias obsoletas y errores de lint.",
allowed_tools=["bash", "file_edit"],
tool_config={
"bash": {"allowed_commands": ["npm outdated", "npm run lint"]},
"file_edit": {"allowed_paths": [f"packages/{pkg}/**"]},
},
)
for pkg in packages
]
options = AgentOptions(
cwd=repo_path,
allowed_tools=["file_edit"],
subagents=subagents,
)
prompt = (
f"Utiliza los subagentes de auditoría para cada uno de {packages} para comprobar si hay dependencias obsoletas "
"y errores de lint, luego escribe un resumen combinado en AUDIT.md "
"en la raíz del repositorio con una sección por paquete."
)
async for message in query(prompt=prompt, options=options):
if message.get("type") == "text":
print(message["text"], end="", flush=True)
elif message.get("type") == "subagent_result":
print(f"\n[{message['subagent_name']} finalizado]")
asyncio.run(audit_monorepo_packages("/repo", ["billing", "auth", "search"]))Lo que esto demuestra:
- Generar un subagente por paquete para que cada auditoría se ejecute en su propio contexto aislado, limitado solo a los archivos de ese paquete.
- Limitar el acceso
bashyfile_editde cada subagente de forma independiente del padre y entre sí. - El agente padre solo necesita
file_editpara sí mismo, ya que su propio trabajo es solo escribir el resumen combinado. - Subtareas independientes y de forma similar (auditar paquetes no relacionados) como el caso más claro para la delegación.
Inmersión profunda
Cómo funciona
- Un subagente se define con un
name(nombre), unadescription(descripción) que el modelo padre utiliza para decidir cuándo invocarlo, y sus propiasallowed_tools(herramientas permitidas) /tool_config(configuración de herramientas). - Desde el bucle de uso de herramientas del padre, invocar un subagente se parece a cualquier otra llamada a herramienta: el padre decide llamarlo, el SDK ejecuta el bucle interno del subagente hasta su finalización y el resultado vuelve como una observación.
- El subagente ejecuta su propio ciclo de decidir-actuar-observar internamente, con su propia ventana de contexto que se inicia fresca para esa invocación y no transporta el historial completo del padre por defecto.
- Solo el resultado final del subagente cruza de vuelta al contexto del padre, no sus llamadas a herramientas intermedias ni su razonamiento; esta es la propiedad de aislamiento que mantiene limpio el contexto del padre.
- Dado que cada invocación de subagente es autocontenida, los subagentes independientes pueden ser enviados y esperados de forma concurrente, mientras que un subagente cuya tarea depende de la salida de otro subagente debe ejecutarse después de él.
Cuándo delegar frente a añadir una herramienta
| Señal | Favorece | Razón |
|---|---|---|
| La tarea necesita una capacidad más, sin exploración independiente | Añadir una herramienta | Más simple; no se necesita un límite de contexto adicional |
| La tarea es una subtarea autocontenida con su propia exploración | Subagente | Mantiene el ruido exploratorio fuera del contexto del padre |
| Múltiples subtareas similares en entradas independientes | Subagentes (uno por entrada) | Permite la ejecución paralela |
| La subtarea necesita un ámbito de herramientas más estrecho o diferente que el padre | Subagente | El ámbito de las herramientas es por subagente, no compartido |
Notas de Python
# La descripción de un subagente es lo que el modelo padre lee para decidir
# cuándo invocarlo; trátala como una descripción de herramienta, no como un comentario.
SubagentConfig(
name="test-runner",
description="Ejecuta el conjunto de pruebas del proyecto e informa solo de las pruebas fallidas.",
allowed_tools=["bash"],
tool_config={"bash": {"allowed_commands": ["pytest"]}},
)Parámetros y valores de retorno
| Parámetro | Tipo | Descripción |
|---|---|---|
name | str | Identificador que el padre utiliza para invocar este subagente |
description | str | Indica al modelo padre cuándo se aplica este subagente |
allowed_tools | list[str] | Ámbito de herramientas para este subagente, independiente del padre |
tool_config | dict | Ámbito por herramienta para las herramientas de este subagente |
Trampas
- Delegar una tarea que en realidad no es independiente. Dividir una tarea con dependencias reales entre dos subagentes te obliga a secuenciarlos manualmente y pasarles los resultados tú mismo. Solución: solo divide las tareas a lo largo de límites genuinamente independientes; mantén los pasos dependientes en un agente o en secuencia.
- Escribir una descripción vaga del subagente. Una descripción como "agente auxiliar" no da al modelo padre ninguna señal sobre cuándo invocarlo. Solución: escribe descripciones como escribirías una descripción de herramienta: específica, orientada a la acción y limitada a un trabajo.
- Asumir que un subagente ve el historial completo del padre. Los subagentes normalmente comienzan con un contexto fresco para su invocación, no con toda la conversación del padre. Solución: pasa explícitamente cualquier contexto que el subagente necesite en el prompt que le des.
- Dividir en exceso una tarea simple en muchos subagentes. Cada invocación de subagente añade sobrecarga (un contexto fresco, un bucle interno completo); una tarea lo suficientemente simple para una llamada a herramienta no necesita un subagente. Solución: reserva los subagentes para subtareas genuinamente independientes y no triviales.
- Conceder a un subagente el ámbito de herramientas completo del padre por defecto. Copiar
allowed_toolsdel padre en cada subagente anula el propósito de limitar el trabajo de forma estrecha. Solución: limita cada subagente solo a lo que su trabajo específico requiere. - No manejar un fallo del subagente. Si el bucle interno de un subagente falla o se agota el tiempo de espera, el padre necesita decidir qué hacer con un resultado incompleto. Solución: trata los resultados del subagente como cualquier otro resultado de herramienta que pueda fallar, y maneja ese caso en tu prompt o lógica de aplicación.
Alternativas
| Alternativa | Usar cuando | No usar cuando |
|---|---|---|
| Un solo agente con más herramientas | La tarea necesita una capacidad más, no exploración independiente | La subtarea inundaría de lo contrario el contexto con razonamiento irrelevante |
| Llamadas a herramientas secuenciales en un solo agente | Los pasos dependen genuinamente de la salida de otros | Los pasos son independientes y podrían ejecutarse de forma concurrente |
Llamadas query() de nivel superior separadas | Las subtareas no están relacionadas entre sí, no hay una tarea padre compartida | Las subtareas forman parte de una tarea padre coherente que necesita un resultado combinado |
Preguntas frecuentes
¿Qué aísla exactamente un subagente?
- Su propia ventana de contexto, separada de la del padre.
- Su propio ámbito de herramientas, independiente de
allowed_toolsdel padre. - Su razonamiento intermedio y llamadas a herramientas, que nunca aparecen en el contexto del padre, solo el resultado final.
¿Cómo decide el padre cuándo invocar un subagente?
De la misma manera que decide llamar a cualquier herramienta: el modelo lee la description (descripción) del subagente junto con la conversación y elige invocarlo cuando la tarea coincide.
¿Pueden los subagentes ejecutarse en paralelo?
Sí, cuando son independientes entre sí. Los subagentes cuyas tareas no dependen de la salida de otros pueden ser enviados y esperados de forma concurrente.
¿Ve un subagente el historial de conversación del padre?
No por defecto; normalmente comienza con un contexto fresco para su propia invocación. Pasa explícitamente cualquier contexto necesario en el prompt que le des al subagente.
¿Puede un subagente tener sus propios subagentes?
El modelo de subagentes del SDK admite la anidación en principio, ya que cada subagente ejecuta su propio bucle interno de uso de herramientas, pero la anidación profunda añade sobrecarga real y dificultad de depuración; la mayoría de las tareas se benefician de un solo nivel.
¿Qué herramientas puede usar un subagente?
Las que le hayas asignado a través de sus propias allowed_tools y tool_config, independientemente del ámbito de herramientas del padre; a un subagente no se le conceden automáticamente las herramientas del padre.
¿En qué se diferencia delegar a un subagente de simplemente llamar a una herramienta?
Una llamada a herramienta ejecuta una acción discreta y devuelve un resultado. Una invocación de subagente ejecuta un bucle interno completo de uso de herramientas, llamando potencialmente a varias herramientas y razonando a través de varios pasos, antes de devolver un resultado final.
¿Cuándo una tarea es demasiado pequeña para un subagente?
Cuando es una acción única y simple que una llamada directa a herramienta manejaría igual de bien; la sobrecarga de un contexto fresco y un bucle interno no vale la pena para pasos triviales.
¿Qué sucede si la tarea de un subagente falla?
El fallo (o un resultado incompleto/de error) vuelve al padre como la observación de esa invocación, y el propio bucle del padre tiene que decidir cómo proceder, de la misma manera que manejaría cualquier llamada a herramienta fallida.
¿Puedo limitar cuántos subagentes se ejecutan a la vez?
Los límites de concurrencia son una preocupación a nivel de aplicación; tú controlas cuántas invocaciones de subagentes envías a la vez en tu propio código de orquestación alrededor de query().
Relacionado
- El modelo mental del Claude Agent SDK - cómo encajan los subagentes en el bucle conceptualmente
- Habilitar herramientas de edición de archivos, Bash y web en el Agent SDK - ámbito de herramientas, aplicable también por subagente
- Referencia de opciones de configuración del Claude Agent SDK - comparación de subagentes y otras opciones
- Añadir puntos de control de intervención humana a un flujo de trabajo del Agent SDK - puntos de control dentro del trabajo delegado
- Mejores prácticas del Claude Agent SDK - guía de producción sobre ámbito y delegación
Versiones de pila: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el Claude Agent SDK (última versión, Python y TypeScript). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.