← Volver al listado de tecnologías ← Índice de Goose

11. Subagents

10 de mayo de 2026 Por: Artiko

goosesubagentsdelegationparallelrun-tasks

11. Subagents

Un subagent es una instancia independiente del agente que ejecuta una tarea específica con su propio context, sin contaminar la sesión principal.

Es la forma de delegar trabajo paralelo o exploratorio sin perder foco en la tarea principal.

El problema que resuelve

Estás en una sesión de Goose laburando en una refactorización compleja. De repente necesitás:

Investigar 10 librerías candidatas para reemplazar una.
Auditar 50 archivos en busca de un pattern específico.
Generar tests para 12 funciones existentes.

Hacerlo en la sesión principal rompe el contexto de la refactorización: el modelo se llena de info irrelevante para tu tarea original.

Subagents resuelven esto:

flowchart LR
    M[Sesión principal\nrefactor] --> S1[Subagent 1\ninvestigar libs]
    M --> S2[Subagent 2\nauditar pattern]
    M --> S3[Subagent 3\ngenerar tests]
    S1 -->|reporte resumido| M
    S2 -->|reporte resumido| M
    S3 -->|reporte resumido| M

Los subagents trabajan en paralelo, cada uno con su context aislado. Vuelven con un reporte sintético. Tu sesión principal solo ve el resultado, no los miles de tokens del proceso.

Lanzar un subagent

Desde la sesión

> /subagent run --name investigar-redis-clients "Buscá las top 5 librerías de Redis client para Node 20 actuales. Compará: features, mantenimiento, popularidad, licencia. Devolvé un markdown con tabla."

Goose:

Crea una nueva instancia con su propio context.
Le pasa el prompt.
Te devuelve el subagent ID y empieza a ejecutar en background.

🪿 subagent investigar-redis-clients started (id: sub-7a1b2)
   tracking with /subagent status sub-7a1b2

Mientras tanto vos seguís en tu sesión principal.

Verificar status

> /subagent status sub-7a1b2
status: running
elapsed: 1m 23s
turns: 4
tokens: 8.2k

Recoger resultado

> /subagent get sub-7a1b2
[markdown del reporte]

O si querés que se inserte directo en tu context:

> /subagent merge sub-7a1b2

Eso pega el reporte como mensaje del usuario en tu sesión principal.

Listar todos

> /subagent list
sub-7a1b2  done       investigar-redis-clients   1m 47s
sub-3c8f9  running    auditar-pattern            34s
sub-2d10e  failed     generar-tests              error: timeout

CLI: lanzar subagents fuera de sesión

goose subagent run \
  --name audit-deps \
  --prompt "Listá todas las dependencias deprecadas en package.json y reportá cuáles tienen reemplazos directos." \
  --output audit.md

Útil en CI o para batch jobs:

# Correr 3 subagents en paralelo
goose subagent run --name task1 --prompt "..." &
goose subagent run --name task2 --prompt "..." &
goose subagent run --name task3 --prompt "..." &
wait

Subagents con recipes

La forma más estructurada: subagent ejecuta un recipe en lugar de un prompt libre.

goose subagent run \
  --recipe code-review.yaml \
  --param pr_number=42 \
  --output review.json

Esto combina lo mejor de los dos mundos:

Recipe: schema, permisos, validación.
Subagent: aislamiento, paralelismo.

Run Tasks

Versión simplificada para múltiples tareas en batch:

# tasks.yaml
tasks:
  - name: review-frontend
    prompt: "Audit src/frontend/ por security issues"
    output: reviews/frontend.md

  - name: review-backend
    prompt: "Audit src/backend/ por security issues"
    output: reviews/backend.md

  - name: review-infra
    prompt: "Audit terraform/ por security issues"
    output: reviews/infra.md

goose run tasks.yaml --parallel 3

Goose lanza los 3 tasks en paralelo (cada uno como subagent), espera que terminen y te da un resumen consolidado.

Patrones de uso

Pattern 1: investigación previa a decisión

Cuando una tarea grande necesita información para decidir cómo proceder:

flowchart TD
    P["Tarea principal:<br/>migrar de Redis a Valkey"] --> S1["Subagent:<br/>audit usos<br/>actuales de Redis"]
    P --> S2["Subagent:<br/>diff API<br/>Redis vs Valkey"]
    S1 --> M["Reporte<br/>consolidado"]
    S2 --> M
    M --> P2["Tarea principal<br/>con contexto rico"]

Hacés que los subagents preparen el terreno; vos tomás la decisión informada.

Pattern 2: paralelización de tareas independientes

Generar 50 tests para 50 funciones — cada función es un subagent:

for fn in $(rg -l 'export function' src/); do
  goose subagent run \
    --name "test-$(basename $fn)" \
    --recipe generate-test.yaml \
    --param target=$fn &
done
wait

50 subagents en paralelo (con throttle obvio según tu rate limit del provider).

Pattern 3: explorador asíncrono

Mientras vos hacés algo, un subagent hace scouting:

> /subagent run --name scout "Buscá en el codebase ejemplos de manejo de errores asíncronos. Devolvé 3 patterns con sus pros y contras."

Vos seguís trabajando. Cuando estás listo, /subagent get scout y aprovechás la investigación.

Pattern 4: dual analysis

Mismo problema, dos perspectivas:

goose subagent run --name security-perspective \
  --prompt "Analizá este código solo desde perspectiva de seguridad: $(cat src/auth.ts)" &

goose subagent run --name performance-perspective \
  --prompt "Analizá este código solo desde perspectiva de performance: $(cat src/auth.ts)" &

wait

Comparás las dos respuestas; los subagents no se influyen entre sí.

Limitaciones a tener en cuenta

1. Tokens y costo se multiplican

10 subagents en paralelo = 10x el costo de tokens vs un único agent serial. Solo paralelizá cuando el ahorro de tiempo humano justifica el costo.

2. Coordinación es responsabilidad del orquestador

Si dos subagents necesitan información que el otro está produciendo, no se hablan entre sí. Vos (o el agente principal) tenés que orquestar.

3. Rate limits del provider

20 subagents simultáneos pueden saturar tu rate limit. Goose tiene throttle interno pero respeta el límite global del provider — vas a ver 429 Too Many Requests.

# config con throttle
subagents:
  max_parallel: 5
  retry_on_rate_limit: true
  retry_backoff: 2.0

4. Debugging más complejo

Un subagent que falla silenciosamente es harder de debuggear que un fallo en sesión principal. Activá logs:

GOOSE_LOG_LEVEL=debug goose subagent run --name task1 --prompt "..."

Ejemplo práctico end-to-end

Caso: tenés que portar 30 endpoints de Express a Fastify. Workflow con subagents:

# 1. Listar endpoints
goose run list-endpoints.yaml --output endpoints.json

# 2. Por cada endpoint, lanzar subagent que migra
jq -r '.[] | .file' endpoints.json | while read file; do
  goose subagent run \
    --name "migrate-$(basename $file)" \
    --recipe migrate-endpoint.yaml \
    --param target=$file &

  # throttle: max 5 simultáneos
  if [ $(jobs -r | wc -l) -ge 5 ]; then
    wait -n
  fi
done

wait

# 3. Recolectar resultados
goose subagent list --status done --output migration-report.md

3 horas de trabajo manual reducidas a 20 minutos de tiempo wall-clock + ~$15 en tokens. Es ese tipo de uso donde subagents brillan.

Subagents vs sesiones múltiples

¿Por qué no abrir varias terminales con goose session en paralelo? Porque:

Subagents	Sesiones múltiples
Lanzados desde la sesión principal	Independientes
Reportan al orquestador	Cada una es estanca
Comparten config/extensions	Cada una con la suya
API programática (`goose subagent ...`)	Solo interactivas
Útiles en CI/scripts	Solo manuales

Subagents son la respuesta correcta cuando necesitás delegar dentro de un flow mayor. Sesiones múltiples cuando trabajás en proyectos completamente distintos.

¿Qué viene?

Subagents potencian Goose pero también amplifican lo que puede salir mal. En el próximo capítulo cubrimos permisos, allowlist, sandbox y todo lo que hace que Goose sea seguro de operar en entornos serios.