Deel B · Module 03
De agentic loop
Wat maakt een LLM een agent?
Leerdoelen
Na deze module kun je:
- voorspellen wat er gebeurt als de harness een
tool_resultniet (of met het verkeerdetool_use_id) terugstuurt, en waarom de context per turn groeit; - aanwijzen wie in de loop beslist (model), wie uitvoert en handhaaft (harness) en wie goedkeurt (mens), en op welke momenten een hook kan ingrijpen;
- een minimale agent-loop schrijven met de Messages API en één tool.
Voorkennis-check
Twee vragen over eerdere modules. Fout? Lees die module eerst terug.
Waar zitten we?
Laag 3 van de stack: de lus die model en tools aan elkaar knoopt. Alles wat de lagen erboven toevoegen (skills, hooks, MCP, subagents) haakt aan op deze ene lus.
De stof in drie lagen
Kern ± 5 min
Een agent is een LLM, een set tools en een lus die doorgaat tot het model zegt dat het klaar is. Meer is het niet. De intelligentie zit in het model; de lus is gewone code.
Er zijn drie spelers, en de verdeling is het belangrijkste inzicht van deze module:
- Het model beslist. Het genereert tekst, en soms een verzoek om een tool aan te roepen. Het voert zelf niets uit.
- De harness voert uit en handhaaft. Dat is de code om het model heen: hij bouwt het request, draait de tool, controleert permissies en stuurt het resultaat terug.
- De mens keurt goed waar de harness dat vraagt, en geeft de opdracht.
Klik hieronder door een scenario. Let op drie dingen: welke knoop actief is, hoe de balk onderaan elke turn groeit, en waar de gestippelde hook-labels aan de lijnen hangen.
De lus in één zin: stuur de messages naar het model; zit er een tool_use in, voer die uit, voeg het resultaat toe en stuur opnieuw; zit er geen in, dan ben je klaar.
De hook-labels (UserPromptSubmit, PreToolUse, PostToolUse, Stop) zijn de haakjes waar jouw code in de lus kan ingrijpen zonder het model te vragen. Hoe dat werkt, is het onderwerp van module C2.
Verdieping mechanisme en bronnen
stop_reason bepaalt wat de harness doet
Elke response heeft een stop_reason. De harness leest die en kiest zijn volgende actie:
tool_use: het model wil een tool laten draaien. Uitvoeren,tool_resulttoevoegen, opnieuw sturen.end_turn: het model vindt zichzelf klaar. De lus stopt.max_tokens: de limiet voor de uitvoer is geraakt; het antwoord of de tool-aanroep kan zijn afgekapt. Dit is geen “klaar”, maar een situatie die je moet afhandelen.stop_sequence,refusal,pause_turn: minder vaak nodig, maar een robuuste loop heeft een standaard-tak voor onbekende waarden in plaats van aan te nemen dat allesend_turnis.
Parallelle tool calls
Eén assistant-bericht kan meerdere tool_use-blokken bevatten. De harness voert ze uit (eventueel gelijktijdig) en antwoordt in één user-bericht met een tool_result per tool_use_id. De volgorde van resultaten maakt niet uit; de koppeling via id wel.
Permissies: de harness is de poortwachter
Tussen “het model vraagt” en “de tool draait” zit een beslismoment: een regel (toegestaan/geweigerd), een vraag aan de mens, of een hook. Een geweigerde aanroep wordt een tool_result met een foutmelding, zodat het model kan bijsturen. Het model kan de poort niet omzeilen omdat het niets uitvoert.
Waarom state alleen in messages zit
De Messages API is stateless. Elk request moet daarom alles bevatten wat het model moet weten: system prompt, tool-definities en het hele gesprek. Er is geen sessie aan de serverkant en het model leert niet tijdens het gesprek. “Geheugen” is een lijst die jouw code bijhoudt en steeds opnieuw meestuurt.
Context-groei: de brug naar B4
Omdat die lijst alleen langer wordt, wordt elk request groter dan het vorige. Een grote tool_result (een heel bestand, een lange testrun) blijft voor de rest van de sessie in elk request zitten. Wat je daaraan doet (inkorten, samenvatten, compaction) is module B4.
Subagents: dezelfde loop, opnieuw gestart
Een subagent is geen ander soort ding. Het is een nieuwe instantie van dezelfde loop, met een eigen messages-lijst. Daardoor blijft het werk (en de bulk aan tool_results) buiten de context van de hoofdloop; alleen een samenvatting gaat terug.
Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.
Waar de loop haakjes heeft
De officiële docs beschrijven extensies als dingen die aangrijpen op verschillende plekken van dezelfde loop:
Extensions plug into different parts of the agentic loop:
Voor hooks betekent dat concreet: een instructie in een prompt is een verzoek aan het model, een hook is code in de harness.
An instruction like "never edit `.env`" in CLAUDE.md or a skill is a request, not a guarantee. A `PreToolUse` hook that blocks the edit is enforcement.
Onder de motorkap payloads, schema's, edge cases
Een complete agent-loop past in ongeveer 25 regels. Dit is Python-achtige pseudocode op de Messages API; foutafhandeling en streaming ontbreken met opzet.
agent.py (pseudocode)
client = Anthropic()
messages = [{"role": "user", "content": prompt}]
def ask():
return client.messages.create(
model="claude-sonnet-5-5", max_tokens=4096,
system=SYSTEM, tools=TOOLS,
messages=messages)
resp = ask()
while resp.stop_reason == "tool_use":
messages.append({"role": "assistant", "content": resp.content})
results = []
for block in resp.content:
if block.type == "tool_use":
out = run_tool(block.name, block.input)
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": out})
messages.append({"role": "user", "content": results})
resp = ask()
print(resp.content[0].text)
- De hele lijst gaat mee bij elke call. De API onthoudt niets; dit is het geheugen van de agent.
- De lus-voorwaarde. Het model bepaalt via
stop_reasonwanneer hij ophoudt; jouw code leest dat alleen. - Het assistant-bericht (inclusief de
tool_use-blokken) moet in de lijst, vóór het resultaat. Zonder dit mist het resultaat zijn aanroep. - Hier gebeurt het echte werk, in jouw code. Hier horen permissies, logging en een eventuele
PreToolUse-check. - Het id koppelt resultaat aan aanroep. Bij parallelle calls is dit de enige koppeling.
- Alle resultaten van deze turn in één user-bericht.
- Pas na de lus: de eindtekst. In een echte loop controleer je ook
max_tokensen andere stop-redenen.
Edge cases
- Fouten in een tool stuur je als
tool_resultmet"is_error": trueterug; het model kan dan zelf een andere aanpak kiezen. - Oneindige lus: niets dwingt het model te stoppen. Zet een maximum aantal turns of een budget in de harness.
- Hook-input: een
PreToolUse-hook ontvangthook_event_name,tool_nameentool_inputals JSON; de exit code (0, 2) bepaalt wat de harness doet. Details in C2.
Uitgewerkt voorbeeld: twee turns, echte payloads
Dezelfde taak als in de visual, ingekort tot de eerste twee API-calls. Eerst de response met een tool_use, dan het volgende request met het tool_result.
turn 1: response van de API
{
"id": "msg_01XyZ",
"role": "assistant",
"stop_reason": "tool_use",
"content": [
{ "type": "text", "text": "Ik lees eerst de test." },
{ "type": "tool_use",
"id": "toolu_01A",
"name": "Read",
"input": { "file_path": "tests/test_cart.py" } }
]
}
turn 2: request van de harness
{
"model": "claude-sonnet-5-5",
"max_tokens": 4096,
"system": "Je bent een coding agent ...",
"tools": [ ... ],
"messages": [
{ "role": "user", "content": "Fix de falende test in tests/test_cart.py" },
{ "role": "assistant", "content": [
{ "type": "text", "text": "Ik lees eerst de test." },
{ "type": "tool_use", "id": "toolu_01A", "name": "Read",
"input": { "file_path": "tests/test_cart.py" } } ] },
{ "role": "user", "content": [
{ "type": "tool_result",
"tool_use_id": "toolu_01A",
"content": "1 from cart import total ..." } ] }
]
}
stop_reason: tool_usebetekent “niet klaar, voer uit en kom terug”. Bijend_turnwas dit de laatste response.- Het model verzint dit id. De harness moet het letterlijk teruggeven.
- Het volledige assistant-bericht van turn 1 staat in turn 2, letterlijk. Het request is dus groter dan het vorige.
- Dezelfde waarde als bij markering 2. Zo weet het model welke aanroep dit resultaat beantwoordt.
- De uitvoer komt uit jouw code (het gelezen bestand), niet uit het model. Het model ziet het pas nu, als tekst in zijn context.
Schrijf je eigen minimale loop
Opdracht
- Kies een taal (Python of TypeScript) en de officiële Anthropic SDK. Zet een API-key in je omgeving.
- Definieer één tool,
read_file, met eeninput_schemamet eenpath-string. Implementeer hem als gewone functie. - Schrijf de loop uit de motorkap-sectie opnieuw, zonder te kopiëren: stuur
messages, checkstop_reason, voer de tool uit, stuurtool_resultterug. - Geef de agent de opdracht: “Lees README.md en vertel in één zin waar het project over gaat.” Print per turn de
stop_reason. - Breid uit: print bij elke turn het aantal berichten in
messages, en geef de agent een tweede bestand om te lezen. Wat verandert er?
Verwacht resultaat
Twee API-calls. Turn 1: stop_reason = tool_use met een read_file-aanroep, messages heeft 1 bericht. Je code leest het bestand. Turn 2: stop_reason = end_turn en een tekstantwoord; messages heeft dan 3 berichten (user, assistant, user met tool_result). Bij twee bestanden kan het model beide in één turn vragen (parallelle calls, twee tool_result-blokken in één user-bericht) of na elkaar.
Als het niet werkt, kijk naar …
- API-fout over
tool_usezondertool_result: je hebt hettool_use_idvergeten of verkeerd overgenomen. Neemblock.idletterlijk over. - Het model vraagt steeds hetzelfde bestand op: je hebt het assistant-bericht niet aan
messagestoegevoegd, of het resultaat niet teruggestuurd. Het model ziet dan zijn eigen aanroep niet terug. - De lus stopt direct: je controleert op
end_turnin plaats van optool_use, of je leeststop_reasonvan een oud response-object. - De lus stopt nooit: de tool geeft een fout terug en het model probeert het opnieuw. Voeg een maximum aantal turns toe.
- Content-type-fout: een
tool_resulthoort in een bericht metrole: user, nietassistant.