← Volver al listado de tecnologías ← Índice de Claude Certified Architect

Cap 3: Subagentes: Invocación, Contexto y Spawning

15 de marzo de 2026 Por: Artiko

claudesubagentestaskspawningcontext

Subagentes: Invocación, Contexto y Spawning

Los subagentes son instancias de Claude con contexto aislado, invocados por un coordinator para ejecutar tareas específicas. Este capítulo cubre los mecanismos de invocación, manejo de contexto y ejecución paralela.

Task tool como mecanismo de spawning

El Task tool es el mecanismo estándar para que un agente lance subagentes. Es una herramienta que Claude puede invocar dentro de su agentic loop.

Para que un agente pueda crear subagentes, su configuración de allowedTools debe incluir “Task”:

const coordinator = {
  name: "coordinator",
  allowedTools: ["Task", "Read", "Glob", "Grep"],
  // Sin "Task" en allowedTools, no puede spawnar subagentes
};

Cuando Claude invoca Task, el sistema crea una nueva sesión de agente con:

Un system prompt propio
Un conjunto de herramientas restringido
El prompt de la tarea como primer mensaje

AgentDefinition

Un AgentDefinition define el perfil de un subagente antes de invocarlo:

interface AgentDefinition {
  name: string;
  description: string;      // Para que el coordinator sepa cuándo usarlo
  systemPrompt: string;     // Instrucciones del subagente
  allowedTools: string[];   // Herramientas disponibles
}

Descriptions efectivas

La description ayuda al coordinator a decidir cuándo delegar a ese agente:

// MAL: vaga, no ayuda al routing
description: "Agente de código"

// BIEN: específica, facilita la decisión de routing
description: "Analiza archivos TypeScript para encontrar imports no usados,
dependencias circulares y exports sin consumidores"

System prompts enfocados

El system prompt define la identidad y constraints del subagente:

systemPrompt: `Eres un agente de análisis de seguridad. Tu trabajo es:
- Identificar vulnerabilidades en el código proporcionado
- Clasificarlas por severidad (critical, high, medium, low)
- Sugerir remediaciones concretas

NO implementes cambios. Solo reporta hallazgos.`

Tool restrictions

Cada subagente solo debe tener las herramientas que necesita:

Subagente	Tools necesarias
Analizador	Read, Glob, Grep
Implementador	Read, Edit, Write, Bash
Tester	Read, Bash
Investigador	Read, Glob, Grep, WebFetch

Restringir herramientas reduce el riesgo de acciones no deseadas y enfoca al subagente.

Contexto explícito en el prompt

Los subagentes no heredan automáticamente el historial ni el contexto del coordinator. Todo lo que un subagente necesita saber debe estar en su prompt de tarea:

// MAL: asume que el subagente sabe de qué se habla
coordinator.delegateTask("Corrige el bug que discutimos");

// BIEN: incluye toda la información necesaria
coordinator.delegateTask(`
Corrige el bug en src/auth/login.ts línea 42.
El error: la función validateToken() no verifica expiración.
Archivo afectado: src/auth/login.ts
Función: validateToken() en línea 42
Bug: falta check de token.exp < Date.now()
Criterio de éxito: validateToken retorna false para tokens expirados
`);

fork_session para exploración divergente

fork_session crea una rama de exploración a partir de un baseline compartido. Es útil cuando quieres explorar múltiples approaches sin contaminar la sesión principal.

Sesión principal (baseline)
    ├── Fork A: Explorar approach con SQL raw
    ├── Fork B: Explorar approach con ORM
    └── Fork C: Explorar approach con query builder

Características clave:

El fork hereda el estado del filesystem hasta el punto de fork
Cada fork opera de forma independiente
Los cambios en un fork no afectan al baseline ni a otros forks
El coordinator puede evaluar los resultados de cada fork y elegir el mejor

Cuándo usar fork_session

Situación	fork_session?
Explorar 2-3 approaches de diseño	Sí
Ejecutar una tarea secuencial predecible	No
Probar cambios riesgosos sin afectar main	Sí
Delegar subtareas independientes	No (usar spawning paralelo)

Spawning paralelo

Un coordinator puede emitir múltiples Task calls en un solo turno para ejecutar subagentes en paralelo:

// Claude puede generar múltiples tool_use blocks en una respuesta:
[
  { type: "tool_use", name: "Task", input: { prompt: "Analiza src/auth/" }},
  { type: "tool_use", name: "Task", input: { prompt: "Analiza src/api/" }},
  { type: "tool_use", name: "Task", input: { prompt: "Analiza src/db/" }},
]

Los 3 subagentes se ejecutan simultáneamente. El coordinator recibe los 3 resultados y los combina.

Requisitos para spawning paralelo

Las subtareas deben ser independientes entre sí
No debe haber dependencias de datos entre ellas
El coordinator debe poder agregar los resultados en cualquier orden

Structured data para pasar contexto

Cuando el coordinator pasa información a un subagente, usar formatos estructurados reduce ambigüedad:

// En lugar de texto libre:
"Revisa los archivos de autenticación del módulo de usuarios"

// Pasar datos estructurados:
`Tarea: Revisar código de autenticación
Archivos:
- src/auth/login.ts (líneas 1-150)
- src/auth/token.ts (líneas 1-80)
- src/auth/middleware.ts (líneas 1-60)

Contexto:
- Framework: Express.js
- Auth method: JWT
- Base de datos: PostgreSQL

Criterios de revisión:
1. Validación de inputs
2. Manejo de errores
3. Expiración de tokens`

Incluir URLs, números de página, rutas de archivos y metadata concreta evita que el subagente tenga que buscar o adivinar.

Diseñar prompts con goals, no con steps

Los prompts de tarea para subagentes deben definir qué lograr y cómo medir el éxito, no una secuencia de pasos:

// MAL: procedural step-by-step
`1. Lee el archivo src/auth.ts
 2. Busca la función validateToken
 3. Agrega un check de expiración
 4. Guarda el archivo`

// BIEN: goal-oriented con quality criteria
`Goal: Asegurar que validateToken() rechace tokens expirados.

Contexto: src/auth/login.ts contiene validateToken() que actualmente
no verifica el campo exp del JWT.

Quality criteria:
- validateToken retorna false cuando token.exp < Date.now()
- Los tests existentes siguen pasando
- No se modifican otras funciones del archivo`

El approach goal-oriented permite que Claude use su razonamiento para encontrar la mejor implementación, adaptándose a detalles que un step-by-step no anticiparía.

Resumen

Concepto	Detalle
Task tool	Requiere “Task” en allowedTools del coordinator
Contexto	Explícito en el prompt, nunca heredado
fork_session	Para exploración divergente desde baseline
Paralelo	Múltiples Task calls en un turno
Data format	Estructurado: rutas, líneas, metadata
Prompts	Goal-oriented con quality criteria

Anterior: Coordinator-Subagent | Índice: Índice | Siguiente: Workflows, Hooks y Handoffs