Claude and the Anthropic SDK · Chapter 2 of 21

The system prompt and the conversation

By the end of this chapter you can give Claude standing instructions and a document with the system argument (as a string or as text blocks), hold a conversation by sending its whole history every time, add an instruction in the middle of a conversation, and explain why the old "prefill" trick is now a 400 and what replaces it. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: The Messages API
  • 4 tasks
  • Python
  • Free chapter

Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.

Why you need this

In chapter 1, Claude was confidently wrong about Pooja's bill until the request carried the policy. Sahay needs that on every request: who it is, how to answer, and the policy wording it answers from. Kamla also wants families to chat with Sahay: "My father was admitted on Monday", then "So how much will they pay?", and the second message only makes sense with the first.

So far you have sent one message and read one reply. That cannot hold a conversation: the Messages API keeps nothing between requests. There is no session and no chat id. If the family's first message is not in the second request, Claude has never seen it. And if you come from an OpenAI-style API, two habits will bite: the system prompt is not a message here, and ending a request with a half-written assistant message (a "prefill") is now refused.

The lesson

The system prompt

system is an argument of the request, beside model, max_tokens and messages. It is where the operator (you, the developer) puts what holds for the whole conversation: who the assistant is, how it should answer, and documents it works from. The family's words go in messages; Parchi's rules go in system.

import anthropic

from parchi import policy_wording

SYSTEM = "You are Sahay, Parchi's claims assistant.\n\n" + policy_wording()

client = anthropic.Anthropic()
reply = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system=SYSTEM,
    messages=[{"role": "user", "content": "What is the room rent limit?"}],
)

Without system, and with it:

none:   Most health policies pay the room rent in full for a standard private room, so you should not have to worry about the room you choose.  (11 tokens in)
system: Clause 2.1 of the policy says: For each day of hospitalisation in a normal room, the policy pays room rent up to 1% of the sum insured per day.  (3013 tokens in)

The system prompt is input like any other: it is counted in reply.usage.input_tokens and billed, on every request. The policy is 2,990 of those 3,013 tokens. Chapter 13 makes repeating it cheap with prompt caching.

system as text blocks

system can also be a list of text blocks, the same {"type": "text", "text": ...} dictionaries as message content:

system=[
    {"type": "text", "text": "You are Sahay, Parchi's claims assistant."},
    {"type": "text", "text": policy_wording()},
],
blocks: Clause 2.1 of the policy says: For each day of hospitalisation in a normal room, the policy pays room rent up to 1% of the sum insured per day.  (3012 tokens in)

Claude reads the blocks in order, as one prompt, so the answer is the same. Blocks keep separate pieces separate: the short instructions you edit often, and the long document you never touch. That matters in chapter 13, where a cache breakpoint (cache_control) is set on one block, and a string has no blocks to set it on.

The API is stateless

Ask, then ask again in a new request:

client.messages.create(..., messages=[{"role": "user", "content": "Namaste! My name is Ravi Kumar."}])
client.messages.create(..., messages=[{"role": "user", "content": "What is my name?"}])
I don't know your name yet: you haven't told me in this conversation.

The second request carried one message, so that is all Claude knew. A conversation is something your code keeps: a list of messages that grows by two each turn (the user's message, then Claude's reply), sent whole every time:

history: list[anthropic.types.MessageParam] = []

history.append({"role": "user", "content": "Namaste! My name is Ravi Kumar."})
first = client.messages.create(model="claude-opus-5-5", max_tokens=1024, messages=history)
history.append({"role": "assistant", "content": first.content})

history.append({"role": "user", "content": "What is my name?"})
second = client.messages.create(model="claude-opus-5-5", max_tokens=1024, messages=history)
Your name is Ravi Kumar.

The second request carried three messages: user, assistant, user. Every turn resends everything before it, so a long chat costs more input tokens with each turn (chapter 13 is how you stop paying full price for the repeated part).

The rules of messages

  • Each message is a dictionary, {"role": ..., "content": ...}, and role is "user" or "assistant" (or "system", below). The SDK's type is anthropic.types.MessageParam; use it in your history's type hint.
  • The first message is the user's. Starting with Claude is a 400. The SDK raises it as an exception:

`` anthropic.BadRequestError: Error code: 400 - {'type': 'error', 'error': {'type': 'invalid_request_error', 'message': 'messages: first message must use the "user" role'}, 'request_id': 'req_011COSI0kiVa9M1eX6FNfPGc'} ``

  • User and assistant usually take turns. Two user messages in a row are allowed: the API joins them into one turn.
  • Claude's turns go back exactly as Claude wrote them: {"role": "assistant", "content": reply.content}, every block, not just the text. reply.content is a list of the SDK's block objects, and the SDK sends them back as JSON for you: you do not turn them into dictionaries. On Opus 5.5 a reply to a bill is [thinking, text], and the thinking block carries a signature that must come back unchanged (chapter 16). In chapter 6 a reply holds tool_use blocks, and your next message must answer them. Copying only the text drops both.

A system message mid-conversation

Sometimes an instruction arrives in the middle: the family moves to WhatsApp, or Sahay hands over to a person. You could edit the top-level system, but that changes the start of every request (and, in chapter 13, throws away the cache). Instead, the new instruction joins the conversation as a message with the role "system":

messages=[
    {"role": "user", "content": "My claim was rejected and I disagree. What can I do?"},
    {"role": "system", "content": "Answer in one sentence."},
],

Without it, and with it (the same SYSTEM in both):

without: Clause 12.1 of the policy says: A policyholder who disagrees with a decision can write to the grievance officer through the Parchi app. The grievance officer replies within 14 days.
with:    Clause 12.1 of the policy says: A policyholder who disagrees with a decision can write to the grievance officer through the Parchi app.

That is 45 output tokens without it and 34 with it. The message carries the operator's authority, like system, but sits where it happened. Its placement has rules:

  • it follows a user message (never first, never right after Claude's turn);
  • it is the last message, or the next message is the assistant's.

Broken, each rule is a 400 (the API's own messages, from e.body["error"]["message"]):

messages.0.role: the first message must use the "user" role
messages.2: a system message must follow a user message

(Mid-conversation system messages work on the current models. On a model that does not support them the API answers with a 400 too.)

No prefill

Older Claude models let a request end with an assistant message, and Claude carried on from it. It was a popular trick: end with Category: and the reply is only the label; end with { and the reply is JSON. That is a prefill, and on Opus 5.5, Sonnet 5.5 and Haiku 5.5 it is refused before anything is written:

messages=[
    {"role": "user", "content": "Mera claim kab tak aayega?"},
    {"role": "assistant", "content": "Category:"},
],
anthropic.BadRequestError: Error code: 400 - {'type': 'error', 'error': {'type': 'invalid_request_error', 'message': 'This model does not support assistant message prefill. The conversation must end with a user message.'}, 'request_id': 'req_011CRfp1I4LTwUTOFAxzNtvE'}

The SDK raises a 400 as anthropic.BadRequestError. Catch that class, not every exception, and read what you need from it: e.status_code is 400, e.type is "invalid_request_error", and the API's own words are in e.body["error"]["message"] (e.message is the whole line above).

try:
    client.messages.create(...)
except anthropic.BadRequestError as e:
    print(e.status_code, e.type)
400 invalid_request_error

Assistant messages earlier in the list are fine (that is the history); only a last assistant message is a prefill. What to do instead depends on what the prefill was for (Anthropic's migration guide):

The prefill was forNow
a label or a short answer onlysay so in the system prompt ("Reply with the label only")
skipping a preamble ("Here is...")say so in the system prompt
JSON of a fixed shapestructured output, output_config with a format (chapter 9)
continuing a reply that was cut offa new user message that asks to continue (chapter 3)

With the instruction in system (here on Haiku 5.5, the cheap model for labels), a message from the inbox comes back as the label alone:

without the instruction: Category: claim_status
with "Reply with the category label only, nothing else.": claim_status

Coming from the OpenAI-style API

OpenAI-style chat completionsClaude's Messages API
{"role": "system"} as the first messagethe top-level system argument (string or blocks)
system messages anywherea "system" message only after a user message
history: role and a stringhistory: role and the reply's content blocks
an assistant message last to continuea 400: end with a user message

The lab's Claude

The stand-in follows a few plain instructions in a system prompt or a system message: "answer in one sentence", "under N words", "label only". A real Claude model follows any instruction you can write, far beyond these. What is the same is the API: where instructions go, what a request must carry, and what is refused.

Your turn

Give Sahay its two-block system prompt in task 1. Build a chat that remembers in task 2, and switch a conversation to one-sentence WhatsApp replies in task 3. In the interview question, show why the old classifier fails and fix it.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    system_blocks.py: the system prompt, as blocks

    Send one request to "claude-opus-5-5" (max_tokens 1024) whose system is a list of two text blocks: first "You are Sahay, Parchi's claims assistant. Answer in one sentence.", then policy_wording(). The one user message is exactly: Does the policy pay for the ICU?

    Print answer: TEXT (the reply's text blocks, joined), then input tokens: N (reply.usage.input_tokens).

  2. Task 2

    chat.py: a conversation that remembers

    Define ask(history, text) -> str: append {"role": "user", "content": text} to history, send "claude-opus-5-5" (max_tokens 1024, system=SYSTEM) the whole history, append {"role": "assistant", "content": reply.content} to history, and return the reply's text blocks, joined.

    The check asks two questions in one history: the second request must carry the first question and Claude's answer, as Claude wrote it.

  3. Task 3

    mid_conversation.py: an instruction mid-conversation

    Send "claude-opus-5-5" (max_tokens 1024) with system=SYSTEM and messages: HISTORY followed by one more message, {"role": "system", "content": "The family is reading this on WhatsApp now: answer in one sentence."}.

    Print reply: TEXT (the reply's text blocks, joined), then lines: N (the number of lines in TEXT).

  4. Task 4 · interview question

    Interview: no_prefill.py

    "Our classifier prefilled the assistant turn with 'Category:' and now every request fails. Why, and what instead?" Send OLD_REQUEST with client.messages.create(**OLD_REQUEST), catch the error (an anthropic.BadRequestError) and print old way: STATUS TYPE (e.status_code, e.type).

    Then send the same user message to "claude-haiku-5-5" (max_tokens 1024) with nothing after it and system="Reply with the category label only, nothing else." Print label: TEXT.

What you will learn

  • system: Claude's standing instructions, as a string or a list of text blocks.
  • The API is stateless: you keep the history and send all of it, in order.
  • The roles: the first message is the user's, and Claude's turns go back exactly as Claude wrote them.
  • Mid-conversation system messages: a new instruction where it happens, and where it may go.
  • No prefill: the 400, and what to do instead.

More in The Messages API

Build The system prompt and the conversation yourself

Parchi, a Jaipur startup, helps families claim health insurance. You build Sahay, a claims assistant that reads bills and policies with Claude, and measure what caching, models and effort cost. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.