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 bash y file_edit de cada subagente de forma independiente del padre y entre sí.
• El agente padre solo necesita file_edit para 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), una description (descripción) que el modelo padre utiliza para decidir cuándo invocarlo, y sus propias allowed_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

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

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_tools del 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

Preguntas frecuentes

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.