Cap 4: Desarrollo Multi-Agente

El paradigma multi-agente

El desarrollo multi-agente consiste en ejecutar varios agentes de IA simultáneamente, cada uno trabajando en una tarea diferente dentro del mismo proyecto. Orca hace esto posible gracias a la combinación de worktrees (aislamiento) y una interfaz diseñada para gestionar múltiples procesos.

flowchart TB
    D[Desarrollador] -->|dirige| O[Orca]
    O -->|worktree 1| C[Claude Code<br/>feat/auth]
    O -->|worktree 2| X[Codex<br/>fix/api]
    O -->|worktree 3| G[Gemini<br/>docs/readme]

    C -->|commits| R[(Repo)]
    X -->|commits| R
    G -->|commits| R

Lanzar agentes

Desde la UI

1. Crea o selecciona un worktree
2. Abre una nueva terminal en ese worktree (Ctrl/Cmd + T)
3. Selecciona el agente del dropdown (Claude Code, Codex, etc.)
4. Escribe tu prompt y el agente comienza a trabajar

Desde el CLI

# Crear worktree + lanzar agente en un comando
orca run --agent claude --branch feat/auth "Implementa autenticación con JWT"

# Lanzar agente en worktree existente
orca run --agent codex --worktree fix-api "Corrige el error 500 en /api/users"

Lanzar múltiples agentes en paralelo

# Lanzar 3 agentes simultáneamente
orca run --agent claude --branch feat/auth "Implementa login con OAuth"
orca run --agent codex --branch fix/tests "Corrige los tests rotos en CI"
orca run --agent claude --branch refactor/db "Migra queries a prepared statements"

Cada comando crea su worktree, lanza el agente y le asigna la tarea.

Tabs y Panes

Orca organiza los agentes en tabs (pestañas) y panes (paneles divididos), similar a tmux pero con UI gráfica.

Tabs de agentes

Cada agente activo tiene su propia tab en el panel inferior. La tab muestra:

• Nombre del agente y su icono
• Branch/worktree asignado
• Estado: running, waiting, completed, error
• Indicador de actividad (spinner cuando está trabajando)

Dividir en panes

Para ver múltiples agentes al mismo tiempo:

• Ctrl/Cmd + \ divide horizontalmente
• Ctrl/Cmd + Shift + \ divide verticalmente

Esto te permite observar en tiempo real lo que están haciendo Claude Code y Codex simultáneamente.

Monitorear agentes

Panel de estado

El panel de estado muestra un resumen de todos los agentes activos:

Agente	Worktree	Estado	Tiempo	Tokens
Claude Code	feat/auth	Working	2m 30s	45K
Codex	fix/api	Waiting input	1m 15s	22K
Claude Code	refactor/db	Completed	5m 00s	89K

Notificaciones

Orca notifica cuando un agente:

• Completa su tarea
• Necesita input (pregunta al usuario)
• Encuentra un error y se detiene
• Hace un commit en su worktree

Orquestación de tareas

Modo manual

Tú decides qué agente hace qué, cuándo lanzarlo y cuándo detenerlo. Es el modo por defecto.

Modo plan

Defines un plan con múltiples tareas y Orca las distribuye:

# orca-plan.yaml
tasks:
  - name: "Autenticación"
    agent: claude
    branch: feat/auth
    prompt: "Implementa login con JWT y refresh tokens"

  - name: "API endpoints"
    agent: codex
    branch: feat/api
    prompt: "Crea endpoints CRUD para /api/products"
    depends_on: []

  - name: "Tests E2E"
    agent: claude
    branch: feat/e2e
    prompt: "Escribe tests E2E con Playwright para el flujo de login"
    depends_on: ["Autenticación"]

orca plan run orca-plan.yaml

Las tareas sin dependencias se ejecutan en paralelo. Las que tienen depends_on esperan a que sus dependencias completen.

gantt
    title Plan de ejecución multi-agente
    dateFormat HH:mm
    axisFormat %H:%M

    section Paralelo
    Autenticación (Claude)     :a1, 00:00, 5min
    API endpoints (Codex)      :a2, 00:00, 4min

    section Secuencial
    Tests E2E (Claude)         :a3, after a1, 3min

Gestión de recursos

Límite de agentes concurrentes

Por defecto Orca permite hasta 4 agentes simultáneos. Puedes ajustarlo en Settings:

{
  "concurrency": {
    "maxAgents": 6,
    "maxTokensPerMinute": 500000
  }
}

Pausar y reanudar

# Pausar un agente específico
orca agent pause feat-auth

# Reanudar
orca agent resume feat-auth

# Pausar todos
orca agent pause --all

Agentes soportados

Orca es agnóstico de agente. Cualquier herramienta CLI que lea stdin y escriba stdout funciona. Los agentes oficialmente probados son:

Agente	Comando	Notas
Claude Code	claude	Soporte nativo, mejor integración
OpenAI Codex	codex	Soporte completo
Google Gemini CLI	gemini	Soporte completo
Aider	aider	Soporte completo
OpenCode	opencode	Soporte experimental

Buenas prácticas multi-agente

1. Tareas atómicas: cada agente debería trabajar en una tarea bien definida y acotada
2. Branches descriptivos: facilita la revisión posterior
3. Revisa antes de merge: nunca hagas merge automático sin revisar los diffs
4. Monitorea tokens: múltiples agentes consumen tokens rápidamente
5. Una tarea, un worktree: no asignes múltiples tareas al mismo worktree