D4 · Prompt Engineering › Cluster 2 · Roles & System Prompts

2.1 · The System Parameter vs the User Turn

Where the role lives in the API

CONCEPT Two channels: the system prompt and the conversation

Every Messages API request has two distinct places to put text. The top-level system parameter holds the role, standing instructions, and context that apply to the whole conversation. The messages array holds the turns — the back-and-forth of user and assistant messages that carries the actual task and data.

system is not a message with "role": "system" inside the messages list (that's the OpenAI shape). In Anthropic's API it is a separate top-level field, and it accepts either a plain string or a list of content blocks (text blocks, optionally with cache_control).

FieldWhereHoldsChanges how often
systemTop-level parameterRole / persona, standing instructions, stable contextRarely — same across many requests
messages[] (user)Conversation arrayThe task, the data, the question this turnEvery turn
messages[] (assistant)Conversation arrayClaude's replies (echoed back for history)Every turn
🔑 The API is stateless: there is no server-side memory. You resend system + the full messages history on every call. The system string is the same each time; the messages array grows.
Render order on the wire is tools → system → messages. Because system sits near the front and rarely changes, it's the ideal place for a cache_control breakpoint (prompt caching keys off a stable prefix).

DIAGRAM One request, two channels

flowchart TD REQ["messages.create( … )"] --> SYS["system= (top-level)
role · standing instructions · context"] REQ --> MSG["messages=[ … ]
the turns"] MSG --> U["user: the task / data
(this turn)"] MSG --> A["assistant: Claude's reply
(echoed for history)"] SYS --> CLAUDE["Claude reads system first,
then the conversation"] U --> CLAUDE A --> CLAUDE classDef sys fill:#d4edda,stroke:#28a745,color:#155724; classDef turn fill:#e7f0fd,stroke:#4a90d9,color:#1a3d6d; class SYS,CLAUDE sys; class MSG,U,A turn;

CODE A real anthropic call with system=

The role goes in system; the task goes in a user message. This is the exact shape from the official docs.

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    system="You are a helpful coding assistant specializing in Python.",  # the role / standing instructions
    messages=[
        {"role": "user", "content": "How do I sort a list of dictionaries by key?"},  # the task, this turn
    ],
)
print(message.content)

# system can also be a LIST of blocks — useful for a cache breakpoint:
system=[
    {"type": "text", "text": LONG_STABLE_PROMPT,
     "cache_control": {"type": "ephemeral"}},
]

TRADE-OFFS String system prompt vs. list of blocks

✅ Plain string

  • Simplest — one line for a role
  • Perfect for short personas & scripts
  • No block bookkeeping

✅ List of text blocks

  • Lets you attach cache_control to cache a large stable prompt
  • Can split stable vs. volatile sections
  • Slightly more verbose
Both are valid values of the same system parameter. Reach for the list form only when you need caching or per-block control; otherwise a string is fine.

EXAM TRAPS

Trap: Putting {"role": "system", …} inside messages as the primary system prompt. → In the Anthropic Messages API the standing role goes in the top-level system parameter, not as a message role. (A mid-conversation role:"system" message exists on newer models, but it's an operator-instruction channel, not where you set the initial role.)
Trap: "The system parameter must be a string." → It accepts a string OR a list of content blocks. The list form is how you add a cache_control breakpoint.
Trap: Assuming the API remembers the system prompt between calls. → The API is stateless. You resend system and the full history every request.
Trap: Stuffing the per-request question into system. → That belongs in the user turn. Volatile, per-call content in system also breaks prompt caching (2.5, and the caching cluster).

PRACTICE

Q1 · Where does the role/persona go, and where does the task go?

The role/persona goes in the top-level system parameter (stable across the conversation). The task/data goes in a user message inside the messages array (changes every turn).

Q2 · What two types can the system parameter be?

A plain string, or a list of content blocks (text blocks that can each carry cache_control). Use the list form when you want to cache a large stable prompt.

Q3 · Why is system the natural place for a cache breakpoint?

Render order is tools → system → messages, and system rarely changes. A stable prefix is exactly what prompt caching needs — a byte change early in the prefix invalidates everything after it, so keep the volatile content in later user turns.