Bloque 3

Claude SDK

API · Modelos · Tool Use · Primer agente funcional

¿Qué vamos a ver?

  1. ¿Por qué el SDK? — cuándo pasar de herramientas a código
  2. Hello World — tu primera llamada en Python
  3. Tool Use — Claude conectado a tus datos reales
  4. El agente — bucle de razonamiento y acción
  5. Ejercicio práctico — construye el agente de tu startup
  6. De demo a producción — costes, errores y deployment

Al final tendrás un agente funcional que resuelve un problema real.

¿Por qué el SDK?

La escalera de herramientas

Automatización ↑ Claude.ai Chat en el navegador Sin instalación Cowork Tus archivos + Claude Sin código Claude Code Claude en tu terminal CLI SDK / API Claude en tu producto Código Conocimiento técnico requerido →

Cuándo necesitas el SDK

Usa Claude.ai / Cowork cuando el trabajo es manual, puntual, tú y tu equipo.

Usa el SDK cuando:

  • El proceso debe correr sin que nadie lo active — a las 8h, al recibir un email, al registrarse un usuario
  • Claude necesita consultar tu base de datos, no conocimiento genérico
  • Quieres integrar IA en tu producto — tus usuarios ven tu app, no Claude
  • Necesitas escalar a miles de llamadas sin intervención humana

Las respuestas del formulario de hoy son exactamente este tipo de problema.

Hello World

Setup en 3 pasos

1
Crea un entorno virtual
python -m venv .venv && source .venv/bin/activate — aísla las dependencias del proyecto del resto del sistema.
2
Instala la librería oficial
pip install anthropic dentro del entorno. Sin dependencias pesadas.
3
Configura tu API key
Exporta ANTHROPIC_API_KEY como variable de entorno. El cliente la lee automáticamente al instanciarlo — no hay que pasarla en el código.

Consigue tu key gratuita en console.anthropic.com — incluye créditos para empezar.

Modelos disponibles

Modelo ID Velocidad Cuándo usarlo
Haiku 4 claude-haiku-4-5-... ⚡⚡⚡ Clasificación, resúmenes, volumen alto
Sonnet 4 claude-sonnet-4-6 ⚡⚡ La mayoría de casos — empieza aquí
Opus 4 claude-opus-4-8 ⚡ Razonamiento complejo, análisis profundo
Fable 5 claude-fable-5 ⚡ Tareas agenticas largas, coding avanzado, computer use

Regla práctica: Haiku para volumen y velocidad, Sonnet para la mayoría de casos, Fable 5 para agentes autónomos de larga duración.

Tu primera llamada

Se llama a client.messages.create() con tres parámetros clave:

model
Qué versión de Claude usar — claude-haiku-4-5 para empezar.
max_tokens
Límite máximo de tokens en la respuesta. Controla el coste y evita respuestas infinitas.
messages
Array con el historial de la conversación. El primer mensaje es siempre role: "user" con tu pregunta.

La respuesta llega en response.content[0].text — exactamente el mismo texto que verías en Claude.ai, pero ahora dentro de tu código.

▶ sdk_examples/01_primera_llamada.py

Conversación multi-turno

1ª llamada
messages = [{ role:"user", content:"¿Qué ejercicio me recomiendas?" }]
→ Claude responde: "Te recomiendo empezar con 20 min de cardio suave..."
2ª llamada
messages = [{ role:"user", content:"¿Qué ejercicio me recomiendas?" },
           { role:"assistant", content:"Te recomiendo empezar con 20 min de cardio..." },
           { role:"user", content:"¿Y si solo tengo 10 minutos?" }]
→ Claude recuerda el contexto: "Con 10 minutos, prueba HIIT: 30s esfuerzo / 30s descanso × 10..."

Cada llamada es sin estado — la memoria eres tú: añade las respuestas anteriores al array messages.

Tool Use

Claude conectado a tus datos reales

Claude como orquestador

Tu apppregunta del usuario
⇆
Clauderazona y decide qué herramienta usar y cuándo
⇆
Tus funcionestu BD, tu API, tus datos reales

Sin Tool Use: Claude responde con conocimiento genérico.
Con Tool Use: Claude responde con tus datos reales.

Claude decide cuándo llamar la herramienta. Tú defines qué hace.

Anatomía de una herramienta

Una herramienta es un diccionario con tres campos:

name
Identificador que Claude usa para invocar la función. Debe ser único y descriptivo — por ejemplo "buscar_usuario".
description
Texto en lenguaje natural dirigido a Claude — explica qué hace la función y cuándo usarla. Es el campo más importante: de él depende que Claude elija bien.
input_schema
JSON Schema con los parámetros que acepta: tipo, nombre y descripción de cada uno. Claude los infiere y rellena automáticamente según el contexto.

▶ sdk_examples/02_tool_definition.py

El flujo de Tool Use — paso a paso

1
Usuario pregunta: "¿Cuál es el plan de entrenamiento de María?"
2
Claude recibe la pregunta y la lista de herramientas disponibles
3
Claude responde con tool_use: "quiero llamar buscar_usuario("María")"
4
Tu código ejecuta la función real y obtiene el resultado de la BD
5
Devuelves el resultado a Claude como tool_result
6
Claude genera la respuesta final usando los datos reales

Tool Use y Tool Result en las llamadas

1ª llamada
messages = [{ role:"user", content:"¿Cuál es el plan de María?" }]
→ stop_reason: "tool_use"
{ role:"assistant", content:[{ type:"tool_use", id:"tu_01", name:"buscar_usuario", input:{nombre:"María"} }] }
2ª llamada
messages = [ …turno anterior…,
  { role:"user", content:[{ type:"tool_result", tool_use_id:"tu_01", content:"{id:'u123', nivel:'intermedio'}" }] }]
→ stop_reason: "end_turn" → Claude genera la respuesta final

tool_use es Claude pidiendo ejecutar algo. tool_result eres tú devolviendo el dato. Siempre en el array messages.

El Agente

El bucle que todo lo une

El loop del agente

1
Inicializa el historial con la pregunta del usuario como primer mensaje.
2
Llama a la API pasando el historial completo, el system prompt y la lista de tools disponibles.
3
Añade la respuesta de Claude al historial — sea texto final o una petición de tool.
4
Si stop_reason == "end_turn": Claude considera que tiene suficiente información y ha generado una respuesta completa — no necesita llamar a ninguna tool más. Sale del loop y mostramos el texto al usuario. El otro valor posible es "tool_use": Claude quiere datos antes de responder.
5
Si stop_reason == "tool_use": recorre los bloques de la respuesta, ejecuta cada tool con tus datos reales y recoge los resultados.
6
Devuelve los resultados como tool_result en el historial y vuelve al paso 2 — Claude decide si necesita más tools o puede responder.

▶ sdk_examples/03_fitcoach_agent.py

FitCoach — definir las herramientas

Se definen dos herramientas que Claude puede invocar:

buscar_usuario(nombre) Recibe el nombre completo del usuario y devuelve su id, nivel y objetivo.
Claude la usa cuando necesita identificar a alguien antes de consultar su plan.
obtener_plan(usuario_id) Recibe el usuario_id y devuelve el plan: días, minutos de cardio y de fuerza.
Claude la usa una vez tiene el id del usuario obtenido con la tool anterior.

Las descripciones guían a Claude para encadenar las tools en el orden correcto sin instrucciones explícitas.

▶ sdk_examples/03_fitcoach_agent.py

La memoria del agente — el historial

user
"¿Cuál es el plan de María García?"
assistant
tool_use → buscar_usuario("María García")
user
tool_result → {id: "u123", nivel: "intermedio", objetivo: "resistencia"}
assistant
tool_use → obtener_plan("u123")
user
tool_result → {días: ["lun", "mié", "vie"], cardio: "30 min", fuerza: "45 min"}
assistant
"María sigue un plan de 3 días por semana enfocado en resistencia..."

El historial es la memoria del agente — cada turno Claude ve todo el contexto anterior.

FitCoach — ejecutar las herramientas

Datos simulados Dos diccionarios Python replican lo que haría una base de datos real: uno con perfiles de usuario y otro con planes de entrenamiento indexados por usuario_id.
Dispatcher ejecutar_tool Una sola función recibe el nombre de la tool y sus parámetros, y delega a la lógica correspondiente. En producción aquí iría la consulta SQL o la llamada a tu API.

Si Claude solicita un usuario que no existe, la función devuelve {"error": "Usuario no encontrado"} — Claude recibe ese mensaje y puede adaptar su respuesta al usuario final.

▶ sdk_examples/03_fitcoach_agent.py

FitCoach — en acción

Usuario: "¿Cuál es el plan de entrenamiento de María García?"
→ Claude llama buscar_usuario("María García") → {id: "u123", nivel: "intermedio"}
→ Claude llama obtener_plan("u123") → {días: ["lun","mié","vie"], cardio: "30 min"}
FitCoach: "María sigue un plan de 3 días por semana (lunes, miércoles y viernes), enfocado en resistencia. Cada sesión incluye 30 min de cardio y 45 min de fuerza — adecuado para su nivel intermedio."

Claude coordinó dos llamadas, combinó los resultados y generó una respuesta contextualizada — todo automático.

▶ sdk_examples/03_fitcoach_agent.py

El agent loop — vuelta a vuelta

iter 1
while True → client.messages.create(messages)
assistant → [{ type:"tool_use", name:"buscar_usuario", id:"tu_01" }]  stop_reason: "tool_use"
user     ← [{ type:"tool_result", tool_use_id:"tu_01", content:"{id:'u123'…}" }]
↓ loop continúa
iter 2
while True → client.messages.create(messages)  (ahora con 3 mensajes)
assistant → [{ type:"tool_use", name:"obtener_plan", id:"tu_02" }]  stop_reason: "tool_use"
user     ← [{ type:"tool_result", tool_use_id:"tu_02", content:"{días:…}" }]
↓ loop continúa
iter 3
while True → client.messages.create(messages)  (ahora con 5 mensajes)
assistant → "María sigue un plan de 3 días…"  stop_reason: "end_turn" → break ✓

Manos a la obra 🛠️

🎓 Plataforma educativa

Tools:
obtener_curriculum(materia)
generar_pregunta(tema, nivel)

Objetivo: agente que genera una batería de preguntas para un tema concreto, adaptadas al nivel del alumno

💪 Fitness / operaciones

Tools:
buscar_usuario(nombre)
actualizar_plan(usuario_id, cambios)

Objetivo: agente que recibe una solicitud de cambio y actualiza el plan automáticamente

💬 Atención al cliente

Tools:
buscar_pedido(numero)
escalar_ticket(pedido_id, motivo)

Objetivo: agente que responde preguntas con datos reales del pedido y escala si no puede resolver

Entregable: define las 2 tools de tu caso (nombre, descripción, parámetros) y el system prompt.

Template base — adapta a tu caso

Tres partes a personalizar — el loop del agente no cambia:

system_prompt
Define el rol y el tono del agente. Escribe aquí qué hace tu startup, qué puede y qué no puede hacer el asistente.
tools
Lista de herramientas disponibles. Cada una necesita nombre, descripción y esquema de parámetros. Empieza con 1–2 tools y añade más cuando las necesites.
ejecutar_tool
El dispatcher que conecta Claude con tus datos reales. Sustituye los datos simulados por consultas a tu BD o llamadas a tu API.

▶ sdk_examples/04_template.py

Q&A

¡Gracias! 🙌

Ha sido un placer aprender juntos


¿Nos dejas tu feedback?

https://forms.gle/2eLq7PucCT66i7aF6

← Volver al índice