Claude Agent SDK: El Framework que Invalida Todo lo que Sabías sobre Agentes IA
Tutorial práctico del Claude Agent SDK: aprende a crear agentes IA en 10 líneas de código, sin LangChain ni grafos. Ejemplos reales con @tool, sub-agentes y sandboxing.
El Stack de Agentes que Aprendiste el Año Pasado Ya Está Obsoleto
¿Y si te dijera que LangChain, CrewAI y los DAGs que montaste con tanto esfuerzo son infraestructura innecesaria?
El Claude Agent SDK ejecuta agentes completos en 10 líneas de código. Sin pipelines. Sin grafos de estado. Sin gestión manual de contexto.
*Y funciona mejor. *
La mayoría asume que construir agentes requiere orquestar explícitamente herramientas, definir grafos DAG y gestionar memoria manualmente. Es lo que nos han vendido durante dos años.
El Claude Agent SDK demuestra lo contrario: el modelo más efectivo es delegar la orquestación al propio LLM, usando un bucle de cómputo simple donde Claude decide el flujo.
No necesitas LangChain. No necesitas middleware de agentes. El SDK elimina la capa de abstracción que la industria había dado por sentada.
---
Por Qué el Modelo Tradicional Está Roto
Frameworks como LangChain asumen algo fundamental: que el desarrollador debe predecir y codificar cada ruta posible del agente.
Grafos, DAGs, cadenas, nodos condicionales. Modelas el flujo como un mapa de carreteras donde cada intersección está predefinida.
❌ Enfoque tradicional (LangChain/CrewAI):
Defines un grafo de estado con nodos y aristas
Codificas la lógica de transición entre cada nodo
Gestionas manualmente el contexto compartido
Añadir una herramienta nueva implica redibujar el grafo
Cambiar el orden de operaciones requiere reescribir el DAG
✅ Enfoque del Claude Agent SDK:
Decoras funciones Python con `@tool`
Creas el agente y le pasas las herramientas
Claude decide el flujo en tiempo de ejecución
Añadir una herramienta es una línea: `@tool`
El orden de operaciones lo determina el modelo
*La diferencia no es técnica. Es filosófica. *
LangChain asume que el humano es mejor orquestador que el LLM. El Claude Agent SDK asume lo contrario: que el modelo, con el contexto adecuado, sabe mejor que tú qué herramienta llamar y en qué orden.
Y los datos lo respaldan. El SDK reduce el código boilerplate de gestión de estado en un 70-80% comparado con enfoques tradicionales.
---
El Bucle Agente-Tools: La Mecánica Interna
El Claude Agent SDK no ejecuta pipelines lineales. Implementa lo que Anthropic llama un compute loop: Claude llama herramientas, evalúa resultados, decide la siguiente acción, y repite.
No es un DAG. Es un bucle vivo donde el modelo es el orquestador.
```
Claude recibe input
→ decide qué herramienta llamar
→ ejecuta la herramienta
→ evalúa el resultado
→ ¿Tarea completada?
→ Sí: devuelve respuesta final
→ No: vuelve a decidir qué herramienta llamar
```
Esto no es magia. Es un patrón que existía antes, pero que requería que implementaras manualmente el bucle, la gestión de contexto, el sandboxing y el manejo de errores.
El SDK te da todo eso empaquetado en una llamada.
---
Tutorial Paso a Paso con Claude Agent SDK
Vamos al código. Este es un claude agent sdk tutorial práctico que puedes ejecutar ahora mismo.
1. Instalación y Configuración
```python
Instala el SDK
pip install claude-agent-sdk
Configura tu API key
export ANTHROPIC_API_KEY="sk-ant-..."
```
El SDK requiere Python 3.10+. Nada más.
2. Tu Primer Agente con Herramientas Decoradas
Aquí está la magia. Defines herramientas como funciones Python con un decorador `@tool`, y el tipado de parámetros genera el esquema JSON automáticamente.
```python
from claude_agent_sdk import Client, tool
@tool
def buscar_en_web(consulta: str) -> str:
"""Busca información en la web y devuelve resultados resumidos."""
Aquí iría tu lógica de búsqueda
return f"Resultados para: {consulta}"
@tool
def leer_archivo(ruta: str) -> str:
"""Lee el contenido de un archivo del sistema."""
with open(ruta, 'r') as f:
return f.read()
@tool
def ejecutar_codigo_python(codigo: str) -> str:
"""Ejecuta código Python en un entorno sandboxeado."""
El sandboxing es nativo del SDK
return exec_sandboxed(codigo)
Crear el agente
cliente = Client(api_key="...")
agente = cliente.configure(
tools=[buscar_en_web, leer_archivo, ejecutar_codigo_python],
model="claude-opus-4-5-2026"
)
Ejecutar el bucle agente
respuesta = agente.run(
"Busca información sobre agentes IA, "
"lee el archivo notas.md del proyecto, "
"y genera un resumen ejecutivo en Python"
)
print(respuesta.text)
```
10 líneas. Sin grafos. Sin estados. Sin pipelines.
El SDK maneja automáticamente el ciclo de invocación → respuesta → herramienta → evaluación. Tú solo decoras funciones y dejas que Claude decida.
3. El Patrón de Sub-Agentes (Custodial Agent)
Para tareas complejas, el SDK implementa handoffs entre agentes como primitiva nativa. Un agente principal puede delegar subtareas a agentes especializados con contextos independientes pero compartidos.
```python
from claude_agent_sdk import Client, tool, agent_handoff
@tool
def buscar_en_web(consulta: str) -> str:
return f"Resultados web: {consulta}"
@tool
def analizar_documento(texto: str) -> str:
return f"Análisis: {texto}"
Agente especializado en investigación
agente_investigador = cliente.configure(
tools=[buscar_en_web],
name="investigador",
instructions="Eres un investigador. Buscas información precisa en la web."
)
Agente especializado en análisis
agente_analista = cliente.configure(
tools=[analizar_documento],
name="analista",
instructions="Eres un analista. Extraes insights de documentos."
)
Agente principal con capacidad de handoff
agente_principal = cliente.configure(
tools=[agent_handoff(agente_investigador),
agent_handoff(agente_analista)],
name="orquestador",
instructions=(
"Eres un orquestador. Para investigación, delega al investigador. "
"Para análisis de documentos, delega al analista. "
"Consolida los resultados y presenta el informe final."
)
)
respuesta = agente_principal.run(
"Investiga las últimas tendencias en AI Agents, "
"analiza el whitepaper de Anthropic, "
"y genera un informe ejecutivo completo."
)
```
El patrón custodial agent permite que Claude gestione sub-agentes para tareas paralelas. En otros frameworks, esto requeriría colas de mensajes, pools de workers y lógica de consolidación.
Aquí es una primitiva nativa.
4. Ejecución Sandboxeada de Código
El sandboxing es un punto ciego en la mayoría de alternativas. Mientras que OpenAI Code Interpreter es una caja negra SaaS, el SDK de Claude permite ejecución local con sandboxing integrado.
```python
@tool
def ejecutar_bash(comando: str) -> str:
"""Ejecuta un comando bash en entorno sandboxeado."""
El sandbox limita permisos, red y sistema de archivos
return exec_bash_sandboxed(comando)
@tool
def analizar_logs(ruta_log: str) -> dict:
"""Analiza un archivo de logs y devuelve métricas."""
with open(ruta_log, 'r') as f:
contenido = f.read()
return {"lineas": len(contenido.split("\n")),
"tamano_kb": len(contenido) / 1024}
agente_devops = cliente.configure(
tools=[ejecutar_bash, analizar_logs, leer_archivo],
sandbox=True # sandboxing global activado
)
agente_devops.run(
"Analiza los logs del servidor en /var/log/nginx/, "
"identifica los 5 errores más frecuentes, "
"y genera un script de bash para rotar esos logs automáticamente."
)
```
El modelo decide dinámicamente: leer archivo, ejecutar script bash, analizar logs. Sin pipeline fijo. Sin orden predefinido.
---
El Ahorro Real No Está en las Líneas de Código
Está en el mantenimiento.
En un sistema con LangChain, cambiar el orden de operaciones o añadir una nueva herramienta requiere reescribir el grafo. Cada cambio implica:
Modificar la definición del DAG
Actualizar las transiciones de estado
Re-validar que el flujo completo funciona
En el SDK de Claude, solo añades la función con `@tool` y el modelo decide cuándo usarla.
*Eso cambia la velocidad de iteración. *
En prototipado, la diferencia es brutal. Puedes pasar de "idea" a "agente funcionando" en minutos. En producción, reduce drásticamente el coste de añadir nuevas capacidades.
---
Dónde el SDK Falla (y Hay que Reconocerlo)
Este modelo funciona brillantemente para tareas exploratorias y de composición dinámica: investigación, análisis de datos, asistentes internos, generación de informes.
Pero falla cuando necesitas predictibilidad estricta.
Si tu caso de uso requiere que el agente siga EXACTAMENTE el mismo flujo cada vez —procesamiento regulatorio, transacciones financieras, sistemas de compliance— el enfoque de "Claude decide" introduce variabilidad indeseada.
❌ Cuándo NO usar Claude Agent SDK:
Flujos regulatorios donde cada paso debe auditarse idénticamente
Sistemas de trading o procesamiento de pagos
Cualquier proceso donde la desviación del flujo tenga coste legal o financiero
✅ Cuándo SÍ usar Claude Agent SDK:
Investigación y análisis exploratorio
Asistentes internos de productividad
Generación y procesamiento de contenido
Prototipado rápido de nuevas capacidades
Automatización de tareas con múltiples herramientas
En esos casos, un DAG fijo sigue siendo superior. El SDK no es bala de plata. Es una herramienta para un tipo específico de problema.
---
El Patrón de Orquestación Delegada
Llamo a esto El Patrón de Orquestación Delegada: programas las herramientas, defines los límites de seguridad, y dejas que el modelo decida el flujo.
Los pasos son:
1. Define herramientas granulares — cada `@tool` debe hacer una cosa y hacerla bien
2. Configura sandboxing — el SDK ejecuta código de forma segura, úsalo
3. Usa sub-agentes para especialización — delega investigación, análisis y generación a agentes con instrucciones específicas
4. No luches contra el modelo — si necesitas predictibilidad estricta, usa un DAG. Si necesitas flexibilidad, usa el SDK
5. Itera rápido — añade herramientas y deja que Claude descubra cómo combinarlas
---
Lo Que Nadie Te Dice
La objeción más común: "Darle al LLM control del flujo es peligroso. Prefiero pipelines predecibles que pueda auditar."
Es una crítica válida. En entornos regulados, los DAGs fijos tienen sentido. Pero la mayoría de casos de uso —investigación, análisis, asistentes internos— se benefician más de la flexibilidad que de la predictibilidad.
Otra objeción: "Esto solo funciona con Claude. ¿Qué pasa si quiero usar GPT-4 o Llama?"
El SDK está acoplado a Anthropic, sí. Pero el patrón que implementa —bucle agente-tools con orquestación delegada al LLM— es aplicable a cualquier modelo. De hecho, OpenAI Agents SDK usa handoffs similares. El valor real del artículo está en mostrar el patrón, no el vendor lock-in.
---
Resumen y Próximos Pasos
El Claude Agent SDK no es un framework más. Es un cambio de paradigma:
❌ Antes: Programabas el flujo, y las herramientas eran secundarias
✅ Ahora: Programas las herramientas, y el modelo programa el flujo
Esto reduce drásticamente el boilerplate, acelera la iteración y te permite construir agentes que se adaptan dinámicamente a contextos que no anticipaste.
Los takeaways:
Instala con `pip install claude-agent-sdk`
Usa `@tool` para convertir cualquier función Python en herramienta
El bucle agente-tools es nativo — no necesitas gestionar estado manualmente
Implementa sub-agentes con `agent_handoff()` para tareas complejas
Reconoce cuándo NO usarlo: predictibilidad estricta requiere DAGs
El año que viene, cuando mires atrás y veas el stack de agentes que montaste en 2025, te preguntarás por qué perdiste tanto tiempo dibujando grafos.
*El futuro de los agentes no es programar flujos. Es programar herramientas y dejar que el modelo descubra el camino. *
Lee el artículo completo en brianmenagomez.com
Más sobre mis servicios en brianmenagomez.com
Herramientas: Conversor IAE CNAE · Gestorias cerca de ti · Calculadora IRPF