Cómo construir un chatbot de IA con la API de Claude en 2026

Antes, construir un chatbot implicaba gestionar clasificadores de intención, árboles de diálogo y una gran cantidad de casos límite. Con una API moderna de modelos de lenguaje, el modelo se encarga de la parte difícil —entender y responder—, mientras que su trabajo consiste únicamente en conectar los componentes. Con la API de Claude puede tener un chatbot verdaderamente capaz funcionando en mucho menos de una hora.

Esta guía explica los conceptos y el código necesarios: configuración inicial, mantenimiento de una conversación, control del comportamiento, transmisión de respuestas y optimización de costos.

Paso 1: Configuración inicial

Necesita dos elementos: una clave de API y el SDK.

1. Obtenga una clave de API — cree una cuenta en la Consola de Anthropic y genere una clave de API. Manténgala en secreto: almacénela en una variable de entorno; nunca la codifique directamente ni la incluya en el control de versiones.
2. Instale el SDK — Anthropic proporciona SDK oficiales. Para Python:

pip install anthropic

(También existe un SDK para Node.js; los conceptos explicados a continuación son idénticos.)

Paso 2: Su primer mensaje

El núcleo de la API de Claude es la API de Mensajes. Usted envía una lista de mensajes y Claude devuelve la siguiente respuesta. A continuación se muestra la llamada más sencilla posible:

from anthropic import Anthropic

client = Anthropic()  # lee la variable de entorno ANTHROPIC_API_KEY

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "¡Hola! ¿En qué puedo ayudarte?"}
    ],
)

print(response.content[0].text)

Este es un chatbot funcional —aunque muy olvidadizo—. model selecciona qué versión de Claude utilizar, max_tokens limita la longitud de la respuesta y messages es el historial de la conversación hasta el momento.

Paso 3: Dotarlo de memoria

El ejemplo anterior no tiene memoria: cada llamada es independiente. Para mantener una conversación real, tú debe conservar el historial y reenviarlo en cada turno. La propia API es sin estado —solo conoce lo que usted le envía.

El patrón consiste en mantener una messages lista, agregar cada mensaje del usuario y cada respuesta de Claude, y enviar toda la lista en cada llamada.

from anthropic import Anthropic

client = Anthropic()
messages = []

while True:
    user_input = input("Usted: ")
    if user_input.lower() == "salir":
        break

    messages.append({"role": "user", "content": user_input})

    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        messages=messages,
    )

    reply = response.content[0].text
    print(f"Claude: {reply}")

    messages.append({"role": "assistant", "content": reply})

Ahora sí es un chatbot real: recuerda todo lo dicho anteriormente en la conversación, porque ese historial se envía en cada turno.

Paso 4: Definir su personalidad mediante un mensaje del sistema

Rara vez se desea un asistente genérico. El indicación del sistema define el rol, el tono y las reglas del bot. Se pasa como un parámetro independiente, no como un mensaje. system parámetro, no como un mensaje.

SYSTEM_PROMPT = """Eres un amable asistente de soporte para un servicio de suscripción de café. Sé cálido, conciso y útil. Si un cliente pregunta sobre algo que no conoces, indícale que lo conectarás con un agente humano. Nunca menciones a competidores."""

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=SYSTEM_PROMPT,
    messages=messages,
)

La indicación del sistema es tu principal herramienta para moldear el comportamiento del bot: dedica tiempo a redactarla. Sé específico acerca del rol, el tono, cómo debe actuar el bot ante dudas y cualquier límite estricto.

Paso 5: Transmitir la respuesta en tiempo real (streaming)

En los ejemplos anteriores, esperas a que se genere toda la respuesta antes de que aparezca algo. Las interfaces reales de chat transmiten el texto palabra por palabra. El SDK lo hace sencillo:

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=SYSTEM_PROMPT,
    messages=messages,
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

El streaming no acelera la generación, pero hace que el bot parezca notablemente más receptivo, porque el usuario ve la salida inmediatamente.

Paso 6: Reducir costos mediante la memoria caché de indicaciones (prompt caching)

Las llamadas a la API se facturan por tokens, y un chatbot reenvía muchas veces el mismo texto en cada turno: la indicación del sistema y un historial de conversación que solo crece. La caché de indicaciones (prompt caching) permite marcar las partes estables de la indicación para que la API las reutilice en lugar de procesarlas nuevamente, reduciendo sustancialmente tanto el costo como la latencia.

Agregas una marca de caché al contenido que deseas almacenar en caché —normalmente la indicación del sistema y cualquier contexto fijo y extenso:

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=messages,
)

Para cualquier chatbot que maneje tráfico real, activa la memoria caché de indicaciones desde el inicio: es una de las optimizaciones de mayor impacto disponibles y no tiene ningún costo adicional.

Elección del modelo

Claude está disponible en varias categorías. Como regla general:

• Un modelo rápido y equilibrado (como el nivel Sonnet) es la opción predeterminada adecuada para la mayoría de los chatbots: calidad sólida, buena velocidad y costo razonable.
• El modelo más capaz (el nivel Opus) merece la pena cuando el bot debe realizar razonamientos complejos o tareas difíciles.
• Un modelo más pequeño y más rápido (el nivel Haiku) es ideal para chatbots simples y de alto volumen, donde la velocidad y el costo son prioritarios.

Comienza con el nivel equilibrado y solo cambia a otro nivel una vez que observes el uso real.

Preparación para producción

El código anterior constituye el núcleo funcional. Para una implementación real, añade:

• Una capa web — envuelve la lógica en un punto final de API y conecta una interfaz de chat.
• Límites de historial — las conversaciones crecen indefinidamente; limita o resume los turnos antiguos para evitar que las indicaciones se vuelvan excesivamente largas.
• Manejo de errores — gestiona límites de tasa y fallos transitorios mediante reintento.
• Conocimiento — para responder con tus propios datos, incorpora la generación aumentada por recuperación para que el bot recupere documentos relevantes.
• Seguridad — valida las entradas y establece límites claros en la indicación del sistema.

Detecte errores y límites de velocidad antes de que los usuarios los encuentren

Un chatbot que funciona en su portátil seguirá fallando en producción en el instante en que reciba tráfico real. La API de Claude presenta dos tipos de fallo, y cada uno requiere una respuesta distinta. El primero es errores transitorios de la API — estos se presentan como excepciones con un código de estado HTTP. El segundo es una negativa, que es una respuesta perfectamente válida que simplemente rechaza la solicitud. Confundir ambos es el error de fiabilidad más común que observamos en los primeros códigos de chatbots.

En cuanto a los errores transitorios, dos códigos de estado son los más relevantes:

• 429 (límite de velocidad) — ha superado la cuota de solicitudes por minuto o de tokens por minuto de su cuenta. La respuesta incluye un encabezado retry-after que le indica exactamente cuántos segundos debe esperar. Respételo con precisión; esperar menos tiempo provocará otro error 429.
• 529 (sobrecarga) — la API de Anthropic está temporalmente saturada para todos los usuarios. No puede prevenir este error mediante código, y las solicitudes rechazadas con código 529 no generan cargo alguno. Reduzca la frecuencia de llamadas y reintente; nunca sobrecargue un extremo ya sobrecargado.
• 500 (error del servidor) — un fallo interno poco frecuente. Trátelo igual que un 529: reintente con retroceso exponencial (backoff).

La buena noticia es que los SDK oficiales ya reintentan automáticamente los errores 429 y 5xx con retroceso exponencial (por defecto, dos reintetos). Para un chatbot en producción, aumente este límite y deje que el SDK haga el trabajo, en lugar de implementar su propio bucle:

• Aumente max_retries en el cliente (un valor entre 4 y 5 es razonable para un chat orientado al usuario).
• Capture las excepciones tipificadas — RateLimitError, OverloadedError, APIError — en lugar de comparar cadenas de texto en los mensajes de error, lo cual dejaría de funcionar silenciosamente si cambia la redacción.
• Cuando finalmente se agoten todos los reintetos, muestre al usuario un mensaje sereno como «Ahora mismo estoy un poco ocupado; inténtelo de nuevo dentro de un momento», en lugar de una traza de pila (stack trace).

Las negativas constituyen un flujo completamente distinto. Cuando una respuesta llega con stop_reason: "refusal", la solicitud ha tenido éxito — Claude ha decidido no responder por razones de seguridad, y en los modelos actuales no se le facturará si no se generó ninguna salida. Es fundamental que no vuelva a enviar simplemente la misma conversación: la negativa se repetirá. En su lugar, elimine o reformule el turno que la desencadenó, o reinicie el historial, y proporcione al usuario un mensaje claro. Puesto que una negativa es un campo de la respuesta y no una excepción, cualquier código que solo inspeccione end_turn y tool_use permitirá que pase inadvertida como una respuesta vacía y confusa. Siempre agregue una bifurcación explícita para gestionarla.

Implemente estos tres comportamientos — reintento con retroceso exponencial, manejo tipificado de excepciones y una bifurcación específica para negativas — y su chatbot se degradará con elegancia bajo carga, en lugar de fallar estrepitosamente ante las personas para las que fue diseñado.

Preguntas frecuentes

¿Cómo construyo un chatbot con la API de Claude?

Instala el SDK de Anthropic, obtén una clave de API y llama a la API Messages: envía una lista de mensajes y Claude devolverá una respuesta. Para lograr un comportamiento conversacional, debes mantener tú mismo el historial de mensajes y reenviarlo en cada turno. Añade una indicación del sistema para darle personalidad y usa la transmisión en tiempo real (streaming) para una sensación de inmediatez.

¿Recuerda la API de Claude los mensajes anteriores?

No: la API es sin estado (stateless). Solo conoce lo que le envías en una solicitud determinada. Para dotar al chatbot de memoria, tu aplicación debe almacenar el historial de conversación e incluirlo en la lista messages en cada llamada.

¿Qué es una indicación del sistema?

La indicación del sistema es una instrucción independiente que define el rol, el tono y las reglas del chatbot —por ejemplo, «Eres un asistente de soporte conciso; deriva al cliente a un agente humano si tienes dudas». Se pasa como el parámetro system y es la forma principal de definir cómo se comportará el bot.

¿Cuánto cuesta ejecutar un chatbot con la API de Claude?

El costo depende del modelo y del número de tokens procesados. Un modelo equilibrado resulta económico para el tráfico típico de chat. Dado que los chatbots reenvían la indicación del sistema y el historial en crecimiento en cada turno, habilitar la memoria caché de indicaciones puede reducir significativamente los costos: reutiliza las partes estables de la indicación en lugar de procesarlas repetidamente.

¿Qué modelo de Claude debo usar para un chatbot?

Para la mayoría de los chatbots, comienza con un modelo rápido y equilibrado (nivel Sonnet): ofrece una calidad sólida a una velocidad y costo razonables. Usa el modelo más capaz para tareas complejas de razonamiento y un modelo más pequeño y rápido para chatbots simples y de alto volumen.

¿Qué significan los errores 429 y 529 de la API de Claude?

Un 429 significa que ha alcanzado el límite de velocidad de su cuenta (solicitudes o tokens por minuto); la respuesta incluye un encabezado retry-after que le indica cuánto tiempo debe esperar. Un 529 significa que la API de Anthropic está temporalmente sobrecargada para todos los usuarios — dichas solicitudes no generan cargo y no pueden evitarse mediante código. Ambos casos requieren retroceso exponencial, que los SDK oficiales aplican automáticamente por defecto.

¿Cómo debe manejar mi chatbot una negativa de Claude?

Una negativa llega como una respuesta normal y válida con stop_reason: "refusal"stop_reason: "refusal" stop_details que indica qué política se activó.

¿Necesito escribir mi propia lógica de reintento para la API de Claude?

Normalmente no. Los SDK oficiales de Anthropic ya reintentan automáticamente los errores 429 y 5xx con retroceso exponencial, con un valor predeterminado de dos reintentos. Para un chatbot orientado al usuario, la configuración más sencilla y robusta consiste en aumentar max_retries max_retries RateLimitError y OverloadedErrorRateLimitError

Conclusión

Construir un chatbot con la API de Claude consiste principalmente en la integración técnica, no en la inteligencia artificial. El modelo se encarga de comprender y generar respuestas; tú proporcionas el bucle. Mantén un historial messages y reenvíalo para otorgar memoria, usa una indicación del sistema system para darle personalidad, aplica streaming para mejorar la sensación de inmediatez y activa la memoria caché de indicaciones para controlar los costos.

Ese núcleo básico realmente requiere tan solo una hora de trabajo. El camino hacia la producción implica la ingeniería habitual que lo rodea: una capa web, gestión del historial, manejo de errores y RAG si el bot necesita conocer tus propios datos. Comienza con el bucle simple mostrado arriba, haz que funcione y construye progresivamente a partir de ahí.