Messages, Roles, and System Prompts

Every request to a large language model API is a list of messages, and each message carries two things: who is speaking and what they said. The model's whole job is to predict what the next message in that list should be. This sounds trivial, but it is the single idea everything else in this course builds on: prompting is not a monologue you write once, it is a conversation you construct, message by message, and the model only ever sees the list you hand it.

Each message has a role — a short tag telling the model (and anything wrapped around it) what kind of speaker produced that content. The most universal roles are user, for what the person asked, and assistant, for what the model previously said. Everything else — the channel for your own instructions — differs by provider, and getting it right is the first skill in this course.

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[
        {"role": "developer", "content": "You are a concise support assistant. Never invent order numbers."},
        {"role": "user", "content": "Where is my order #48213?"},
    ],
)
print(response.choices[0].message.content)

OpenAI's Chat Completions and Responses APIs recognize five message roles: system, developer, user, assistant, and tool. The developer role gives an application's own instructions a clear, higher-priority place in what OpenAI calls its instruction hierarchy — its API reference describes it as carrying instructions the model should follow ahead of anything a user says. Many teams still reach for system out of habit, and the two behave close enough alike for most applications, but developer is the one designed to win when a user's message tries to argue with it.

Anthropic takes a different shape entirely. In the Messages API there is no system-role message you add to the messages array for your opening instructions — instead there's a separate top-level system parameter that sits outside the conversation entirely. A specific set of newer Claude models also accepts a system-role message inside messages, but only after the first user turn, as a way to inject fresh instructions partway through a long conversation without invalidating anything cached before it.

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system="You are a concise support assistant. Never invent order numbers.",
    messages=[
        {"role": "user", "content": "Where is my order #48213?"}
    ],
)
print(message.content)

None of this is just API trivia. Separating instructions from user content is a real, if partial, defense: a model told "the text below is untrusted input" behaves differently than one that received the same text with no framing at all. It is not a security boundary — a determined attacker can still write user text that reads like an instruction — but it measurably reduces how often a model follows an instruction smuggled inside data it was only supposed to read.

The practical rule of thumb is narrow scope for the instruction channel: role, tone, and non-negotiable constraints belong in system or developer; the specific task, question, and any data to work on belong in user. When that data is long — a document, a codebase, a transcript — put it near the top of the user turn, above your actual question. Providers report this ordering consistently improves how well the model attends to the query that follows it.