D1 · Agentic Architecture › Cluster 1 · Foundations

1.5 · Message Structure & Content Blocks

Roles, alternation, and the typed-block list inside content

CONCEPT Messages: roles & alternation

A conversation is a list of messages, each {role, content}. Two rules govern their shape:

🔑 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 typeAppears inKey field(s)What it carries
textuser & assistant.textPlain natural-language text
thinkingassistant.thinkingExtended reasoning (when enabled)
tool_useassistant.name, .input, .idThe model's request to call a tool
tool_resultuser.tool_use_id, .contentThe 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.