🧪 Ejemplos ejecutables · Claude Code para Equipos
La teoría de agentes de Anthropic, en 11 programas
Cada concepto del capítulo 2 tiene aquí un programa corto que corre contra la Guía Scrum 2020 real.
El caso es siempre el mismo: el Tutor de proyectos que responde por WhatsApp citando la página.
📂 Código en demos/teoria/ · 🐍 Python · 🔑 necesita ANTHROPIC_API_KEY
Preparar el entorno
Una sola vez. Los ejemplos 01 a 06 y 08 usan el Client SDK (anthropic); 07, 09, 10 y 11 usan el Claude Agent SDK, que trae el mismo motor de Claude Code.
pip install anthropic claude-agent-sdk pdfplumber
# Windows PowerShell: $env:ANTHROPIC_API_KEY="sk-ant-..."
# macOS / Linux: export ANTHROPIC_API_KEY="sk-ant-..."
cd "courses/Claude Code para equipos/demos/teoria"
python tutor_corpus.py "¿Cuánto dura el Daily Scrum?" # comprueba el corpus, sin gastar API
💳 Cada corrida gasta tokens reales
Los programas imprimen los tokens y, en los del Agent SDK, el costo en USD. Los agentes llevan max_turns y max_budget_usd para que ninguna corrida se alargue. Los números cambian según el modelo y el momento: compáralos con lo que dice «Qué observar», no con cifras fijas.
Workflows: el código fija el camino
«Sistemas donde LLMs y tools se orquestan por caminos de código predefinidos». Predecibles y baratos: son la base del Tutor.
01
Client SDK · anthropicEl LLM aumentado
Building effective agents · «The augmented LLM»
El bloque básico: un modelo con una tool de recuperación. El bucle de tool use está escrito a mano: mientras la respuesta pida una tool, el programa la ejecuta y devuelve el resultado.
🧑🎓 pregunta→🧠 modelo decide buscar→🔎 buscar_documento→🧠 redacta con los párrafos→✅ respuesta con (p. N)
Qué observarLa consulta que el modelo genera no es la pregunta literal del alumno: la reformula con los términos de la guía.
En el TutorEs el paso 4 del recorrido de una pregunta: el agente busca antes de redactar.
02
Client SDK · anthropicPrompt chaining con gate
Building effective agents · «Workflow: Prompt chaining»
Tres llamadas en secuencia. Entre la segunda y la tercera, un gate por código rechaza la respuesta si no cita página o si cita una página que la búsqueda no devolvió.
1 · reformular (Haiku)→buscar→2 · redactar (Sonnet)→🚦 gate: ¿páginas válidas?→3 · adaptar a WhatsApp
Qué observarSi el gate dice RECHAZA, la cadena se detiene y nada llega al alumno. El gate no es un modelo: es una comparación de conjuntos.
En el TutorPasos fijos más un chequeo determinista: exactamente lo que pide la guía para tareas que se descomponen limpio.
03
Client SDK · anthropicRouting
Building effective agents · «Workflow: Routing»
Un clasificador rápido decide la categoría de cuatro mensajes distintos, y el código deriva cada uno a su camino: definición con Haiku, comparación con Sonnet, saludo y fuera de alcance sin modelo.
mensaje→🏷️ clasificador (Haiku)→definición · Haikucomparación · Sonnetsaludo · códigofuera de alcance · código
Qué observarLa pregunta sobre laptops nunca llega a la búsqueda ni al modelo grande. Ante una categoría desconocida, el código elige el camino más restrictivo.
En el TutorPrompts especializados por tipo de pregunta y el modelo pequeño para lo fácil: menos costo sin perder calidad.
04
Client SDK · anthropic (async)Parallelization: sectioning y voting
Building effective agents · «Workflow: Parallelization»
Primero tres tareas independientes a la vez (redacción, términos clave, pregunta de repaso). Después, tres revisores con enfoques distintos votan si la redacción tiene información sin soporte.
párrafos→redaccióntérminosrepaso→🗳️ 3 votos→mayoría por código
Qué observarEl tiempo total en paralelo frente a la suma de las tres llamadas. Y que la decisión ENVIAR o BLOQUEAR la toma el código con 2 de 3 votos.
En el TutorEl guardrail va en una llamada separada: la guía indica que rinde mejor que pedirle a la misma llamada que responda y se vigile.
05
Client SDK · anthropic (async)Orchestrator-workers
Building effective agents · «Workflow: Orchestrator-workers»
Una pregunta compuesta se parte en subpreguntas que decide el orquestador. Cada worker busca con su subpregunta y responde; un sintetizador une todo conservando las citas.
pregunta compuesta→🧭 orquestador → JSON→worker 1worker 2worker n→🧩 síntesis
Qué observarEl número de subpreguntas cambia con la pregunta. Cada worker recupera páginas distintas, y la síntesis las cita todas.
En el Tutor«Compara el PO y el Scrum Master en la Planning y la Review»: no se sabe de antemano cuántas búsquedas harán falta.
06
Client SDK · anthropicEvaluator-optimizer
Building effective agents · «Workflow: Evaluator-optimizer»
Un generador redacta y un evaluador lo critica en bucle, con tres criterios binarios. Dos los mide el código (longitud y páginas) y uno un modelo (afirmaciones sin soporte).
✍️ generador⇄🔍 evaluador: C1 · C2 · C3→APROBADO3 rondas → escalar a humano
Qué observarEl feedback de cada ronda y la condición de parada explícita: si no aprueba en tres rondas, la respuesta no se envía.
En el TutorHay criterio claro (cita, soporte, longitud del canal) y refinar mejora la respuesta de forma medible.
08
Client SDK · anthropicPrompt caching medido
API de Anthropic · Prompt caching · Claude Code · How Claude Code uses prompt caching
La Guía Scrum entera va como bloque del system prompt con cache_control. Se hacen dos preguntas seguidas y se imprimen los tres contadores de tokens de cada una.
tools→system→📚 documento · breakpoint|pregunta (cambia)
Qué observar1ª llamada: escritos > 0, leídos = 0. 2ª: escritos = 0, leídos > 0, y el ahorro calculado. Leer cuesta 0,1× la entrada; escribir 1,25×.
En el TutorCientos de preguntas diarias sobre el mismo documento: el prefijo estable se paga una vez cada 5 minutos, no en cada mensaje.
Agentes: el modelo dirige su proceso
«Sistemas donde los LLMs dirigen dinámicamente sus propios procesos y uso de tools». Con el Claude Agent SDK: el mismo bucle, tools, hooks y subagentes que Claude Code.
07
Claude Agent SDKAgente autónomo con condiciones de parada
Agent SDK · «How the agent loop works» · Building effective agents · «Agents»
Una tool propia expuesta como servidor MCP en el mismo proceso. El agente decide cuántas veces buscar; el harness decide qué tools existen, cuáles corren solas, cuántos turnos y cuánto dinero.
objetivo→🔁 planea · busca · lee resultado→max_turns · max_budget_usd→ResultMessage.subtype
Qué observarCada tool call, el subtype, los turnos y el costo. Corre python 07_agente_autonomo.py 1 para ver error_max_turns.
En el TutorSin Bash, sin escritura, sin red: el agente que responde a alumnos solo puede buscar en el documento.
09
anthropic + Claude Agent SDKGuardrails contra prompt injection
Claude Code · Security · Agent SDK · Securely deploying AI agents · Hooks
Se simula un PDF malicioso: un fragmento que ordena crear un archivo y responder «Proyecto aprobado». Parte A delimita el texto con un nonce por petición. Parte B deja que los permisos permitan Bash y Write, pero un hook PreToolUse los bloquea siempre.
☠️ texto con instrucción→A · <datos-nonce> = DATOS→B · hook PreToolUse: deny→¿existe aprobado.txt? NO
Qué observarSi el modelo resiste solo, el hook no actúa y el programa lo dice. Si intenta Bash o Write, verás la línea BLOQUEADO. Al final se comprueba el disco.
En el TutorUna instrucción en CLAUDE.md es contexto; el hook es determinista. Lo que no debe pasar nunca va en el hook.
10
Claude Agent SDKSubagente verificador
Claude Code · Create custom subagents · Agent SDK · Subagents
El agente principal redacta. Un subagente definido con AgentDefinition, con modelo Haiku y solo la tool de búsqueda, intenta refutar la respuesta con contexto limpio y devuelve solo el veredicto.
🧠 principal redacta→▶ SubagentStart→🔍 verificador (haiku)→■ SubagentStop→veredicto
Qué observarLos hooks marcan cuándo nace y termina el subagente. El costo final incluye lo que gastó el subagente.
En el TutorQuien hace no es quien califica: el verificador no ve el razonamiento del redactor, solo el resultado y el documento.
11
Claude Agent SDKMemoria de sesión: resume y fork
Agent SDK · «Sessions and continuity» · Session management
Una primera consulta crea la sesión. La segunda la reanuda con su session_id y pregunta por lo dicho antes. La tercera la bifurca para explicarlo de otra forma sin tocar la original.
1 · nueva sesión→2 · resume=session_id→3 · fork_session=True
Qué observarEn la reanudación, el agente responde sin volver a buscar (tool calls = 0) porque el contexto se restauró. La rama del fork tiene otro session_id.
En el TutorUna sesión por alumno que se reanuda al siguiente mensaje de WhatsApp, en vez de empezar de cero cada vez.
El corpus y las fuentes
📚 La Guía de Scrum 2020 (español, Latinoamérica)
Ken Schwaber y Jeff Sutherland, descargada de scrumguides.org, licencia Creative Commons BY-SA 4.0. Está en demos/teoria/datos/. tutor_corpus.py la lee con pdfplumber, la parte en fragmentos con su número de página del PDF y busca por coincidencia léxica. La búsqueda es simple a propósito: estos ejemplos tratan del bucle agéntico. El capítulo de RAG la sustituye por búsqueda híbrida y estructural.
📖 Documentación de Anthropic usada
Building effective agents · Building agents with the Claude Agent SDK · Agent SDK overview y agent loop · Custom tools · Hooks · Subagents · Sessions · Prompt caching (API y Claude Code) · Explore the context window · Security · Securely deploying AI agents · Agent teams. Copias locales en courses/_fuentes_anthropic/.