Construcción de Conversaciones Multi-turno con el Array de Mensajes

Una conversación real con Claude no es una sola llamada a la API, sino una secuencia de llamadas, cada una llevando consigo todo el historial hasta el momento.

Esta página cubre la mecánica práctica de construir y mantener ese historial en el código de la aplicación.

Resumen

La API de Mensajes no tiene memoria del lado del servidor de solicitudes pasadas.

Cada llamada se evalúa de forma independiente, utilizando únicamente el array messages incluido en esa solicitud específica.

Para construir una conversación que se sienta continua, tu aplicación posee una lista creciente de turnos y reenvía todo cada vez.

Este es un diseño deliberado: mantiene la API simple y sin estado, y te da control total sobre exactamente qué contexto ve Claude en cada turno.

La contrapartida es que la gestión del estado —añadir turnos correctamente, en el orden adecuado, con el contenido correcto— se convierte en el trabajo de tu aplicación.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

import anthropic
 
client = anthropic.Anthropic()
messages = []
 
def send(user_text: str) -> str:
    messages.append({"role": "user", "content": user_text})
 
    response = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        system="Eres un asistente útil.",
        messages=messages,
    )
 
    messages.append({"role": "assistant", "content": response.content})
    return response.content[0].text

Cuándo usar esto:

• Cualquier interfaz de estilo chat donde el usuario envía más de un mensaje por sesión.
• Bucles de agente donde las respuestas de Claude (incluidas las llamadas a herramientas) necesitan informar su siguiente turno.
• Servicios backend que mantienen una conversación por usuario, sesión o ticket.
• Cualquier lugar donde necesites que Claude se refiera a algo dicho anteriormente en la misma interacción.

Ejemplo de Trabajo

import anthropic
 
client = anthropic.Anthropic()
 
 
class Conversation:
    """Posee el array de mensajes para una conversación y lo añade en cada turno."""
 
    def __init__(self, system_prompt: str, model: str = "claude-opus-4-8"):
        self.system_prompt = system_prompt
        self.model = model
        self.messages: list[dict] = []
 
    def send(self, user_text: str, max_tokens: int = 1024) -> str:
        self.messages.append({"role": "user", "content": user_text})
 
        response = client.messages.create(
            model=self.model,
            max_tokens=max_tokens,
            system=self.system_prompt,
            messages=self.messages,
        )
 
        # Añade la lista completa de contenido, no solo el texto extraído, para que
        # los bloques de uso de herramientas u otro contenido estructurado se conserven para turnos futuros.
        self.messages.append({"role": "assistant", "content": response.content})
 
        # Concatena solo los bloques de texto para el valor de retorno visible para el llamador.
        return "".join(block.text for block in response.content if block.type == "text")
 
 
if __name__ == "__main__":
    convo = Conversation(system_prompt="Eres un asistente útil para planificar viajes.")
 
    print(convo.send("Estoy planeando un viaje a Japón en abril."))
    print(convo.send("¿Qué debería empacar, dado lo que te acabo de decir?"))
    print(convo.send("¿Cuántos mensajes hemos intercambiado hasta ahora?"))

Lo que esto demuestra:

• Una pequeña clase Conversation posee self.messages para que el estado no se filtre a variables globales del módulo.
• send() añade el turno del user antes de la llamada a la API y el turno del assistant después, manteniendo una estricta alternancia de roles intacta.
• Se almacena la lista completa de response.content, no una cadena de texto plano, para que los bloques de uso de herramientas u otro contenido estructurado sobrevivan a turnos posteriores.
• system_prompt se establece una vez en la construcción y se reutiliza sin cambios en cada llamada de la conversación.

Análisis Profundo

Cómo Funciona

• Cada llamada a client.messages.create() es completamente autocontenida: la API no tiene concepto de sesión, ni ID de conversación, ni memoria entre solicitudes.
• La lista messages que envías se recorre en orden; la API valida que comience con user y alterne estrictamente los roles a partir de ahí.
• La respuesta de Claude llega como un objeto Message cuyo .content es una lista de bloques de contenido —típicamente un bloque de text para una respuesta simple, pero potencialmente más para uso de herramientas o contenido mixto.
• Añadir response.content (el objeto, no la cadena derivada) como el siguiente turno del assistant es lo que permite a Claude "ver" su propio razonamiento y llamadas a herramientas anteriores en la siguiente solicitud.
• Dado que se reenvía todo el array, tanto el tamaño de la carga útil de la solicitud como el número de tokens de entrada facturados crecen a medida que la conversación se alarga —cubierto más a fondo en la página de gestión de la ventana de contexto.

Crecimiento de Turnos por Intercambio

Cada intercambio añade exactamente dos entradas: un user y un assistant.

Notas de Python

# Prefiere una estructura tipada sobre diccionarios sueltos si estás gestionando muchas conversaciones.
from dataclasses import dataclass, field
 
@dataclass
class Turn:
    role: str
    content: str | list
 
@dataclass
class Session:
    messages: list[Turn] = field(default_factory=list)
 
    def as_api_payload(self) -> list[dict]:
        return [{"role": t.role, "content": t.content} for t in self.messages]

Usar un pequeño tipo contenedor (o una dataclass, como la de arriba) en lugar de diccionarios crudos dispersos por tu código base hace que sea mucho más fácil serializar una conversación para su almacenamiento y recargarla más tarde sin adivinar la forma.

Trampas Comunes

• Añadir solo response.content[0].text en lugar de la lista completa de contenido. Esto descarta los bloques tool_use y cualquier contenido estructurado, rompiendo los flujos de uso de herramientas en el siguiente turno. Solución: siempre añade response.content tal cual para el turno del asistente; extrae el texto por separado para mostrarlo.
• Olvidar añadir el turno del usuario antes de llamar a la API. El array enviado a messages.create() ya debe incluir la última pregunta. Solución: añade primero el turno del usuario, luego llama a la API, y después añade la respuesta.
• Mutar la misma cadena system a mitad de la conversación. Editar el prompt del sistema entre llamadas funciona, pero invalida silenciosamente cualquier caché de prompt construida sobre el prefijo anterior y puede cambiar el comportamiento de Claude a mitad de la conversación de maneras confusas. Solución: mantén el prompt del sistema fijo durante la vida de una conversación a menos que tengas una razón explícita para cambiarlo.
• Permitir que el array de mensajes crezca sin límites. Cada solicitud reenvía todo el historial, por lo que una conversación muy larga eventualmente corre el riesgo de exceder la ventana de contexto del modelo y aumenta el costo en cada llamada. Solución: planifica recortar o resumir turnos más antiguos antes de que eso suceda.
• Compartir una lista messages mutable entre usuarios concurrentes. Una sola lista global utilizada por múltiples conversaciones simultáneas intercalará turnos no relacionados y romperá la alternancia. Solución: delimita una lista messages por conversación/sesión, nunca una lista compartida a nivel de módulo.
• Asumir que la API elimina duplicados o ignora contexto repetido. Enviar la misma información dos veces en el array (por ejemplo, duplicar un documento grande en dos turnos user diferentes) se factura como tokens de entrada separados ambas veces. Solución: incluye el contexto compartido una vez y confía en que permanecerá en el historial de la conversación en lugar de reenviarlo.

Alternativas

Preguntas Frecuentes

Relacionado

• Entendiendo los Roles y Turnos en la API de Mensajes - el modelo conceptual en el que se basa esta página.
• Conceptos Básicos de la API de Mensajes - introducción más corta y basada en ejemplos de la misma mecánica.
• Gestión del Historial de Conversaciones y Recorte para la Ventana de Contexto - qué hacer una vez que el array se vuelve demasiado grande.
• Referencia de Roles y Tipos de Bloques de Contenido de la API de Mensajes - referencia para cada tipo de bloque de contenido que puedas añadir.

Versiones de Stack: 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 modelos, versiones de SDK y precios cambian rápidamente — verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.