Fundamentos del SDK de Python

9 ejemplos para empezar con el SDK de Python de Anthropic: 6 básicos y 3 intermedios.

Prerrequisitos

• Python 3.8 o superior.
• Una clave API de Anthropic, disponible en la Consola de Anthropic.
• Instala el SDK: pip install anthropic.
• Configura tu clave como una variable de entorno para no codificarla nunca: export ANTHROPIC_API_KEY=sk-ant-....

Ejemplos básicos

1. Instala el SDK

Añade el paquete oficial a tu proyecto con pip.

pip install anthropic

• Instala el paquete anthropic y sus dependencias, incluyendo httpx para el transporte HTTP.
• Fija una versión en requirements.txt (anthropic>=0.40,<1.0) para compilaciones reproducibles.
• No se requieren dependencias adicionales del sistema en una instalación estándar de Python.

2. Crea un cliente

Construye un cliente una vez, reutilizando la clave API del entorno.

import anthropic
 
client = anthropic.Anthropic()

• Sin argumentos, Anthropic() lee automáticamente la variable de entorno ANTHROPIC_API_KEY.
• Construye el cliente una vez al inicio y reutilízalo para cada solicitud; no crees un nuevo cliente por llamada.
• Pasa api_key="sk-ant-..." explícitamente solo cuando no puedas usar una variable de entorno, por ejemplo, cuando una clave se carga desde un gestor de secretos en tiempo de ejecución.

Relacionado: El Modelo Mental del SDK de Python de Anthropic - cómo encaja el cliente en el diseño del SDK

3. Envía tu primer mensaje

Llama a la API de Mensajes con un modelo, un límite de tokens y una lista de mensajes.

import anthropic
 
client = anthropic.Anthropic()
 
message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "¿En una frase, qué es un decorador de Python?"}
    ],
)
 
print(message.content[0].text)

• model selecciona qué modelo de Claude responde a la solicitud; claude-sonnet-5 es una buena opción por defecto para la mayoría de las cargas de trabajo.
• max_tokens limita la longitud de la respuesta, no la longitud de tu entrada.
• messages es una lista de turnos; la primera entrada debe tener role="user".

4. Lee el texto de la respuesta

message.content es una lista de bloques de contenido, no una cadena única.

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Nombra tres números primos."}],
)
 
for block in message.content:
    if block.type == "text":
        print(block.text)

• La respuesta de Claude puede contener múltiples bloques de contenido (texto, llamadas a herramientas, etc.), por lo que content es siempre una lista.
• Comprobar block.type == "text" antes de leer .text evita errores cuando una respuesta contiene bloques que no son de texto.
• Para una respuesta simple solo de texto, message.content[0].text es un atajo común una vez que conoces la estructura de tus respuestas.

5. Establece un prompt del sistema

Usa el parámetro system para dirigir el comportamiento del modelo durante toda la conversación.

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="Eres un tutor de Python conciso. Responde en un párrafo corto.",
    messages=[{"role": "user", "content": "¿Qué es un generador?"}],
)
 
print(message.content[0].text)

• system es un parámetro de nivel superior, separado de messages, y se aplica a toda la solicitud.
• Úsalo para instrucciones de persona, tono y formato en lugar de repetirlas en cada mensaje del usuario.
• Un prompt system estable e inmutable es también lo que hace que el caché de prompts sea efectivo más adelante.

6. Controla max_tokens

max_tokens es un límite estricto para la respuesta, y al alcanzarlo se trunca la salida.

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=100,
    messages=[{"role": "user", "content": "Escribe un ensayo de 500 palabras sobre la tipificación en Python."}],
)
 
print(message.stop_reason)  # "max_tokens" si el ensayo fue cortado
print(message.content[0].text)

• stop_reason te dice por qué se detuvo la generación: "end_turn" para una finalización natural, "max_tokens" para una truncación.
• Establecer max_tokens demasiado bajo para la tarea corta silenciosamente la respuesta en lugar de generar un error.
• Un valor por defecto común para respuestas cortas a medianas es 1024-4096; la salida de formato largo necesita más, y por encima de aproximadamente 16000 deberías cambiar a streaming (ver Relacionado).

Relacionado: Respuestas en Streaming con el SDK de Python - evita tiempos de espera en respuestas grandes

Ejemplos intermedios

7. Conversación multi-turno

La API no tiene estado: reenvías todo el historial de la conversación en cada llamada.

import anthropic
 
client = anthropic.Anthropic()
 
messages = [
    {"role": "user", "content": "Mi lenguaje favorito es Python."},
]
 
first = client.messages.create(model="claude-sonnet-5", max_tokens=200, messages=messages)
messages.append({"role": "assistant", "content": first.content[0].text})
 
messages.append({"role": "user", "content": "¿Qué dije que era mi lenguaje favorito?"})
second = client.messages.create(model="claude-sonnet-5", max_tokens=200, messages=messages)
 
print(second.content[0].text)

• Claude no tiene memoria entre llamadas; cada turno anterior que quieras que se recuerde debe estar en la lista messages que envías.
• Añade la propia respuesta del asistente de vuelta a messages antes de añadir el siguiente turno del usuario, para que el modelo vea su propia respuesta anterior.
• Los mensajes deben empezar con role="user" y generalmente alternar user/assistant.

8. Maneja errores con excepciones tipadas

Captura las clases de excepción específicas del SDK en lugar de un único except amplio.

import anthropic
 
client = anthropic.Anthropic()
 
try:
    message = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hola"}],
    )
except anthropic.RateLimitError:
    print("Límite de tasa alcanzado - espera y vuelve a intentarlo más tarde.")
except anthropic.APIConnectionError:
    print("Error de red al contactar la API.")
except anthropic.APIStatusError as e:
    print(f"La API devolvió un error: {e.status_code} {e.message}")

• RateLimitError, APIConnectionError y APIStatusError son clases distintas para modos de fallo distintos; captura la más específica primero.
• El SDK ya reintenta fallos transitorios (errores de red, 429, 5xx) automáticamente, por lo que una excepción aquí significa que los reintentos se agotaron o el fallo no era reintentable.
• Consulta la página de referencia de excepciones para la correspondencia completa entre el tipo de excepción y el manejo recomendado.

Relacionado: Tipos de Excepciones del SDK de Python de un Vistazo - el mapeo completo de excepciones a estrategias

9. Configura el tiempo de espera y los reintentos en la construcción

Establece valores predeterminados a nivel de cliente para cuánto esperar y cuántas veces reintentar.

import anthropic
 
client = anthropic.Anthropic(
    max_retries=4,
    timeout=30.0,
)
 
message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Resume la trama de un cuento sobre un faro."}],
)
 
print(message.content[0].text)

• max_retries controla cuántas veces el SDK reintenta automáticamente un fallo transitorio antes de lanzar una excepción; el valor predeterminado es 2.
• timeout está en segundos para el SDK de Python y se aplica por solicitud a menos que se anule.
• Usa client.with_options(...) para anular cualquiera de las configuraciones para una sola llamada sin cambiar los valores predeterminados del cliente.

Relacionado: Referencia de Configuración de Reintentos y Tiempos de Espera del SDK de Python - cada configuración, comparada lado a lado

Versiones de la pila: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026: Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5, y el SDK oficial de Python anthropic (última versión 0.x). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.