SDK de Anthropic Claude

Q: ¿Cómo configuro la clave API?

O pase api_key= al constructor. Nunca confirme claves en git.

Q: ¿Qué es el bucle de uso de herramientas?

1. Envíe el mensaje del usuario con las herramientas definidas. 2. Si stop_reason == "tool_use", ejecute la herramienta. 3. Envíe los resultados de la herramienta como un mensaje de usuario. 4. Repita hasta que stop_reason == "end_turn".

Q: ¿Prompt del sistema o primer mensaje del usuario?

El parámetro system es el prompt del sistema dedicado. Más limpio que incrustar instrucciones en los mensajes del usuario.

Q: ¿Cómo uso Claude con FastAPI?

Use AsyncAnthropic en manejadores de rutas asíncronas. Transmita con StreamingResponse para SSE a los clientes.

Q: ¿Cómo reduzco los costos?

Use Haiku para tareas simples. Establezca max_tokens apropiado. Cachee los prompts del sistema repetidos donde sea compatible.

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.stream y text_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, messages y tools opcionales.
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_stream solo 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 requiere max_tokens; las solicitudes fallan sin él. Solución: siempre establezca max_tokens explícitamente.
Bucle de herramientas no implementado - Claude devuelve tool_use pero el código no lo maneja. Solución: compruebe stop_reason y envíe bloques tool_result.
Clave API codificada - riesgo de seguridad en el código fuente. Solución: anthropic.Anthropic() lee ANTHROPIC_API_KEY del entorno.
No se manejan los límites de tasa - los errores 429 bloquean la aplicación. Solución: reintento de retroceso exponencial con tenacity o 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.type antes 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 system es el prompt del sistema dedicado.
Más limpio que incrustar instrucciones en los mensajes del usuario.

¿Cómo uso Claude con FastAPI?

Use AsyncAnthropic en manejadores de rutas asíncronas.
Transmita con StreamingResponse para 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_tokens apropiado.
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+.

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.stream y text_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, messages y tools opcionales.
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_stream solo 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 requiere max_tokens; las solicitudes fallan sin él. Solución: siempre establezca max_tokens explícitamente.
Bucle de herramientas no implementado - Claude devuelve tool_use pero el código no lo maneja. Solución: compruebe stop_reason y envíe bloques tool_result.
Clave API codificada - riesgo de seguridad en el código fuente. Solución: anthropic.Anthropic() lee ANTHROPIC_API_KEY del entorno.
No se manejan los límites de tasa - los errores 429 bloquean la aplicación. Solución: reintento de retroceso exponencial con tenacity o 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.type antes 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 system es el prompt del sistema dedicado.
Más limpio que incrustar instrucciones en los mensajes del usuario.

¿Cómo uso Claude con FastAPI?

Use AsyncAnthropic en manejadores de rutas asíncronas.
Transmita con StreamingResponse para 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_tokens apropiado.
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+.

SDK de Anthropic Claude

Buscar en la documentación

SDK de Anthropic Claude