Deel B · Module 01
De Messages-API
Wat gaat er écht over de lijn?
Leerdoelen
Na deze module kun je:
- voorspellen wat het model te zien krijgt bij beurt n, en waarom
usage.input_tokensper beurt oploopt; - een request en response veld voor veld uitleggen en aanwijzen waar je
stop_reason, rollen en content-blokken moet controleren; - een multi-turn gesprek bouwen waarbij je de
messages-lijst zelf beheert, en de gebruikelijke fouten (vergeten assistant-bericht, samengevoegde beurten) herkennen en herstellen.
Voorkennis-check
Twee vragen over eerdere modules. Fout? Lees die module eerst terug.
Waar zitten we?
Laag 2 van de stack: de API is het enige contact tussen jouw code en het model. Alles wat een agent doet, is uiteindelijk een reeks requests en responses van het type dat je hier ziet. De loop (B3) is een lus om dit ene request-type heen.
De stof in drie lagen
Kern ± 5 min
Het model draait op de server van de aanbieder; jouw code praat er via HTTP mee. Eén POST naar /v1/messages met een JSON-body: welk model, hoeveel max_tokens het maximaal mag schrijven, een optioneel system-prompt en de lijst messages. Terug komt één Message: een lijst content-blokken, een stop_reason en een usage-telling.
Het belangrijkste inzicht: de API is stateless. De server onthoudt niets tussen twee requests. Het geheugen van een gesprek is de messages-lijst die jij bijhoudt en bij elke beurt helemaal opnieuw meestuurt, inclusief het antwoord dat het model de vorige keer gaf. Dat verklaart waarom de input-kosten per beurt oplopen, en het is de brug naar twee latere modules: in B3 is de agent-loop letterlijk een lus die die lijst laat groeien, en in B4 wordt die groei een probleem dat je moet beheren.
Speel hieronder het gesprek in drie beurten af. Let op drie dingen: welke berichten nieuw zijn (blauw omlijnd), hoe de balk en input_tokens groeien, en dat het antwoord van beurt n in beurt n+1 als assistant-bericht terugkomt. Klik op een veld voor uitleg: wat het is, waarom het er is en welke valkuil erbij hoort. Onderaan zie je dezelfde Message als stroom events.
Samengevat: de API gedraagt zich als een pure functie lijst → nieuw bericht. Wil je dat het model iets weet, dan staat het in de lijst (of in system).
Verdieping mechanisme en bronnen
Rollen en afwisseling
De docs beschrijven dat de modellen getraind zijn op afwisselende user- en assistant-beurten. Je krijgt bij een afwijking niet altijd een fout: opeenvolgende berichten met dezelfde rol worden samengevoegd tot één beurt. Dat is bruikbaar, maar ook de reden dat een vergeten assistant-bericht onopgemerkt blijft.
Een lijst die met een assistant-bericht eindigt is “prefill”: het model zet de tekst voort. Op Claude 4.6 en later wordt dat niet meer ondersteund; een request met een geprefilld laatste assistant-bericht geeft een 400 invalid_request_error (“The conversation must end with a user message”). Structured outputs of instructies in het systeemprompt zijn de aanbevolen alternatieven.
The Messages API can be used for either single queries or stateless multi-turn conversations.
Content-blokken
content is een string (korte schrijfwijze voor één text-blok) of een lijst blokken met elk een type. Behalve text noemen de docs onder meer afbeeldingen, documenten, tool_use en tool_result. Een antwoord is dus een lijst: bij tool use staat er bijvoorbeeld tekst en een tool_use-blok in. De uitwerking volgt in B2. Bij thinking (zie A5) komen er thinking-blokken bij; die moet je ongewijzigd teruggeven, anders volgt een 400.
stop_reason
Dit veld vertelt waarom het model stopte: end_turn (klaar), max_tokens (jouw grens bereikt, tekst afgekapt), tool_use (het model wil dat jij een tool uitvoert) en andere. De agent-loop in B3 draait op dit ene veld.
Sampling-parameters bestaan niet meer
Voorbeelden in oudere tutorials sturen temperature, top_p of top_k mee. Op de huidige modellen geeft een niet-default waarde een 400, en met API-versie 2026-10-21 geeft elk request met een van die drie parameters een 400 op elk model. Je stuurt gedrag dus bij met prompting. De achtergrond staat in A4.
Streaming
Met "stream": true komt hetzelfde Message binnen als server-sent events: message_start, per content-blok content_block_start, een reeks content_block_deltas en content_block_stop, dan message_delta (hier staat stop_reason; de usage is cumulatief) en message_stop. Daar tussendoor kunnen ping-events komen. Jouw code plakt de deltas aan elkaar tot het uiteindelijke Message. De docs raden streaming aan voor langlopende requests; ook krijgt de gebruiker het eerste woord eerder te zien.
Let op twee dingen. De docs waarschuwen dat nieuwe eventtypes kunnen verschijnen, dus negeer onbekende types in plaats van te crashen. En een fout kan ook ná de 200 komen, als event: error in de stream.
Fouten en retries
Foutcodes die je in de praktijk tegenkomt: 400 (invalid_request_error: je request deugt niet, opnieuw proberen helpt niet), 429 (rate_limit_error), 500 (api_error) en 529 (overloaded_error, tijdelijke overbelasting). De officiële SDK probeert tijdelijke fouten (verbindingsfouten, rate limits, 5xx) standaard twee keer opnieuw met exponentiële backoff en volgt de retry-after-header als die er is. Een 400 retry je dus niet blind; een 429 of 529 wel, met wachttijd. Elke fout heeft een request_id; bewaar die voor support.
A 529 error can occur when the API experiences high traffic across all users.
De API-versie-header
Elk request heeft een anthropic-version-header nodig; de SDK zet hem voor je. Anthropic houdt binnen een versie bestaande parameters stabiel, maar mag optionele velden, uitvoerwaarden en eventtypes toevoegen. Daarom moet je code onbekende velden en eventtypes tolereren.
Anthropic recommends using the latest API version whenever possible.
Wat deze module niet uit een bron behandelt
Prompt caching (het hergebruiken van een onveranderd begin van de prompt tussen requests) valt buiten de bronnen van deze module; raadpleeg daarvoor de officiële docs. Ons eigen verband, dus geen bronuitspraak: omdat elke beurt dezelfde oude berichten opnieuw meestuurt, is het logisch dat een agent-bouwer wil weten of het onveranderde begin goedkoper kan. Ook image-input en andere blokvarianten zijn alleen genoemd, niet uitgewerkt.
Onder de motorkap curl, SDK, ruwe SSE
Let op: de voorbeelden met curl en de SDK hieronder zijn niet runnable zonder API-key (en kosten tokens). Ik heb ze daarom niet uitgevoerd; de vorm komt uit de officiële docs. De mock in de doe-opdracht draait wel zonder key.
Hetzelfde request met curl
curl (3e beurt van het gesprek)
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"system": "Je bent een beknopte assistent.",
"messages": [
{"role": "user", "content": "Hoi, ik ben Sam. Wat is een stateless API in één zin?"},
{"role": "assistant", "content": "Een stateless API onthoudt niets tussen requests: elk request bevat alles wat de server nodig heeft."},
{"role": "user", "content": "Hoe heet ik ook alweer?"}
]
}'
Python-SDK: je beheert de lijst zelf
chat_sdk.py (niet getest, vraagt ANTHROPIC_API_KEY)
import anthropic
client = anthropic.Anthropic() # leest ANTHROPIC_API_KEY; zet anthropic-version voor je
messages = []
def beurt(vraag):
messages.append({"role": "user", "content": vraag})
r = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
system="Je bent een beknopte assistent.",
messages=messages, # de HELE lijst, elke keer
)
messages.append({"role": "assistant", "content": r.content}) # response.content terug in de lijst
print(r.stop_reason, r.usage.input_tokens, r.usage.output_tokens)
De ruwe SSE-stream, geannoteerd
Uit de streaming-docs ("stream": true); de docs kortten zelf in. Let op de lege regel tussen events, de naam van het event op de eerste regel en JSON op de tweede.
response (text/event-stream)
event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}
event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}
event: ping
data: {"type": "ping"}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}
event: content_block_stop
data: {"type": "content_block_stop", "index": 0}
event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}
event: message_stop
data: {"type": "message_stop"}
- Het Message komt als eerste, met lege
contentenstop_reason: null.input_tokensis al bekend. - Blok 0 begint.
indexis de plek in de uiteindelijkecontent-lijst. - Een
pingmag overal voorkomen; negeer hem. - De
text_deltas plak je aan elkaar: “Hello” + “!” = “Hello!”. - Pas hier ligt de
stop_reasonvast; de usage is cumulatief, niet per delta.
Foutvorm
foutrespons (uit de docs)
{
"type": "error",
"error": {
"type": "not_found_error",
"message": "The requested resource could not be found."
},
"request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}
Uitgewerkt voorbeeld
Beurt 3 van het gesprek hierboven, als request. De tokengetallen zijn indicatief; de vorm is echt.
request.json (beurt 3)
{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"system": "Je bent een beknopte assistent.",
"messages": [
{ "role": "user", "content": "Hoi, ik ben Sam. Wat is een stateless API in één zin?" },
{ "role": "assistant", "content": [{ "type": "text", "text": "Een stateless API onthoudt niets ..." }] },
{ "role": "user", "content": "En wat betekent dat voor jou?" },
{ "role": "assistant", "content": [{ "type": "text", "text": "Dat ik alleen weet wat in de messages-lijst staat ..." }] },
{ "role": "user", "content": "Hoe heet ik ook alweer?" }
]
}
- Het model is een parameter van elk request. Sampling-parameters ontbreken met opzet (A4).
- Bovengrens voor het antwoord; haalt het model die, dan is
stop_reasonmax_tokens. - Dit bericht is letterlijk
response.contentvan beurt 1. Jij zet het terug; de server deed het niet. - Het enige nieuwe in dit request, naast de vorige antwoorden. Het model kan “Sam” alleen noemen omdat de eerste regel er nog in staat.
response.json (beurt 3, ingekort)
{
"id": "msg_01Voorbeeld3",
"type": "message",
"role": "assistant",
"content": [{ "type": "text", "text": "Je zei dat je Sam heet." }],
"stop_reason": "end_turn",
"usage": { "input_tokens": 130, "output_tokens": 17 }
}
- Het model stopte omdat het klaar was. Bij
tool_usezou je (B3) een tool uitvoeren en weer een request sturen. - Indicatief: 36 in beurt 1, 81 in beurt 2, 130 in beurt 3. Elke beurt betaal je opnieuw voor wat al in de lijst stond.
Beheer zelf je messages-lijst
Opdracht
Je hebt hier geen API-key voor nodig: je werkt tegen een mock met dezelfde vorm als de API. Met een key kun je daarna dezelfde loop tegen de echte SDK draaien (zie de motorkap-sectie).
- Maak een map met
fake_api.py(hieronder) en schrijf zelfchat.py: een functiebeurt(vraag)die het user-bericht aan een lijst toevoegt,fake_api.create(...)aanroept, het antwoord als assistant-bericht aan de lijst toevoegt en print: aantal berichten,input_tokensen de tekst. - Doe drie beurten:
"Hoi, ik ben Sam.","Noteer dat.","Hoe heet ik ook alweer?". - Maak de lijst leeg (
messages.clear()) en stel de naamvraag opnieuw. Wat verandert? - Saboteer: laat één keer het assistant-bericht weg, en laat de lijst één keer op een assistant-bericht eindigen. Welke fout zie je, en welke niet?
Starterbestand fake_api.py
import re
def create(*, model, max_tokens, messages, system=None):
# Zoals in de docs: opeenvolgende berichten met dezelfde rol worden samengevoegd.
merged = []
for m in messages:
if merged and merged[-1]["role"] == m["role"]:
merged[-1] = {"role": m["role"], "content": merged[-1]["content"] + "\n" + m["content"]}
else:
merged.append(dict(m))
if not merged or merged[-1]["role"] != "user":
raise ValueError("400 invalid_request_error: de conversatie moet op een user-bericht eindigen")
tekst = " ".join(m["content"] for m in merged) # het "model" kent alleen wat in de lijst staat
naam = re.findall(r"ik ben (\w+)", tekst, flags=re.I)
vraag = merged[-1]["content"].lower()
if "hoe heet ik" in vraag:
antwoord = f"Je zei dat je {naam[-1]} heet." if naam else "Dat weet ik niet: dat staat niet in dit gesprek."
else:
antwoord = "Genoteerd."
return {
"id": "msg_nep", "type": "message", "role": "assistant",
"content": [{"type": "text", "text": antwoord}],
"stop_reason": "end_turn",
"usage": {"input_tokens": len(tekst.split()), "output_tokens": len(antwoord.split())},
}
Verwacht resultaat
2 berichten, input_tokens= 4 | Genoteerd.
4 berichten, input_tokens= 7 | Genoteerd.
6 berichten, input_tokens=13 | Je zei dat je Sam heet.
2 berichten, input_tokens= 5 | Dat weet ik niet: dat staat niet in dit gesprek.
Het aantal berichten en input_tokens lopen op (de mock telt woorden, een echte API telt tokens); na clear() is de naam weg. Laat je het assistant-bericht weg, dan krijg je geen fout: de twee user-berichten worden samengevoegd, en het model mist zijn eigen antwoord. Een lijst die op assistant eindigt geeft in de mock een ValueError, naar het voorbeeld van de 400 die Claude 4.6 en later geeft bij prefill.
Als het niet werkt, kijk naar …
- Het model weet de naam niet in beurt 3: je stuurt een verse lijst per beurt, of je voegt het antwoord niet toe. Maak
messageseen variabele buiten de functie. input_tokensblijft gelijk: je overschrijft de lijst in plaats van eraan toe te voegen.- Twee berichten met dezelfde rol achter elkaar: dan voeg je het antwoord niet toe, of je voegt het twee keer toe. Print de rollen om te controleren.
- Met de echte SDK:
contentterugzetten:r.contentis een lijst blokken; die kun je zo alscontentvan het assistant-bericht gebruiken. - Met de echte SDK: 400: lees
error.message. Stuur jetemperaturemee, haal die weg (A4).