Toolbox — Sesión 05: Agentes y subagentes

Objetivo de la sesión

Al terminar esta sesión serás capaz de:

1. Distinguir cuando necesitas un agente simple vs multi-agente
2. Diseñar un sistema coordinator + workers con responsabilidades claras
3. Implementar tools (herramientas) que los agentes pueden usar
4. Gestionar ejecución paralela y worktrees para tareas independientes
5. Aplicar guardrails para que los agentes no se desmanden

Vídeo: Agente simple vs multi-agente en acción

1. Cuando necesitas un agente y cuando no

La escalera de complejidad

    Nivel 0: Prompt directo
      → Una instruccion, una respuesta. Sin herramientas. Sin memoria.
      → Ejemplo: "Resume este documento"
      → No necesitas agente
    
    Nivel 1: Prompt + tools
      → La IA puede usar herramientas (buscar, leer archivos, consultar DB)
      → Ejemplo: "Busca en mi DB los clientes de Madrid y genera un informe"
      → Agente simple (1 agente, varias tools)
    
    Nivel 2: Multi-agente secuencial
      → Varios agentes especializados, uno despues de otro
      → Ejemplo: "Analiza → clasifica → genera informe → envia email"
      → Coordinator + workers en secuencia
    
    Nivel 3: Multi-agente paralelo
      → Varios agentes trabajando al mismo tiempo en tareas independientes
      → Ejemplo: "Analiza 10 documentos simultaneamente"
      → Coordinator + workers en paralelo
    
    Nivel 4: Multi-agente con bucle
      → Agentes que iteran: generan, evaluan, refinan hasta alcanzar calidad
      → Ejemplo: "Genera borrador → critico evalua → ajusta → hasta score > 8"
      → Coordinator + generator + evaluator en loop
    

Regla: empieza siempre en el nivel más bajo que resuelva tu problema

Si un prompt directo funciona, no necesitas agente. Si un agente simple funciona, no necesitas multi-agente. La complejidad tiene coste: más latencia, más tokens, más puntos de fallo.

2. Anatomía de un agente

Los 5 componentes de todo agente

    1. IDENTIDAD     → Quien es, que sabe hacer, que NO debe hacer
                       (system prompt)
    
    2. TOOLS         → Herramientas que puede usar
                       (funciones que ejecuta en el mundo real)
    
    3. MEMORIA       → Que recuerda de interacciones previas
                       (contexto de sesion, scratchpad)
    
    4. POLITICA      → Reglas de cuando actuar y cuando preguntar
                       (umbrales de confianza, HITL)
    
    5. OBSERVABILIDAD → Como sabemos que esta haciendo
                        (logs, trazas, metricas)
    

Ejemplo concreto: agente clasificador de tickets

    # agents/ticket_classifier/agent.py
    
    IDENTITY = """
    Eres un clasificador de tickets de soporte tecnico.
    Tu trabajo es asignar prioridad (P0-P3) y categoria.
    
    REGLAS:
    - P0: sistema caido, datos perdidos, seguridad comprometida
    - P1: funcionalidad core rota, multiples usuarios afectados
    - P2: funcionalidad secundaria rota, workaround disponible
    - P3: mejora, pregunta, cosmetic
    
    Si no estas seguro entre dos prioridades, elige la MAS ALTA.
    NUNCA clasifiques un ticket de seguridad como P2 o P3.
    """
    
    TOOLS = [
        search_similar_tickets,     # Buscar tickets parecidos anteriores
        get_customer_tier,          # Ver si el cliente es premium
        check_system_status,        # Verificar estado del sistema
    ]
    
    POLICY = {
        "confidence_threshold": 0.85,    # Si confianza < 85%, escalar a humano
        "max_retries": 2,                # Maximo 2 intentos antes de escalar
        "requires_human_approval": ["P0"] # P0 siempre requiere confirmacion humana
    }
    

3. El patrón Coordinator + Workers

Como funciona

    USUARIO → COORDINATOR → decide que workers necesita
                    ↓
             ┌──────┼──────┐
             ↓      ↓      ↓
          WORKER1 WORKER2 WORKER3
          (analiza)(clasifica)(genera)
             ↓      ↓      ↓
             └──────┼──────┘
                    ↓
              COORDINATOR → combina resultados → RESPUESTA
    

Reglas del Coordinator

1. NUNCA hace trabajo. Solo decide quien lo hace.
2. LEE los resultados de los workers. No asume que están bien. Verifica.
3. Tiene visión global. Conoce el objetivo final, no solo las partes.
4. Gestiona errores. Si un worker falla, decide: reintentar, escalar, o continuar sin el.

Reglas de los Workers

1. Scope acotado. Cada worker hace UNA cosa bien.
2. No deciden. Ejecutan lo que el coordinator les pide.
3. Scratchpad independiente. Cada worker tiene su propia memoria de trabajo. No comparten contexto entre si.
4. Tools propias. Cada worker tiene acceso solo a las tools que necesita. Mínimo privilegio.

Implementación básica

    # agents/coordinator/agent.py
    
    async def coordinate(task: str) -> str:
        # 1. Analizar la tarea
        plan = await plan_task(task)
        
        # 2. Asignar a workers
        results = {}
        for step in plan.steps:
            worker = get_worker(step.type)
            result = await worker.execute(step.input)
            results[step.name] = result
        
        # 3. Combinar resultados
        final = await synthesize(results, task)
        return final
    
    # agents/workers/analyzer.py
    
    class AnalyzerWorker:
        tools = [read_document, extract_entities, search_db]
        
        async def execute(self, input: str) -> str:
            config = load_prompt("analyzer")
            return await call_llm(
                prompt=config["prompt"],
                user_message=input,
                tools=self.tools
            )
    

4. Tools: las manos del agente

Que es una tool

Una tool es una función que el agente puede llamar para interactuar con el mundo real. Sin tools, el agente solo puede generar texto. Con tools, puede buscar, leer, escribir, enviar, calcular.

Anatomía de una tool

    def search_database(query: str, limit: int = 10) -> list[dict]:
        """
        Busca documentos relevantes en la base de datos.
        
        Args:
            query: Termino de busqueda en lenguaje natural
            limit: Numero maximo de resultados (default: 10)
        
        Returns:
            Lista de documentos con titulo, resumen y relevancia
        """
        # Implementacion real
        results = db.search(query, limit=limit)
        return [{"title": r.title, "summary": r.summary[:200], "score": r.score} for r in results]
    

Clave: La descripción (docstring) es lo que el agente lee para decidir si usa la tool. Si la descripción es mala, el agente no la usara bien.

Catálogo de tools por tipo

Regla de seguridad

    Tools de LECTURA  → El agente puede usar libremente
    Tools de ESCRITURA → Requieren confirmacion o umbral de confianza
    Tools de COMUNICACION → Siempre requieren aprobacion humana (HITL)
    

Nunca dejes que un agente envie emails, publique contenido o modifique datos de producción sin supervision humana. Al menos en las primeras semanas hasta que confies en su comportamiento.

5. Ejecución paralela y worktrees

Cuando paralelizar

Ejecución paralela en Python

    import asyncio
    
    async def parallel_analysis(documents: list[str]) -> list[str]:
        tasks = [analyze_document(doc) for doc in documents]
        results = await asyncio.gather(*tasks)
        return results
    

Worktrees (Claude Code)

En Claude Code, puedes lanzar subagentes en worktrees Git independientes:

    Agente principal (rama main)
      ├── Subagente 1 (worktree: feature-auth)  → trabaja en autenticacion
      ├── Subagente 2 (worktree: feature-api)   → trabaja en API
      └── Subagente 3 (worktree: fix-tests)     → arregla tests
    

Cada subagente tiene su propia copia del repositorio. No se pisan. Al terminar, sus cambios se pueden mergear.

Cuando usarlo: tareas de código independientes que pueden hacerse en paralelo (features diferentes, fixes en archivos diferentes).

6. Guardrails: que los agentes no se desmanden

Los 5 guardrails obligatorios

1. Max retries + circuit breaker

    MAX_RETRIES = 3
    CIRCUIT_BREAKER_THRESHOLD = 5  # Si falla 5 veces seguidas, parar
    
    async def safe_execute(agent, input, retries=0):
        try:
            return await agent.execute(input)
        except Exception as e:
            if retries >= MAX_RETRIES:
                return fallback_response(e)
            return await safe_execute(agent, input, retries + 1)
    

2. Timeout por tarea

    async def execute_with_timeout(agent, input, timeout_seconds=30):
        try:
            return await asyncio.wait_for(agent.execute(input), timeout=timeout_seconds)
        except asyncio.TimeoutError:
            return {"error": "Timeout", "fallback": True}
    

3. Presupuesto de tokens

    MAX_TOKENS_PER_TASK = 10000
    MAX_COST_PER_DAY_USD = 5.0
    

4. Validación de output

    from pydantic import BaseModel
    
    class ClassificationResult(BaseModel):
        category: str
        priority: str  # P0, P1, P2, P3
        confidence: float  # 0.0 - 1.0
        reasoning: str
    
    # Si el agente devuelve algo que no encaja en el schema, error
    result = ClassificationResult.model_validate(agent_output)
    

5. Human-in-the-loop para acciones criticas

    REQUIRES_APPROVAL = ["send_email", "delete_record", "publish_content", "modify_production"]
    
    async def execute_tool(tool_name, args):
        if tool_name in REQUIRES_APPROVAL:
            approval = await request_human_approval(tool_name, args)
            if not approval:
                return {"status": "rejected_by_human"}
        return await tools[tool_name](**args)
    

7. Patrones anti-agente: lo que NO hacer

8. Lab práctico: Construye tu multi-agente

Instrucciones

Disenha y construye un sistema coordinator + 2 workers. 35 minutos.

Paso 1: Define el caso (5 min)

    Tarea completa: _________________________________
    Worker 1: _________________ [que hace]
    Worker 2: _________________ [que hace]
    Coordinator: decide _________________ y combina _________________
    

Paso 2: Diseña el flujo (10 min)

    INPUT: _________________________________
      ↓
    COORDINATOR: _________________________________
      ↓
      ├── WORKER 1: _________________________________
      │   Tools: _________________________________
      │   Output: _________________________________
      │
      └── WORKER 2: _________________________________
          Tools: _________________________________
          Output: _________________________________
      ↓
    COORDINATOR: combina _________________________________
      ↓
    OUTPUT: _________________________________
    

Paso 3: Implementa (15 min)

Escribe el código mínimo:

• System prompt del coordinator
• System prompt de cada worker
• Al menos 1 tool por worker
• Guardrails: timeout + max retries

Paso 4: Testa (5 min)

• El coordinator reparte trabajo correctamente?
• Los workers producen output útil?
• Los guardrails funcionan (provocar un timeout)?

Entregable de la sesión

Tu sistema multi-agente documentado con diagrama de flujo, prompts y guardrails.

    SISTEMA MULTI-AGENTE
    =====================
    
    Nombre: _________________________________
    Coordinator: _________________________________
    Workers:
      1. _____________ — tools: _____________
      2. _____________ — tools: _____________
    
    Guardrails:
      Max retries: _____
      Timeout: _____ seg
      HITL para: _________________________________
      Presupuesto tokens/dia: _____
    
    Patron: [ ] Secuencial  [ ] Paralelo  [ ] Loop
    

Recursos descargables

1. Patrones de agentes (PDF) — 8 patrones con diagrama, cuando usar, cuando evitar
2. Templates LangGraph/CrewAI (GitHub) — Scaffold coordinator + workers listo para clonar
3. Diagrama de flujos (Notion) — Templates de diagramas para documentar tus agentes

Siguientes pasos

En la siguiente sesión (AB-06: Recursos oficiales vs no oficiales) vas a aprender a navegar la documentación oficial de cada herramienta y a distinguir la información fiable de la que no lo es.

Antes de pasar a AB-06:

• Has disenado un sistema coordinator + 2 workers
• Has implementado al menos 1 tool por worker
• Has probado los guardrails (timeout, retries)

Toolbox — Sesión 05 de 09

IAcademy — iacedemy.com