Building Multi-Turn Conversations with the Messages Array

A real conversation with Claude isn't one API call - it's a sequence of calls, each carrying the entire history so far.

This page covers the practical mechanics of building and maintaining that history in application code.

Summary

The Messages API has no server-side memory of past requests.

Every call is evaluated independently, using only the messages array included in that specific request.

To build a conversation that feels continuous, your application owns a growing list of turns and resends the whole thing every time.

This is a deliberate design: it keeps the API simple and stateless, and it puts you in full control of exactly what context Claude sees on each turn.

The tradeoff is that state management - appending turns correctly, in the right order, with the right content - becomes your application's job.

Recipe

Quick-reference recipe card - copy-paste ready.

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="You are a helpful assistant.",
        messages=messages,
    )
 
    messages.append({"role": "assistant", "content": response.content})
    return response.content[0].text

When to reach for this:

• Any chat-style interface where the user sends more than one message per session.
• Agentic loops where Claude's replies (including tool calls) need to inform its next turn.
• Backend services that maintain a conversation per user, session, or ticket.
• Anywhere you need Claude to refer back to something said earlier in the same interaction.

Working Example

import anthropic
 
client = anthropic.Anthropic()
 
 
class Conversation:
    """Owns the messages array for one conversation and appends to it on every turn."""
 
    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,
        )
 
        # Append the full content list, not just the extracted text, so any
        # non-text blocks (tool_use, etc.) are preserved for future turns.
        self.messages.append({"role": "assistant", "content": response.content})
 
        # Concatenate only the text blocks for the caller-facing return value.
        return "".join(block.text for block in response.content if block.type == "text")
 
 
if __name__ == "__main__":
    convo = Conversation(system_prompt="You are a helpful trip-planning assistant.")
 
    print(convo.send("I'm planning a trip to Japan in April."))
    print(convo.send("What should I pack, given what I just told you?"))
    print(convo.send("How many messages have we exchanged so far?"))

What this demonstrates:

• A small Conversation class owns self.messages so state doesn't leak into module-level globals.
• send() appends the user turn before the API call and the assistant turn after, keeping strict role alternation intact.
• The full response.content list is stored, not a plain string, so tool-use blocks or other structured content survive into later turns.
• system_prompt is set once at construction and reused unchanged across every call in the conversation.

Deep Dive

How It Works

• Each call to client.messages.create() is fully self-contained: the API has no session concept, no conversation ID, and no memory between requests.
• The messages list you send is walked in order; the API validates that it starts with user and strictly alternates roles from there.
• Claude's reply arrives as a Message object whose .content is a list of content blocks - typically one text block for a plain reply, but potentially more for tool use or mixed content.
• Appending response.content (the object, not the derived string) as the next assistant turn is what lets Claude "see" its own prior reasoning and tool calls on the next request.
• Because the whole array is resent, both the request payload size and the number of billed input tokens grow as the conversation lengthens - covered further in the context-window management page.

Turn Growth Per Exchange

Every exchange adds exactly two entries: one user, one assistant.

Python Notes

# Prefer a typed structure over loose dicts if you're managing many conversations.
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]

Using a small wrapper type (or a dataclass, as above) instead of raw dicts scattered through your codebase makes it much easier to serialize a conversation to storage and reload it later without guessing at the shape.

Gotchas

• Appending only response.content[0].text instead of the full content list. This discards tool_use blocks and any structured content, breaking tool-use flows on the next turn. Fix: always append response.content as-is for the assistant turn; extract text separately for display.
• Forgetting to append the user turn before calling the API. The array sent to messages.create() must already include the latest question. Fix: append the user turn first, then call the API, then append the reply.
• Mutating the same system string mid-conversation. Editing the system prompt between calls works, but it silently invalidates any prompt cache built on the prior prefix and can shift Claude's behavior mid-conversation in confusing ways. Fix: keep the system prompt frozen for the life of a conversation unless you have an explicit reason to change it.
• Letting the messages array grow unbounded. Every request resends the full history, so a very long conversation eventually risks exceeding the model's context window and increases cost on every call. Fix: plan for trimming or summarizing older turns before that happens.
• Sharing one mutable messages list across concurrent users. A single global list used by multiple simultaneous conversations will interleave unrelated turns and break alternation. Fix: scope one messages list per conversation/session, never a module-level shared list.
• Assuming the API deduplicates or ignores repeated context. Sending the same information twice in the array (e.g., duplicating a large document in two different user turns) is billed as separate input tokens both times. Fix: include shared context once, and rely on it staying in the conversation's history rather than re-sending it.

Alternatives

FAQs

Related

• Understanding Roles and Turns in the Messages API - the conceptual model this page builds on.
• Messages API Basics - shorter, example-driven intro to the same mechanics.
• Managing Conversation History and Trimming for the Context Window - what to do once the array gets too large.
• Messages API Roles and Content Block Types Reference - reference for every content block type you might append.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the official anthropic Python SDK (latest 0.x release). Model names, SDK versions, and pricing move quickly - verify current specifics at platform.claude.com/docs before relying on them.