SDK de Anthropic Claude
El SDK de Python de Anthropic llama a los modelos Claude a través de la API de Mensajes. Admite streaming, uso de herramientas, visión y salidas estructuradas para aplicaciones LLM de producción.
Receta
Tarjeta de referencia rápida - lista para copiar y pegar.
import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
system="Eres un asistente útil.",
messages=[{"role": "user", "content": "¡Hola!"}],
)
print(message.content[0].text)Cuándo usar esto:
- Al crear aplicaciones en modelos Claude (Sonnet, Haiku, Opus).
- Al transmitir respuestas largas a los usuarios en tiempo real.
- Al dar a Claude acceso a herramientas (búsqueda, base de datos, API).
- Al procesar imágenes o documentos con la capacidad de visión de Claude.
Ejemplo de trabajo
"""anthropic_claude_sdk.py - mensajes, streaming y uso de herramientas."""
from __future__ import annotations
import json
import anthropic
client = anthropic.Anthropic()
# Mensaje básico
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=512,
system="Eres un revisor de código Python. Sé conciso.",
messages=[{"role": "user", "content": "Revisa: def add(a,b): return a+b"}],
)
print(response.content[0].text)
# Streaming
print("--- streaming ---")
with client.messages.stream(
model="claude-sonnet-4-20250514",
max_tokens=256,
messages=[{"role": "user", "content": "Cuenta del 1 al 5."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
print()
# Uso de herramientas
tools = [{
"name": "get_weather",
"description": "Obtener el tiempo para una ciudad",
"input_schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
}]
def get_weather(city: str) -> str:
return json.dumps({"city": city, "temp_f": 72, "condition": "soleado"})
msg = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "¿Qué tiempo hace en Austin?"}],
)
while msg.stop_reason == "tool_use":
tool_results = []
for block in msg.content:
if block.type == "tool_use":
result = get_weather(**block.input)
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": result,
})
msg = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
tools=tools,
messages=[
{"role": "user", "content": "¿Qué tiempo hace en Austin?"},
{"role": "assistant", "content": msg.content},
{"role": "user", "content": tool_results},
],
)
print(msg.content[0].text)Lo que esto demuestra:
- Creación básica de mensajes síncronos.
- Streaming con
messages.streamytext_stream. - Definición de herramientas con esquema JSON y bucle de uso de herramientas.
- Envío de resultados de herramientas en múltiples turnos de vuelta a Claude.
Profundización
Cómo funciona
- La API de Mensajes acepta
system,messagesytoolsopcionales. - Los bloques de contenido están tipificados:
text,tool_use,tool_result,image. - stop_reason indica por qué terminó la generación:
end_turn,tool_use,max_tokens. - El streaming emite eventos;
text_streamsolo produce deltas de texto. - Conteo de tokens a través de
client.messages.count_tokens()antes de enviar.
Niveles de Modelos
| Modelo | Velocidad | Capacidad | Uso |
|---|---|---|---|
| Haiku | Más rápido | Tareas básicas | Clasificación, extracción |
| Sonnet | Equilibrado | Razonamiento sólido | Aplicaciones generales |
| Opus | Más lento | Mejor calidad | Análisis complejos, codificación |
Notas de Python
# Cliente asíncrono
import asyncio
import anthropic
async def main():
client = anthropic.AsyncAnthropic()
msg = await client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=256,
messages=[{"role": "user", "content": "Hola"}],
)
print(msg.content[0].text)
asyncio.run(main())Errores comunes
- Falta
max_tokens- La API requieremax_tokens; las solicitudes fallan sin él. Solución: siempre establezcamax_tokensexplícitamente. - Bucle de herramientas no implementado - Claude devuelve
tool_usepero el código no lo maneja. Solución: compruebestop_reasony envíe bloquestool_result. - Clave API codificada - riesgo de seguridad en el código fuente. Solución:
anthropic.Anthropic()leeANTHROPIC_API_KEYdel entorno. - No se manejan los límites de tasa - los errores 429 bloquean la aplicación. Solución: reintento de retroceso exponencial con
tenacityo configuración de reintento del SDK. - Se ignoran los límites de tokens - las conversaciones largas exceden la ventana de contexto. Solución: recorte mensajes antiguos o resuma el historial.
- Acceso incorrecto al bloque de contenido - asumiendo que todos los bloques son de texto. Solución: compruebe
block.typeantes de acceder a.text.
Alternativas
| Alternativa | Usar cuando | No usar cuando |
|---|---|---|
| SDK de Anthropic | Modelos Claude | Necesita el ecosistema de OpenAI |
| SDK de OpenAI | Modelos GPT, herramientas más amplias | Prefiere la seguridad/estilo de Claude |
| LiteLLM | Abstracción multi-proveedor | Simplicidad de proveedor único |
| AWS Bedrock | Claude a través de AWS IAM | La API directa es más simple |
Preguntas frecuentes
¿Cómo configuro la clave API?
export ANTHROPIC_API_KEY="sk-ant-..."- O pase
api_key=al constructor. - Nunca confirme claves en git.
¿Qué es el bucle de uso de herramientas?
- Envíe el mensaje del usuario con las herramientas definidas.
- Si
stop_reason == "tool_use", ejecute la herramienta. - Envíe los resultados de la herramienta como un mensaje de usuario.
- Repita hasta que
stop_reason == "end_turn".
¿Cómo transmito respuestas?
with client.messages.stream(...) as stream:
for text in stream.text_stream:
print(text, end="")- Use streaming asíncrono para servidores web.
¿Puede Claude leer imágenes?
{"role": "user", "content": [
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": b64}},
{"type": "text", "text": "¿Qué hay en esta imagen?"},
]}¿Cómo cuento tokens?
count = client.messages.count_tokens(
model="claude-sonnet-4-20250514",
messages=[{"role": "user", "content": "Hola"}],
)
print(count.input_tokens)¿Qué es el pensamiento extendido?
- Algunos modelos Claude admiten un bloque de pensamiento antes de la respuesta.
- Útil para tareas de razonamiento complejas.
- Consulte la documentación del modelo para ver la disponibilidad.
¿Cómo manejo los errores?
import anthropic
try:
client.messages.create(...)
except anthropic.RateLimitError:
time.sleep(5) # retroceso
except anthropic.APIStatusError as e:
print(e.status_code, e.message)¿Prompt del sistema o primer mensaje del usuario?
- El parámetro
systemes el prompt del sistema dedicado. - Más limpio que incrustar instrucciones en los mensajes del usuario.
¿Cómo uso Claude con FastAPI?
- Use
AsyncAnthropicen manejadores de rutas asíncronas. - Transmita con
StreamingResponsepara SSE a los clientes.
¿Qué modelos están disponibles?
- Consulte https://docs.anthropic.com para ver los IDs de modelos actuales.
- Los nombres de los modelos incluyen fechas de versión (por ejemplo,
claude-sonnet-4-20250514).
¿Cómo reduzco los costos?
- Use Haiku para tareas simples.
- Establezca
max_tokensapropiado. - Cachee los prompts del sistema repetidos donde sea compatible.
¿Puedo obtener salida JSON?
- Instruya a Claude para que responda en JSON en el prompt del sistema.
- Use el uso de herramientas con un esquema para una estructura garantizada.
- Consulte Salida Estructurada.
Relacionado
- SDK de OpenAI y otros - comparación de proveedores
- Uso de herramientas y llamadas a funciones - patrones de herramientas
- Streaming y llamadas LLM asíncronas - streaming asíncrono
- Ingeniería de Prompts - prompts del sistema
- Tokens, Costos y Límites de Tasa - presupuestación
Versiones de Stack: Esta página se escribió para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ y uv 0.6+.