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).
| Field | Where | Holds | Changes how often |
|---|---|---|---|
system | Top-level parameter | Role / persona, standing instructions, stable context | Rarely — same across many requests |
messages[] (user) | Conversation array | The task, the data, the question this turn | Every turn |
messages[] (assistant) | Conversation array | Claude's replies (echoed back for history) | Every turn |
system + the full messages history on every call. The system string is
the same each time; the messages array grows.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
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_controlto cache a large stable prompt - Can split stable vs. volatile sections
- Slightly more verbose
system parameter. Reach for the list form only
when you need caching or per-block control; otherwise a string is fine.EXAM TRAPS
{"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.)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.system and the full history every request.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.