Llevo 4 meses construyendo agentes de IA para mi negocio. Claude Code es mi herramienta principal — lo uso para todo, desde el blog hasta gestionar código. Pero hay tareas donde necesitas algo que Claude Code no te da: un agente custom, integrado en tu sistema, que haga exactamente lo que tú defines.
Para eso existe Claude Agent SDK. La librería Python de Anthropic que te permite construir agentes que razonan, llaman a herramientas y actúan en bucle hasta completar una tarea. Sin frameworks pesados, sin dependencias infinitas, sin magia negra.
Hoy te enseño el patrón exacto que uso para crear agentes con el SDK. Con código real, costes reales, y los errores que cometí para que tú no los cometas.
Qué es Claude Agent SDK (y qué no es)
- Claude Agent SDK
- Claude Agent SDK es el kit de desarrollo en Python de Anthropic que permite crear agentes de IA autónomos basados en Claude. El agente recibe una tarea, razona sobre ella, llama a herramientas externas y repite el ciclo hasta resolverla. A diferencia de un chatbot, el agente toma decisiones no lineales y ejecuta acciones reales sobre APIs, archivos y bases de datos.
Claude Agent SDK es la librería oficial de Anthropic para Python. Se instala con pip install anthropic y te da acceso directo a los modelos Claude a través de su API. Pero la gracia no está en hacer llamadas sueltas a la API — está en el patrón de agente que puedes construir encima.
Un agente construido con el SDK funciona así: recibe una tarea, llama a Claude para razonar sobre ella, Claude decide si necesita usar alguna herramienta (buscar datos, leer un archivo, llamar a una API), ejecuta esa herramienta, devuelve el resultado a Claude, y Claude sigue razonando. Este bucle se repite hasta que la tarea está completa.
Lo que NO es: no es Claude Code. Claude Code es una herramienta lista para usar con terminal, acceso a archivos, y un montón de funcionalidad integrada. El SDK es más bajo nivel — tú construyes tu agente desde cero. Más trabajo, pero control total sobre cada decisión. Si ya leíste la comparativa OpenClaw vs LangGraph vs Claude Agent SDK, sabrás que cada herramienta tiene su sitio.
La arquitectura es limpia: tu código Python orquesta el bucle, el SDK gestiona las llamadas a la API de Anthropic, y Claude decide cuándo y cómo usar las herramientas que tú defines. No hay capas intermedias ni abstracciones innecesarias. Todo lo que pasa entre tu código y la respuesta final es visible y debuggeable.
Instalación y configuración en 5 minutos
La instalación es una línea. Una. No diecisiete.
pip install anthropic
Una sola dependencia. Nada de requirements.txt con 47 paquetes. Nada de conflictos de versiones. Si vienes de LangChain o LangGraph, esto te va a parecer un alivio brutal.
Para configurar el cliente, necesitas tu API key de Anthropic. La consigues en console.anthropic.com, apartado API Keys:
import anthropic
client = anthropic.Anthropic(api_key="tu-api-key")
En producción, la API key va en variable de entorno (ANTHROPIC_API_KEY) y el SDK la detecta automáticamente sin que escribas nada. No la metas hardcodeada en el código — error de novato que cometí el primer día y casi subo a GitHub con la key a la vista. Lección aprendida.
Con el cliente configurado ya puedes hacer tu primera llamada:
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[
{"role": "user", "content": "¿Qué es un agente de IA en 30 palabras?"}
]
)
print(response.content[0].text)
Pero una llamada suelta no es un agente. Lo que convierte esto en agente es el bucle y las herramientas. Que es donde empieza lo interesante.
El patrón del bucle agente: la clave de todo
Este es el concepto clave. Un agente no es una llamada a Claude — es un bucle de llamadas donde Claude decide el siguiente paso en cada iteración. Es lo que diferencia un agente de un chatbot simple o de un flujo determinista en n8n.
El patrón funciona así: envías la tarea a Claude junto con las herramientas disponibles. Claude analiza la tarea y decide si necesita usar alguna herramienta. Si sí, te devuelve un tool_use con los parámetros. Ejecutas la herramienta en tu código, devuelves el resultado a Claude, y el bucle continúa. Claude sigue razonando con la información nueva hasta que da la respuesta final.
En código, el bucle completo son unas 40 líneas reutilizables. Aquí está el patrón base que uso en todos mis agentes:
import anthropic
client = anthropic.Anthropic()
tools = [
{
"name": "buscar_precio",
"description": "Busca el precio actual de un producto por nombre exacto",
"input_schema": {
"type": "object",
"properties": {
"producto": {
"type": "string",
"description": "Nombre del producto a buscar"
}
},
"required": ["producto"]
}
}
]
def ejecutar_tool(nombre, inputs):
if nombre == "buscar_precio":
precios = {"claude max": "100€/mes", "n8n cloud": "20€/mes"}
return precios.get(inputs["producto"].lower(), "No encontrado")
def agente(tarea, max_iteraciones=15):
messages = [{"role": "user", "content": tarea}]
for _ in range(max_iteraciones):
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=4096,
tools=tools,
messages=messages
)
if response.stop_reason == "end_turn":
return response.content[0].text
tool_results = []
for block in response.content:
if block.type == "tool_use":
result = ejecutar_tool(block.name, block.input)
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": result
})
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})
return "Agente alcanzó el máximo de iteraciones"
El 90% del valor real está en cómo diseñas las herramientas y el prompt del sistema, no en el código del bucle. El bucle es infraestructura — lo copias una vez y te olvidas. Lo que importa es qué herramientas le das y cómo se las describes a Claude.
Añadir herramientas reales a tu agente
Las herramientas son el superpoder del agente. Sin ellas, Claude solo puede pensar. Con ellas, puede actuar. Cada herramienta es una función Python que hace algo concreto: consultar una base de datos, llamar a una API, leer un archivo, enviar un mensaje.
La regla que he aprendido a base de errores: empieza con 2-3 herramientas máximo. Cada tool que añades le da más opciones a Claude, y más opciones significan más posibilidades de que elija mal. Esto no lo dice ningún tutorial — lo aprendes cuando tu agente decide usar enviar_email en lugar de buscar_datos porque la descripción era ambigua.
Herramientas que uso en mis agentes en producción:
| Herramienta | Qué hace | Agente que la usa |
|---|---|---|
buscar_web |
Busca información en Google via SerpAPI | Remy (research) |
leer_archivo |
Lee archivos del VPS local | Rafiki (blog) |
enviar_slack |
Envía mensaje a canal de Slack | Todos |
consultar_airtable |
Lee y escribe registros en Airtable | FBS (analítica) |
generar_svg |
Crea diagramas SVG con plantillas | Rafiki (blog) |
Para definir una herramienta en el SDK necesitas tres cosas: un nombre descriptivo, una descripción clara que Claude lee para decidir cuándo usarla, y el esquema JSON de los parámetros de entrada. La descripción es lo más crítico — si es vaga ("busca información"), Claude la usará para todo. Sé específico: "Busca el precio actual de un producto en el catálogo de Shopify por su nombre exacto". Cuanto más precisa la descripción, mejor decide Claude.
¿Quieres montar tu propio equipo de agentes de IA?
Cada semana comparto lo que funciona (y lo que no) montando agentes reales para mi negocio. Sin teoría, sin humo.
🎁 Al suscribirte recibes mi guía: cómo llegué a 500 subs en <1 mes con agentes IA.
Ejemplo real: mi agente de investigación de mercado
Voy a enseñarte un caso concreto que tengo en producción. Remy es mi agente de research. Le doy un tema, y me devuelve un informe estructurado con datos verificados, fuentes citadas, y tendencias detectadas. Lo construí con Claude Agent SDK en una tarde — la parte difícil fue afinar los prompts, no el código.
El agente tiene 3 herramientas: buscar en web (SerpAPI), buscar en mis notas de Notion (API de Notion), y formatear el informe final en markdown. El system prompt le dice que es un investigador riguroso, que siempre cite fuentes con URL, y que priorice datos de 2025-2026.
resultado = agente(
"Investiga el mercado de agentes de IA para solopreneurs en España. "
"Dame tamaño de mercado, competidores principales y oportunidades. "
"Solo datos de 2025-2026."
)
Remy hace ~6-8 iteraciones del bucle: busca en web, encuentra datos, busca más contexto, cruza con mis notas, y genera el informe. Tarda unos 45 segundos y cuesta ~0,08€ por investigación completa.
Comparado con hacer un research manual (2-3 horas por tema), el ROI es obsceno. 0,08€ y 45 segundos vs 3 horas de mi tiempo. Si facturo a 50€/hora, cada research me ahorra 150€ de coste de oportunidad. Con el SDK, el agente se paga solo en la primera ejecución.
Eso no significa que el agente sea perfecto. A veces cita fuentes que no existen o malinterpreta datos. Por eso siempre reviso el output antes de usarlo. La IA no sustituye el criterio — lo amplifica.
Cuánto cuesta un agente con Claude Agent SDK (desglose real)
El SDK es gratuito y open source. Solo pagas las llamadas a la API de Anthropic. Aquí están los precios reales que manejo en mayo de 2026:
| Modelo | Input (1M tokens) | Output (1M tokens) | Uso recomendado |
|---|---|---|---|
| Sonnet 4.6 | 3$ | 15$ | Agentes de producción (mejor ratio) |
| Haiku 4.5 | 0,25$ | 1,25$ | Tareas simples: clasificar, extraer |
| Opus 4.7 | 15$ | 75$ | Análisis complejos, razonamiento profundo |
Un agente típico con Sonnet consume 3.000-8.000 tokens de input y 1.000-3.000 de output por tarea. Eso son 0,02-0,07€ por ejecución. Si tu agente procesa 50 tareas diarias, hablamos de 1-3,50€ al día. Menos de 100€ al mes para un agente que trabaja 24/7 sin quejarse.
Mi equipo completo de 6 agentes me sale por menos de 20€/mes en coste de API. Compáralo con el coste de un equipo humano equivalente — 12.000-16.000€/mes en sueldos brutos más Seguridad Social. No es opinión, son matemáticas básicas.
Y si activas prompt caching (y deberías), el coste baja otro 90% en los tokens del system prompt que se repite entre llamadas. Según la documentación de Anthropic, los tokens cacheados cuestan un 90% menos que los tokens nuevos en input. Eso hace que agentes con prompts largos de sistema sean todavía más baratos en producción.
Los 4 errores que cometí al empezar
Después de montar varios agentes con el SDK, he acumulado una lista de tropiezos que te van a ahorrar horas de debug y frustración.
Error 1: demasiadas herramientas desde el día 1. Mi primer agente tenía 12 tools. Claude se perdía eligiendo la correcta y a veces encadenaba 3 herramientas cuando con 1 bastaba. Lo reduje a 3 y la fiabilidad subió del 60% al 95%. Empieza con 2-3 tools y añade una nueva solo cuando confirmes que las anteriores funcionan bien.
Error 2: descripciones vagas en las tools. Si describes una herramienta como "busca información", Claude la usará para absolutamente todo. Sé quirúrgico: "Busca el precio actual de un producto en el catálogo de Shopify por su nombre exacto. Solo devuelve precio y disponibilidad." Cuanto más precisa la descripción, mejor las decisiones de Claude.
Error 3: no limitar las iteraciones del bucle. Un bug en una herramienta puede hacer que el agente entre en bucle infinito — Claude pide un tool, falla, intenta otro, falla, vuelve al primero. Pon siempre un max_iteraciones (yo uso 15 como tope). Si no resuelve la tarea en 15 pasos, algo está mal y es mejor parar que quemar tokens.
Error 4: no usar prompt caching. Si tu agente procesa muchas tareas seguidas, el prompt del sistema se envía en cada llamada API. Con prompt caching de Anthropic, esa parte se cachea y reduces el coste un 90% en los tokens de input repetidos. Según la propia documentación de Anthropic, los tokens de caché cuestan 0,30$ por millón vs 3$ sin caché en Sonnet. Actívalo siempre en producción.
Cuándo elegir Claude Agent SDK vs Claude Code vs n8n
Esta es la pregunta que más me hacen y la que peor se responde en internet, porque todo el mundo tiene su herramienta favorita. Yo uso las tres, así que te doy la versión honesta — comparativa completa en Claude Code vs n8n vs Make.
Claude Code es para cuando necesitas un agente generalista que trabaje con archivos, terminal y código. Es mi herramienta del día a día — con ella escribo este blog, gestiono el repo, y hago mil cosas. Si puedes resolver tu problema con Claude Code, no necesitas el SDK. Así de simple.
Claude Agent SDK es para cuando necesitas un agente custom integrado en tu sistema, con herramientas específicas de tu negocio. Si tu agente tiene que consultar tu base de datos propia, llamar a tus APIs internas, y generar informes con tu formato exacto, el SDK es tu herramienta. Más trabajo inicial, pero control total sobre cada decisión y cada token.
n8n es para flujos deterministas con IA puntual. Si tu proceso es "cuando pasa X, haz Y, y usa Claude solo para decidir Z", n8n es perfecto. No necesitas un agente que razone en bucle — necesitas un flujo que ejecute pasos predefinidos con IA en un punto concreto. Lo expliqué en detalle en el tutorial de n8n con Claude API.
La regla rápida: si tu agente necesita tomar decisiones complejas, usar varias herramientas en secuencia, y adaptar su plan sobre la marcha — SDK. Si es una tarea lineal con IA en un punto — n8n. Si es desarrollo de software o tareas generales — Claude Code. No hay una herramienta que sirva para todo, y el que te diga lo contrario probablemente te está vendiendo una.
Mi recomendación si estás empezando: arranca con Claude Code para validar que tu idea de agente funciona. Cuando confirmes que sí, migra la lógica al SDK para tener control total y poder escalar. Es el camino que seguí yo, y es el que menos tiempo desperdicia. Puedes explorar las opciones en el directorio de agentes IA si buscas más inspiración sobre qué construir.
El Agent SDK no es difícil. Lo difícil es contener las ganas de darle 47 herramientas a tu agente el primer día. Empieza con 2-3 tools, confirma que funcionan, y luego añade. Cada herramienta nueva es una fuente potencial de fallos.