SpyBara
Go Premium

agent-sdk/subagents.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

87 added, 75 removed.

2026
Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Subagentes en el SDK

Define e invoque subagentes para aislar contexto, ejecutar tareas en paralelo y aplicar instrucciones especializadas en sus aplicaciones Claude Agent SDK.

Los subagentes son instancias de agente separadas que su agente principal puede generar para manejar subtareas enfocadas. Utilice subagentes para aislar contexto para subtareas enfocadas, ejecutar múltiples análisis en paralelo y aplicar instrucciones especializadas sin sobrecargar el prompt del agente principal.

Esta guía explica cómo definir y usar subagentes en el SDK utilizando el parámetro agents.

Descripción general

Puede crear subagentes de tres formas:

  • Programáticamente: use el parámetro agents en sus opciones query() (TypeScript, Python)
  • Basado en sistema de archivos: defina agentes como archivos markdown en directorios .claude/agents/ (consulte definición de subagentes como archivos)
  • Propósito general integrado: Claude puede invocar el subagente integrado general-purpose en cualquier momento a través de la herramienta Agent sin que usted defina nada

Esta guía se enfoca en el enfoque programático, que se recomienda para aplicaciones SDK.

Cuando define subagentes, Claude determina si invocarlos en función del campo description de cada subagente. Escriba descripciones claras que expliquen cuándo se debe usar el subagente, y Claude delegará automáticamente las tareas apropiadas. También puede solicitar explícitamente un subagente por nombre en su prompt (por ejemplo, "Usa el agente code-reviewer para...").

Beneficios de usar subagentes

Aislamiento de contexto

Cada subagente se ejecuta en su propia conversación nueva. Las llamadas a herramientas intermedias y los resultados permanecen dentro del subagente; solo su mensaje final regresa al padre. Consulte Qué heredan los subagentes para ver exactamente qué hay en el contexto del subagente.

Ejemplo: un subagente research-assistant puede explorar docenas de archivos sin que ninguno de ese contenido se acumule en la conversación principal. El padre recibe un resumen conciso, no cada archivo que leyó el subagente.

Paralelización

Múltiples subagentes pueden ejecutarse simultáneamente, por lo que las subtareas independientes se completan en el tiempo del más lento en lugar de la suma de todos ellos.

Ejemplo: durante una revisión de código, puede ejecutar los subagentes style-checker, security-scanner y test-coverage simultáneamente en lugar de secuencialmente.

Instrucciones y conocimiento especializados

Cada subagente puede tener prompts de sistema personalizados con experiencia específica, mejores prácticas y restricciones.

Ejemplo: un subagente database-migration puede tener conocimiento detallado sobre mejores prácticas de SQL, estrategias de reversión y verificaciones de integridad de datos que serían ruido innecesario en las instrucciones del agente principal.

Restricciones de herramientas

Los subagentes pueden limitarse a herramientas específicas, reduciendo el riesgo de acciones no intencionadas.

Ejemplo: un subagente doc-reviewer podría tener acceso solo a las herramientas Read y Grep, asegurando que pueda analizar pero nunca modifique accidentalmente sus archivos de documentación.

Creación de subagentes

Defina subagentes directamente en su código utilizando el parámetro agents. Este ejemplo crea dos subagentes: un revisor de código con acceso de solo lectura y un ejecutor de pruebas que puede ejecutar comandos. Claude invoca subagentes a través de la herramienta Agent, por lo que incluya Agent en allowedTools para aprobar automáticamente las invocaciones de subagentes sin un aviso de permiso.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
async for message in query(
prompt="Review the authentication module for security issues",
options=ClaudeAgentOptions(
# Auto-approve these tools, including Agent for subagent invocation
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
"code-reviewer": AgentDefinition(
# description tells Claude when to use this subagent
description="Expert code review specialist. Use for quality, security, and maintainability reviews.",
# prompt defines the subagent's behavior and expertise
prompt="""You are a code review specialist with expertise in security, performance, and best practices.

When reviewing code:
- Identify security vulnerabilities
- Check for performance issues
- Verify adherence to coding standards
- Suggest specific improvements

Be thorough but concise in your feedback.""",
# tools restricts what the subagent can do (read-only here)
tools=["Read", "Grep", "Glob"],
# model overrides the default model for this subagent
model="sonnet",
),
"test-runner": AgentDefinition(
description="Runs and analyzes test suites. Use for test execution and coverage analysis.",
prompt="""You are a test execution specialist. Run tests and provide clear analysis of results.

Focus on:
- Running test commands
- Analyzing test output
- Identifying failing tests
- Suggesting fixes for failures""",
# Bash access lets this subagent run test commands
tools=["Bash", "Read", "Grep"],
),
},
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

Configuración de AgentDefinition

Campo Tipo Requerido Descripción
description string Sí Descripción en lenguaje natural de cuándo usar este agente
prompt string Sí El prompt del sistema del agente que define su rol y comportamiento
tools string[] No Matriz de nombres de herramientas permitidas. Si se omite, hereda todas las herramientas
disallowedTools string[] No Matriz de nombres de herramientas a eliminar del conjunto de herramientas del agente. También se aceptan patrones a nivel de servidor MCP: mcp__server o mcp__server__* elimina todas las herramientas de ese servidor, y mcp__* elimina todas las herramientas MCP de cualquier servidor
model string No Anulación de modelo para este agente. Acepta un alias como 'fable', 'opus', 'sonnet', 'haiku', 'inherit', o un ID de modelo completo. Por defecto es el modelo principal si se omite
skills string[] No Lista de nombres de skills a precargar en el contexto del agente al inicio. Los skills no listados permanecen invocables a través de la herramienta Skill
memory 'user' | 'project' | 'local' No Fuente de memoria para este agente
mcpServers (string | object)[] No Servidores MCP disponibles para este agente, por nombre o configuración en línea
initialPrompt string No Se envía automáticamente como el primer turno del usuario cuando este agente se ejecuta como el agente del hilo principal. Se ignora cuando el agente se invoca como subagente
maxTurns number No Número máximo de turnos de agente antes de que el agente se detenga
background boolean No Ejecutar este agente como una tarea de fondo no bloqueante cuando se invoca
effort 'low' | 'medium' | 'high' | 'xhigh' | 'max' | number No Nivel de esfuerzo de razonamiento para este agente
permissionMode PermissionMode No Modo de permiso para la ejecución de herramientas dentro de este agente

En el SDK de Python, estos nombres de campo usan camelCase para coincidir con el formato de cable. Consulte la referencia AgentDefinition para obtener detalles.

Definición basada en sistema de archivos (alternativa)

También puede definir subagentes como archivos markdown en directorios .claude/agents/. Consulte la documentación de subagentes de Claude Code para obtener detalles sobre este enfoque. Los agentes definidos programáticamente tienen prioridad sobre los agentes basados en sistema de archivos con el mismo nombre.

Qué heredan los subagentes

La ventana de contexto de un subagente comienza nueva (sin conversación padre) pero no está vacía. El único canal del padre al subagente es la cadena de prompt de la herramienta Agent, así que incluya cualquier ruta de archivo, mensaje de error o decisión que el subagente necesite directamente en ese prompt.

El subagente recibe El subagente no recibe
Su propio prompt del sistema (AgentDefinition.prompt) y el prompt de la herramienta Agent El historial de conversación del padre o resultados de herramientas
CLAUDE.md del proyecto (cargado a través de settingSources) Contenido de skill precargado, a menos que esté listado en AgentDefinition.skills
Definiciones de herramientas (heredadas del padre, o el subconjunto en tools) El prompt del sistema del padre

Invocación de subagentes

Invocación automática

Claude decide automáticamente cuándo invocar subagentes en función de la tarea y la description de cada subagente. Por ejemplo, si define un subagente performance-optimizer con la descripción "Especialista en optimización de rendimiento para ajuste de consultas", Claude lo invocará cuando su prompt mencione optimizar consultas.

Escriba descripciones claras y específicas para que Claude pueda hacer coincidir tareas con el subagente correcto.

Invocación explícita

Para garantizar que Claude use un subagente específico, mencione su nombre en su prompt:

"Use the code-reviewer agent to check the authentication module"

Esto omite la coincidencia automática e invoca directamente el subagente nombrado.

Configuración dinámica de agentes

Puede crear definiciones de agentes dinámicamente en función de condiciones en tiempo de ejecución. Este ejemplo crea un revisor de seguridad con diferentes niveles de rigor, utilizando un modelo más potente para revisiones estrictas.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


# Factory function that returns an AgentDefinition
# This pattern lets you customize agents based on runtime conditions
def create_security_agent(security_level: str) -> AgentDefinition:
is_strict = security_level == "strict"
return AgentDefinition(
description="Security code reviewer",
# Customize the prompt based on strictness level
prompt=f"You are a {'strict' if is_strict else 'balanced'} security reviewer...",
tools=["Read", "Grep", "Glob"],
# Key insight: use a more capable model for high-stakes reviews
model="opus" if is_strict else "sonnet",
)


async def main():
# The agent is created at query time, so each request can use different settings
async for message in query(
prompt="Review this PR for security issues",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
# Call the factory with your desired configuration
"security-reviewer": create_security_agent("strict")
},
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

Detección de invocación de subagentes

Los subagentes se invocan a través de la herramienta Agent. Para detectar cuándo se invoca un subagente, busque bloques tool_use donde name sea "Agent". Los mensajes desde dentro del contexto de un subagente incluyen un campo parent_tool_use_id.

La estructura del mensaje difiere entre SDKs. En Python, los bloques de contenido se acceden directamente a través de message.content. En TypeScript, SDKAssistantMessage envuelve el mensaje de la API de Claude, por lo que el contenido se accede a través de message.message.content.

Este ejemplo itera a través de mensajes transmitidos, registrando cuándo se invoca un subagente y cuándo los mensajes posteriores se originan dentro del contexto de ejecución de ese subagente.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ToolUseBlock


async def main():
async for message in query(
prompt="Use the code-reviewer agent to review this codebase",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Agent"],
agents={
"code-reviewer": AgentDefinition(
description="Expert code reviewer.",
prompt="Analyze code quality and suggest improvements.",
tools=["Read", "Glob", "Grep"],
)
},
),
):
# Check for subagent invocation. Match both names: older SDK
# versions emitted "Task", current versions emit "Agent".
if hasattr(message, "content") and message.content:
for block in message.content:
if isinstance(block, ToolUseBlock) and block.name in (
"Task",
"Agent",
):
print(f"Subagent invoked: {block.input.get('subagent_type')}")

# Check if this message is from within a subagent's context
if hasattr(message, "parent_tool_use_id") and message.parent_tool_use_id:
print("  (running inside subagent)")

if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

Reanudación de subagentes

Los subagentes pueden reanudarse para continuar donde se detuvieron. Los subagentes reanudados retienen su historial de conversación completo, incluidas todas las llamadas a herramientas anteriores, resultados y razonamiento. El subagente continúa exactamente donde se detuvo en lugar de comenzar de nuevo.

Cuando un subagente se completa, el resultado de la herramienta Agent incluye un bloque de texto que contiene agentId: <id>. Los agentes integrados Explore y Plan son de una sola ejecución y no devuelven un agentId, así que use un agente personalizado o general-purpose cuando necesite reanudar. Para reanudar un subagente programáticamente:

  1. Capture el ID de sesión: Extraiga session_id de los mensajes durante la primera consulta
  2. Extraiga el ID del agente: Analice agentId del texto del resultado de la herramienta Agent
  3. Reanude la sesión: Pase resume: sessionId en las opciones de la segunda consulta e incluya el ID del agente en su prompt

El ejemplo a continuación define un agente personalizado endpoint-finder. La primera consulta lo ejecuta y captura el ID de sesión e ID de agente del resultado de la herramienta Agent, luego la segunda consulta reanuda la sesión para hacer una pregunta de seguimiento que requiere contexto del primer análisis.

import asyncio
import re
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ToolResultBlock

AGENTS = {
"endpoint-finder": AgentDefinition(
description="Locates and catalogs API endpoints in a codebase.",
prompt="You find and document API endpoints. Report each endpoint's path, method, and handler.",
tools=["Read", "Grep", "Glob"],
)
}


def extract_agent_id(block: ToolResultBlock) -> str | None:
"""Extract agentId from an Agent tool result's text content."""
parts = block.content if isinstance(block.content, list) else [{"text": block.content}]
for part in parts:
if match := re.search(r"agentId:\s*([\w-]+)", part.get("text") or ""):
return match.group(1)
return None


async def main():
agent_id = None
session_id = None

# First invocation - run the endpoint-finder subagent
async for message in query(
prompt="Use the endpoint-finder agent to find all API endpoints in this codebase",
options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"], agents=AGENTS),
):
# Capture session_id from ResultMessage (needed to resume this session)
if hasattr(message, "session_id"):
session_id = message.session_id
# Search tool results for the agentId trailer
for block in getattr(message, "content", None) or []:
if isinstance(block, ToolResultBlock):
agent_id = extract_agent_id(block) or agent_id
# Print the final result
if hasattr(message, "result"):
print(message.result)

# Second invocation - resume and ask follow-up
if agent_id and session_id:
async for message in query(
prompt=f"Resume agent {agent_id} and list the top 3 most complex endpoints",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"], agents=AGENTS, resume=session_id
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

Las transcripciones de subagentes persisten independientemente de la conversación principal:

  • Compactación de conversación principal: Cuando la conversación principal se compacta, las transcripciones de subagentes no se ven afectadas. Se almacenan en archivos separados.
  • Persistencia de sesión: Las transcripciones de subagentes persisten dentro de su sesión. Puede reanudar un subagente después de reiniciar Claude Code reanudando la misma sesión.
  • Limpieza automática: Las transcripciones se limpian en función de la configuración cleanupPeriodDays (predeterminado: 30 días).

Restricciones de herramientas

Los subagentes pueden tener acceso restringido a herramientas a través del campo tools:

  • Omitir el campo: el agente hereda todas las herramientas disponibles (predeterminado)
  • Especificar herramientas: el agente solo puede usar las herramientas listadas

Este ejemplo crea un agente de análisis de solo lectura que puede examinar código pero no puede modificar archivos ni ejecutar comandos.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
async for message in query(
prompt="Analyze the architecture of this codebase",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
"code-analyzer": AgentDefinition(
description="Static code analysis and architecture review",
prompt="""You are a code architecture analyst. Analyze code structure,
identify patterns, and suggest improvements without making changes.""",
# Read-only tools: no Edit, Write, or Bash access
tools=["Read", "Grep", "Glob"],
)
},
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

Combinaciones comunes de herramientas

Caso de uso Herramientas Descripción
Análisis de solo lectura Read, Grep, Glob Puede examinar código pero no modificar ni ejecutar
Ejecución de pruebas Bash, Read, Grep Puede ejecutar comandos y analizar salida
Modificación de código Read, Edit, Write, Grep, Glob Acceso completo de lectura/escritura sin ejecución de comandos
Acceso completo Todas las herramientas Hereda todas las herramientas del padre (omita el campo tools)

Escalar con flujos de trabajo dinámicos

Los subagentes funcionan bien para algunas tareas delegadas por turno. Para ejecuciones que coordinan docenas a cientos de agentes, use la herramienta Workflow, que mueve la orquestación a un script que el tiempo de ejecución ejecuta fuera del contexto de la conversación. Consulte flujos de trabajo dinámicos para ver cómo los flujos de trabajo difieren de la delegación de subagentes turno a turno.

La herramienta Workflow está disponible en el SDK de TypeScript Agent v0.3.149 y posterior. Incluya Workflow en allowedTools para aprobar automáticamente las ejecuciones de flujo de trabajo. Los esquemas de entrada y salida de la herramienta se enumeran en la referencia de TypeScript.

Solución de problemas

Claude no delega a subagentes

Si Claude completa tareas directamente en lugar de delegar a su subagente:

  1. Verifique que las invocaciones de Agent estén aprobadas: incluya Agent en allowedTools para aprobar automáticamente las llamadas de subagentes. Sin esto, las invocaciones de Agent caen en su callback canUseTool o, en modo dontAsk, se deniegan
  2. Use prompting explícito: mencione el subagente por nombre en su prompt (por ejemplo, "Usa el agente code-reviewer para...")
  3. Escriba una descripción clara: explique exactamente cuándo se debe usar el subagente para que Claude pueda hacer coincidir las tareas apropiadamente

Agentes basados en sistema de archivos no se cargan

Los agentes definidos en .claude/agents/ se cargan solo al inicio. Si crea un nuevo archivo de agente mientras Claude Code está en ejecución, reinicie la sesión para cargarlo.

Windows: fallos de prompt largo

En Windows, los subagentes con prompts muy largos pueden fallar debido a límites de longitud de línea de comandos (8191 caracteres). Mantenga los prompts concisos o use agentes basados en sistema de archivos para instrucciones complejas.