Phase 14 - Lesson 17

Claude Agent SDK: Subagentes y Session Store

Claude Agent SDK es la versión en biblioteca del arnés (harness) de Claude Code. Herramientas integradas, subagentes para aislamiento de contexto, hooks, propagación de trazas W3C, paridad de Session Store. Claude Managed Agents es la alternativa hospedada para trabajos asíncronos de larga duración.

Tipo: Aprender + Construir Idiomas: Python (stdlib) Prerrequisitos: Phase 14 · 01 (Agent Loop), Phase 14 · 10 (Skill Libraries) Tiempo: ~75 minutos

Objetivos de Aprendizaje

• Explicar la diferencia entre el Anthropic Client SDK (API sin procesar) y el Claude Agent SDK (forma del arnés/harness).
• Describir subagentes —paralelización y aislamiento de contexto— y cuándo recurrir a ellos.
• Nombrar la interfaz de Session Store del SDK de Python (append, load, list_sessions, delete, list_subkeys) y el papel de --session-mirror.
• Implementar un arnés (harness) con stdlib con herramientas integradas, inicio de subagentes con contexto aislado, hooks de ciclo de vida y un Session Store.

El Problema

Una API de LLM básica solo ofrece un viaje de ida y vuelta. Un agente de producción necesita ejecución de herramientas, servidores MCP, hooks de ciclo de vida, inicio de subagentes, persistencia de sesión y propagación de trazas. Claude Agent SDK entrega esta estructura como una biblioteca —el mismo arnés que usa Claude Code, expuesto para agentes personalizados.

El Concepto

Client SDK vs Agent SDK

• Client SDK (anthropic). API de mensajes sin procesar. Eres el dueño del bucle, las herramientas y el estado.
• Agent SDK (claude-agent-sdk). Ejecución de herramientas integrada, conexiones MCP, hooks, inicio de subagentes, Session Store. El bucle de Claude Code como una biblioteca.

Herramientas integradas

El SDK incluye más de 10 herramientas listas para usar: lectura/escritura de archivos, shell, grep, glob, extracción web (fetch) y más. Las herramientas personalizadas se registran a través de la interfaz estándar de esquema de herramientas (tool-schema).

Subagentes

Dos propósitos documentados por Anthropic:

1. Paralelización. Ejecutar trabajo independiente de forma concurrente. "Buscar el archivo de prueba para cada uno de estos 20 módulos" representa 20 tareas paralelas de subagentes.
2. Aislamiento de contexto. Los subagentes utilizan su propia ventana de contexto; solo los resultados regresan al orquestador. Se preserva el límite de tokens (budget) del orquestador.

Adiciones recientes al SDK de Python: list_subagents(), get_subagent_messages() para leer transcripciones de subagentes.

Session Store

Paridad de protocolo con TypeScript:

• append(session_id, message) — agrega un turno.
• load(session_id) — restaura la conversación.
• list_sessions() — enumera las sesiones.
• delete(session_id) — elimina con efecto cascada hacia las sesiones de subagentes.
• list_subkeys(session_id) — enumera las claves de los subagentes.

--session-mirror (bandera de CLI) refleja la transcripción en un archivo externo a medida que se transmite (streaming), para depuración.

Hooks

Hooks de ciclo de vida que puedes registrar:

• PreToolUse, PostToolUse — controlan o auditan las llamadas a herramientas.
• SessionStart, SessionEnd — realizan la inicialización y el cierre.
• UserPromptSubmit — actúan sobre la entrada del usuario antes de que el modelo la vea.
• PreCompact — se ejecutan antes de la compactación de contexto.
• Stop — realizan la limpieza al salir del agente.
• Notification — alertas de canal secundario (side-channel).

Los hooks son el mecanismo por el cual pro-workflow (referencia del plan de estudios de la Fase 14) y sistemas similares añaden comportamiento transversal.

Contexto de traza W3C

Los spans de OTel activos en el llamador se propagan al subproceso de CLI a través de cabeceras de contexto de traza W3C. Toda la traza de multiproceso se muestra como una sola traza en tu backend.

Claude Managed Agents

La alternativa hospedada (cabecera beta managed-agents-2026-04-01). Trabajo asíncrono de larga duración, almacenamiento en caché de prompts integrado, compactación integrada. Cambia control por infraestructura administrada.

Dónde este patrón puede fallar

• Exceso de subagentes. Iniciar 100 subagentes para 100 tareas minúsculas. La sobrecarga (overhead) domina. En su lugar, procesa en lotes (batch).
• Exceso de hooks (hook creep). Cada equipo añade hooks; el tiempo de inicio se infla. Revisa los hooks trimestralmente.
• Acumulación de sesiones. Las sesiones se acumulan y el tamaño crece. Utiliza list_sessions con una política de expiración.

Constrúyelo

code/main.py implementa la estructura del SDK en la biblioteca estándar (stdlib):

• Tool, ToolRegistry con read_file, write_file, list_dir integrados.
• Subagent — contexto privado, ejecución aislada, resultados devueltos.
• SessionStore — append, load, list, delete, list_subkeys.
• Hooks — pre_tool_use, post_tool_use, session_start, session_end.
• Una demostración: el agente principal inicia 3 subagentes en paralelo (cada uno aislado), agrega los resultados y persiste la sesión.

Ejecútalo:

python3 code/main.py

La traza muestra el aislamiento de contexto del subagente (el tamaño del contexto del orquestador permanece limitado), la ejecución de hooks y la persistencia de la sesión.

Úsalo

• Claude Agent SDK para productos enfocados en Claude que desean la forma de arnés (harness) de Claude Code.
• Claude Managed Agents para trabajo asíncrono de larga duración hospedado.
• OpenAI Agents SDK (Lección 16) para equivalentes enfocados en OpenAI.
• LangGraph + herramientas personalizadas si prefieres la máquina de estados en forma de grafo.

Envíalo a Producción

outputs/skill-claude-agent-scaffold.md estructura una aplicación Claude Agent SDK con subagentes, hooks, Session Store, conexión de servidor MCP y propagación de trazas W3C.

Ejercicios

1. Añade un generador de subagentes que agrupe 20 tareas en lotes de 5 subagentes paralelos. Mide el tamaño del contexto del orquestador frente a un subagente por tarea.
2. Implementa un hook PreToolUse que limite la tasa de llamadas a write_file (5 por minuto por sesión). Monitorea el comportamiento.
3. Conecta list_subkeys para representar un árbol de subagentes. ¿Cómo se ve el anidamiento profundo?
4. Migra el prototipo al paquete real de Python claude-agent-sdk. ¿Qué cambia en el registro de herramientas?
5. Lee la documentación de Claude Managed Agents. ¿Cuándo cambiarías de hospedaje propio (self-hosted) a administrado?

Términos Clave

Lecturas Adicionales

• Descripción general de Claude Agent SDK — la versión en biblioteca de Claude Code
• Anthropic, Creación de agentes con el Claude Agent SDK — patrones de producción
• Descripción general de Claude Managed Agents — alternativa hospedada
• OpenAI Agents SDK — contraparte