Claude Agent SDK: Cómo Construir un Agente de IA en Producción — Tutorial para Desarrolladores (2026)

Claude Agent SDK: Cómo Construir un Agente de IA en Producción — Tutorial para Desarrolladores (2026)

En una frase: el Claude Agent SDK es el motor de agentes que usa Claude Code, empaquetado para ti — herramientas, memoria, subagentes y control de permisos en menos de 100 líneas de Python o TypeScript — y el coste real de un agente en producción no son las líneas de código sino las 3 cosas que este tutorial te enseña a no romper: permisos, memoria con citas y evaluación continua. Verificado con la versión de septiembre de 2026.

Soy Javier Santos Criado, consultor IA en Javadex; los agentes que implantamos en empresas (Cortex incluye orquestación de agentes como parte de la plataforma) siguen exactamente los patrones de esta guía. Si tu equipo desarrolla, esto es lo que necesita saber; si no desarrolla, salta al final: ahí está la versión llave en mano.

¿Qué es el Claude Agent SDK (y qué le pasa por encima a un simple bucle de LLM)?#

Un LLM con un while y llamadas a herramientas es un juguete; un agente en producción necesita lo que el SDK trae de serie:

Tutorial: un agente de triaje de soporte en Python#

Caso real tipo: empresa con 300 tickets/mes; el agente clasifica, responde lo rutinario con cita al artículo de ayuda y deriva el resto con un resumen. Patrón idéntico para facturación, incidencias de campo o intake comercial.

1. Instalar y definir el agente#

1pip install claude-agent-sdk

1from claude_agent_sdk import Agent, tool
2 
3@tool
4def buscar_en_helpdesk(consulta: str) -> str:
5    """Busca artículos de la base de conocimiento con su URL."""
6    return helpdesk.search(consulta)   # tu búsqueda vectorial con citas
7 
8agente = Agent(
9    model="claude-sonnet-4-6",
10    instructions="""Eres el triaje de soporte. Para cada ticket:
111. Clasifica (rutinario / complejo / urgente).
122. Si es rutinario, responde citando el artículo con su URL.
133. Si no, deriva a humano con un resumen de 3 líneas y prioridad.""",
14    tools=[buscar_en_helpdesk],
15    max_turns=8,
16)

2. Memoria y subagentes#

1memoria = agente.memory(namespace=f"ticket:{ticket_id}")  # contexto persistente
2 
3facturacion = Agent(
4    model="claude-sonnet-4-6",
5    instructions="Especialista en incidencias de facturación con acceso a la API del ERP.",
6    tools=[consultar_erp, emitir_rectificativa],
7    permissions={"emitir_rectificativa": "require_approval"},  # humano confirma
8)
9 
10agente.subagents = {"facturacion": facturacion}   # el principal delega

Fíjate en la línea de permisos: las acciones reversibles se ejecutan solas; las irreversibles piden confirmación humana. Esa frontera es el 80% del diseño de un agente serio.

3. Evaluar antes de soltarlo#

1evals = [
2  ("El cliente pide factura rectificativa de septiembre", "deriva a facturacion"),
3  ("¿Cómo cambio mi tarjeta?", "responde con cita al artículo X"),
4  ("Pedido #8812 no llega y soy autónomo con urgencia", "prioridad alta + resumen"),
5]

20-50 casos golden corriendo en CI contra el modelo, y cualquier cambio de prompt o de modelo se mide antes de desplegar. Sin esto, "funciona" es una opinión.

4. Coste real por ejecución#

Un triaje típico: 2-4 turns, ~15K tokens de entrada y ~1K de salida por ticket. Con Claude Sonnet (~3 $/15 $ por millón de tokens en 2026): ~0,05-0,07 € por ticket, frente a los 4-6 minutos humanos que costaba clasificarlo. Con cache de prompts (el system prompt y la KB se cachean), baja un 40-60% adicional en volúmenes repetidos.

Las 3 cosas que rompen un agente en producción#

1. Permisos por defecto demasiado anchos. Un agente con tools=* contra producción es un incidente esperando fecha. Empieza en read-only y habilita escrituras acción a acción.
2. Memoria sin citas. El agente responde "según la política interna…" y nadie puede verificar qué política. La memoria y el RAG deben devolver origen verificable (artículo, página, documento).
3. Sin observabilidad de calidad. Loguear tokens no basta: guarda pares pregunta-respuesta-cita y revisa muestras semanales; el 5% de casos raros es donde el agente muerde.

Si esto te suena a "esto lo tiene que montar alguien con tiempo": es literalmente el servicio que hago en Javadex — diagnóstico del proceso, agente con permisos y citas, evals en CI, y en producción en 2-4 semanas. Para equipos técnicos prefiero dejarlos con la plataforma montada y el SDK en sus manos que vender humo.

→ Cuéntame qué proceso quieres automatizar →

Preguntas frecuentes#

¿Qué es el Claude Agent SDK?#

El framework de agentes de Anthropic: el mismo motor que impulsa Claude Code, empaquetado como librería para Python y TypeScript, con herramientas, memoria persistente, subagentes, permisos, hooks y soporte MCP.

¿Cuánto cuesta un agente con el Claude Agent SDK?#

El SDK es gratuito; pagas el consumo de API. Un agente de triaje de soporte cuesta ~0,05-0,07 € por ejecución con Claude Sonnet (2-4 turns, ~15K tokens), y menos con cache de prompts. El coste mayor suele ser el desarrollo y el mantenimiento, no los tokens.

¿Puedo conectar el agente a mi ERP o CRM?#

Sí, vía herramientas tipadas (API del ERP) o servidores MCP. La regla de producción: operaciones de lectura se ejecutan solas; las de escritura irreversibles piden confirmación humana o van con doble validación.

¿Agent SDK o LangGraph/CrewAI?#

El SDK de Anthropic brilla si tu stack gira en torno a modelos Claude y quieres permisos y subagentes con el mínimo código. LangGraph gana en grafo de estados complejo multi-proveedor. Para pymes españolas el criterio es el mantenimiento: gana la opción que tu equipo sepa operar a los 6 meses.

¿Cuánto tarda poner un agente en producción?#

Un prototipo funcional, 1-2 días de desarrollador. Un agente con permisos, citas, evals en CI y observabilidad, 2-4 semanas. Ese salto es el que separa una demo de un servicio.