Orientación · el toolkit del taller

5 minutos de contexto antes de Lesson 01. Si conocés todo lo de abajo podés saltearlo, pero mirá al menos la tabla final: define el vocabulario que vamos a usar durante los 90 min.

System map · el loop del deep agent

Todo el taller construye este loop. Cuando el agente recibe una pregunta que no puede responder, entra en modo aprendizaje: delega a un sub-agent que le escribe un SKILL.md, lo carga en el registry, y lo invoca. La respuesta final tiene evidencia trazable en .receipts/.

flowchart TB
    Q(["<b>01 · Pregunta de negocio</b><br/>¿qué cliente creció más entre Q2 y Q3?"])
    HARN(["<b>02 · DeepAgent harness</b><br/>planning · virtual FS · sub-agents · HITL"])
    SA(["<b>03 · skill_author</b><br/>sub-agent que escribe .skills/*/SKILL.md<br/>siguiendo agentskills.io"])
    REG(["<b>04 · Skill registry</b><br/>discover · validate (Pydantic) · inject as tool"])
    COG(["<b>05 · Cognee sobre Neo4j</b><br/>ingest data/acme · cognify · search INSIGHTS"])
    SM(["<b>06 · State machine</b><br/>raw → learning → answering → refining"])
    REC["<b>Durable evidence</b><br/>.receipts/lifecycle.jsonl"]
    ANS["<b>Respuesta con evidencia</b><br/>value · source · confidence"]

    Q --> HARN
    HARN -- gap detectado --> SA
    SA --> REG
    REG -- tool disponible --> HARN
    HARN -- skill invoke --> COG
    COG -- resultados --> HARN
    HARN --> SM
    SM -- transition event --> REC
    SM --> ANS

    classDef highlight fill:#1e2d4a,stroke:#6b8cb8,stroke-width:2px
    class SA,COG highlight

Los dos bloques resaltados (skill_author y Cognee) son las novedades del taller. Todo lo demás son primitivas que probablemente ya conocés en otro formato.

Por qué esta parte importa

Un DeepAgent no es "un LLM que hace cosas". Es una arquitectura con al menos 4 capas: el modelo, el harness que lo hostea, la memoria persistente, y los skills que decide invocar. Si mezclás las capas mentalmente, el debugging del taller se vuelve confuso.

Esta página nombra cada pieza — y explica por qué la elegimos a ella y no la alternativa obvia.

Capa 1 · Modelo · OpenRouter + Anthropic Claude

Qué es: OpenRouter es un gateway que unifica ~100 modelos (Anthropic, OpenAI, Meta, Mistral, DeepSeek…) detrás de la misma API (compatible con OpenAI SDK).

Por qué acá: - Cambiar de claude-haiku-4.5 a gpt-4o-mini es una env var (OPENROUTER_MODEL), no un refactor. - Un solo API key para todo el ecosistema. Un solo billing. - Mientras el modelo esté detrás de una interfaz ChatCompletion, el resto del stack no cambia.

Default del taller: anthropic/claude-haiku-4.5 — rápido, barato (~USD 0.20 por sesión completa), y suficiente para skill generation.

Capa 2 · Harness · DeepAgents (sobre LangChain + LangGraph)

Qué es: DeepAgents es la librería de LangChain para armar agentes que planifican, delegan a sub-agentes, usan un filesystem virtual, y piden aprobación humana. Está construido sobre LangGraph (state graph) y usa modelos vía LangChain. El repo público está en langchain-ai/deepagents.

Las 4 primitivas de DeepAgents (las 4 herramientas que ya te da sin escribir código):

Por qué DeepAgents y no LangChain crudo o LangGraph directo: - LangChain crudo te da LLM + tools. Perfecto para "responde con esta función". Insuficiente cuando el agente tiene que decidir la secuencia de acciones. - LangGraph te obliga a modelar cada nodo/edge del state machine. Poder total, pero mucho boilerplate para el patrón "loop de razonamiento". - DeepAgents es la capa opinada: te impone planning + FS + sub-agents porque son los patrones que emergieron trabajando con Claude Code y Codex.

Nota polyglot — Si venís del ecosistema Node/TS, DeepAgents cumple un rol parecido a Pi o Herdr: es el shell del agente, no el agente en sí. Pi es un agent runtime (con su propia CLI); Herdr es el multiplexer terminal que hostea al agente y le da paneles visibles al operador. En Python, DeepAgents es la referencia obvia; el patrón conceptual es el mismo.

Capa 3 · Memoria · Cognee sobre Neo4j

Qué es: Cognee toma texto no estructurado (.md, .pdf, .txt) y lo convierte en un grafo de conocimiento con entidades + relaciones. La consulta usa embeddings (LanceDB) + búsqueda en grafo (Neo4j o Kuzu).

Por qué grafo y no solo vectores: - RAG puro (vector-only): "¿cuánto facturó Café del Valle en Q3?" → recupera chunks de invoices-q3.md → el LLM extrae. Falla cuando la respuesta requiere join (ej: cliente × trimestre × servicio). - Grafo + vectores: el grafo captura relaciones (Cliente → factura → concepto → monto → fecha). El LLM puede recorrer aristas para responder queries que un vector store solo no responde.

Backend en el taller: Neo4j en Docker local (academy cognee up) o instancia remota pre-cargada. Kuzu embebido es alternativa 0-infra si Docker no arranca — está soportado pero no es el default.

Capa 4 · Lifecycle · python-statemachine

Qué es: python-statemachine — DSL Python para state machines con transiciones explícitas y guards.

Por qué acá: sin transiciones explícitas, un agente puede: - Quedar en loop infinito de "refinamiento" (nunca converge). - Saltar de raw a answering sin haber creado el skill (respuesta sin evidencia). - No tener stop reason auditable cuando falla.

En Lesson 05 modelamos el ciclo raw → learning → answering → refining → escalated como state machine, y cada transición emite un receipt en .receipts/lifecycle.jsonl.

Capa 5 · Reliability · Ruff + mypy --strict + pytest

El gate único: academy check corre las 4 cosas.

Filosofía: más severo que lo que un humano se autoimpondría — pero exactamente lo que necesita un agente para no tomar shortcuts.

Capa 6 · Contrato de skills · agentskills.io

Qué es: agentskills.io — spec pública para archivos SKILL.md que cualquier agente puede leer y ejecutar.

Por qué formato markdown y no una función Python:

Un skill puede invocar tools, pero no es un tool. Es la receta que sabe cuándo usarlos.

Tabla resumen

Convención de nombres — glosario mínimo

Términos que vamos a usar todo el taller:

• Rig — la infra del workshop (pyproject.toml, scripts/check.sh, academy CLI). Es lo que garantiza que puedas correr las lessons.
• Receipt — evento JSON append-only en .receipts/*.jsonl. Prueba lo que hizo el agente.
• Gate — chequeo que detiene la lección si está rojo. academy check es el gate único.
• Checkpoint — checklist de evidencia al final de cada lesson. Lo tickeás en el micrositio (localStorage) o con academy validate N.
• Skill — archivo SKILL.md con procedimiento markdown que el LLM ejecuta.
• Tool — función Python que el LLM invoca con argumentos.
• Sub-agent — instancia paralela de DeepAgents con prompt especializado. Ej: skill_author.
• State machine — máquina de estados explícita del lifecycle del agente.

Listo. Empezá con Lesson 01 — Rules before code.