De usar Claude a programar con Claude
Hasta ahora has hablado con Claude en una ventana de chat. Hoy lo vas a llamar desde tu propio código. Diego, nuestro programador junior, lo explicó así en la oficina: "es como pedir un café, pero el camarero es una función de Python". Y Tía Rosa, que pasaba por allí, preguntó si el café venía con factura. Spoiler: sí, y se llama usage.
Preparar el terreno
Instala el SDK oficial y guarda tu clave como variable de entorno (nunca la pegues en el código ni la subas a un repositorio):
pip install anthropic
export ANTHROPIC_API_KEY="tu-clave-aqui"El cliente lee la clave del entorno solo:
import anthropic
client = anthropic.Anthropic()Tu primera llamada
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system="Eres un asistente para una tienda de tazas. Responde breve.",
messages=[
{"role": "user", "content": "Dame un eslogan para una taza azul."}
],
)
for block in response.content:
if block.type == "text":
print(block.text)
Los cuatro campos que mandas
| Campo | Para qué sirve |
|---|---|
model | Qué modelo respondes. Usa el identificador exacto, sin fecha |
max_tokens | Tope de longitud de la respuesta. Obligatorio |
system | Rol, tono y reglas generales (opcional, pero muy útil) |
messages | La conversación: una lista de {"role", "content"} |
Los modelos actuales son claude-opus-5-5 (buena opción por defecto), claude-sonnet-5-5 (equilibrado), claude-haiku-5-5 (el más rápido y barato) y claude-fable-5-1 (el más capaz, premium). Los precios y los modelos disponibles cambian: consulta siempre la documentación oficial.
Lo que lees en la respuesta
content: una lista de bloques, no un string. Cada bloque tienetype(text,tool_use,thinking...). Por eso comprobamosblock.type == "text"antes de leer.text.stop_reason: por qué paró Claude.end_turnsignifica que terminó de forma natural;max_tokenssignifica que lo cortaste por quedarte corto.usage:input_tokensyoutput_tokens. Es tu contador de gasto.
Antes y después de un system prompt
ANTES (sin system):
messages=[{"role": "user", "content": "Responde a este cliente enfadado: mi taza llegó rota"}]
-> respuesta correcta pero genérica, sin tono de marca
DESPUÉS (con system):
system="Eres el soporte de Tazas Marta. Tono cálido, 3 frases máximo, ofrece reenvío gratis."
-> respuesta con la voz de la tienda, corta y con soluciónLa historia de Marta
Marta quería respuestas automáticas para su tienda. Diego escribió el código en diez minutos... y la respuesta salió cortada a mitad de frase. Había puesto max_tokens=20. Claude no se había rendido: simplemente se le acabó el presupuesto de palabras. Subió el valor, y asunto resuelto. Tía Rosa comentó: "Es como mandarme un telegrama: cobran por palabra". No iba desencaminada.
Errores típicos
- Olvidar
max_tokens: es obligatorio y la llamada falla sin él. - Hacer
response.content.text:contentes una lista. Recorre los bloques. - Inventar el nombre del modelo o añadirle fechas: usa el identificador exacto.
- Pegar la clave en el código: usa
ANTHROPIC_API_KEY. - Empezar
messagesconassistant: el primer mensaje debe ser del usuario.
💡 Truco: el SDK reintenta solo ante errores de red y de saturación. Aun así, captura anthropic.APIStatusError para manejar los fallos que no se arreglan reintentando.
Reto
En esta lección simularás la API sin red: construirás la petición como un diccionario, extraerás el texto de una respuesta y validarás peticiones. Reto: escribe un system que haga que Claude responda siempre con exactamente tres viñetas, y piensa qué stop_reason esperarías si max_tokens fuese 5.