CONCEPT Messages: roles & alternation
A conversation is a list of messages, each {role, content}. Two rules
govern their shape:
- Roles alternate user → assistant → user → …
- The first message is
user. - Consecutive same-role messages are merged into one — you can't have two
userturns back-to-back as separate entries; they collapse.
🔑 Only two roles exist in
messages[]: user and
assistant. The system prompt is a separate top-level field, not a role
(see 1.2). And tool outputs are fed back as user-role tool_result blocks.CONCEPT content is a list of typed blocks
content is not a string — it's a list of blocks, each with
a type. Four block types matter:
| Block type | Appears in | Key field(s) | What it carries |
|---|---|---|---|
text | user & assistant | .text | Plain natural-language text |
thinking | assistant | .thinking | Extended reasoning (when enabled) |
tool_use | assistant | .name, .input, .id | The model's request to call a tool |
tool_result | user | .tool_use_id, .content | The tool's output you feed back |
⚠️ Because a turn can lead with a
thinking or tool_use block,
never read content[0].text blindly — the first block may not be a
text block and may have no .text attribute at all. Always check
block.type first.DIAGRAM Message → blocks tree
flowchart TD
M["messages[] (alternating user/assistant)"] --> U1["👤 user turn"]
M --> A1["🤖 assistant turn"]
M --> U2["👤 user turn (tool_result)"]
U1 --> UB1["block: text (.text)"]
A1 --> AB1["block: thinking (.thinking)"]
A1 --> AB2["block: text (.text)"]
A1 --> AB3["block: tool_use (.name/.input/.id)"]
U2 --> UB2["block: tool_result (.tool_use_id/.content)"]
classDef usr fill:#d1ecf1,stroke:#17a2b8,color:#0c5460;
classDef asst fill:#e2d4f0,stroke:#764ba2,color:#3d1a5b;
class U1,U2,UB1,UB2 usr; class A1,AB1,AB2,AB3 asst;
CODE Iterate blocks safely by type
# Never assume content[0] is text. Dispatch on block.type. resp = client.messages.create( model="claude-opus-4-8", max_tokens=1024, tools=TOOLS, messages=messages, ) text_parts, tool_calls = [], [] for block in resp.content: if block.type == "text": text_parts.append(block.text) elif block.type == "thinking": pass # reasoning; keep it in history, don't show elif block.type == "tool_use": tool_calls.append(block) # block.name, block.input, block.id answer = "".join(text_parts) # safely assembled visible text # Feeding a tool result back? It's a USER-role tool_result block. messages.append({ "role": "user", "content": [{ "type": "tool_result", "tool_use_id": tool_calls[0].id, "content": "22°C, sunny", }], })
This pattern is robust regardless of whether the model used thinking, tools, both, or
neither — the same loop handles every combination because it dispatches on
block.type.TRADE-OFFS Typed blocks vs. a plain string
✅ Why a block list
- One shape carries text, reasoning, tool calls & results together
- Ordering is preserved (thinking → text → tool_use)
- Multimodal & tool content extend cleanly as new block types
⚠️ What it demands of you
- You must iterate and branch on
type— no naive[0].text - Feeding results back means constructing the right block shape & role
- More verbose than a single string field
EXAM TRAPS
Trap: Reading
content[0].text and assuming it's the answer. → With
thinking or tool use, the first block may be thinking or tool_use and have no
.text. Iterate and check block.type.Trap: Putting
tool_result in an assistant turn. →
tool_result is user-role content. Wrong role breaks alternation and the request fails.Trap: Expecting two consecutive same-role messages to stay separate. → Consecutive
same-role messages are merged. If you need distinct turns, they must alternate roles.
Trap: Sending an assistant message first, or a non-user first message. → The
first message must be
user, and roles alternate from there.PRACTICE
Q1 · Your code crashes with "block has no attribute text" on some responses. Cause & fix?
You read block.text (or content[0].text) on a non-text block —
likely a thinking or tool_use block that leads the turn. Fix: iterate
resp.content and only touch .text when block.type == "text".
Q2 · What role does a tool_result block live in, and what links it to its call?
It lives in a user-role message. It's linked to the originating
tool_use block by tool_use_id (which equals the tool_use block's
id).
Q3 · You add two user messages in a row expecting two turns. What happens?
They get merged into a single user turn — consecutive same-role messages collapse.
Roles must alternate user/assistant, and the first message must be user. To keep turns
distinct, interleave assistant turns.