Deel B · Module 03

De agentic loop

Wat maakt een LLM een agent?

Zone: machine ± 15 min kern

Leerdoelen

Na deze module kun je:

  • voorspellen wat er gebeurt als de harness een tool_result niet (of met het verkeerde tool_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_result toevoegen, 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 alles end_turn is.

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)
  1. De hele lijst gaat mee bij elke call. De API onthoudt niets; dit is het geheugen van de agent.
  2. De lus-voorwaarde. Het model bepaalt via stop_reason wanneer hij ophoudt; jouw code leest dat alleen.
  3. Het assistant-bericht (inclusief de tool_use-blokken) moet in de lijst, vóór het resultaat. Zonder dit mist het resultaat zijn aanroep.
  4. Hier gebeurt het echte werk, in jouw code. Hier horen permissies, logging en een eventuele PreToolUse-check.
  5. Het id koppelt resultaat aan aanroep. Bij parallelle calls is dit de enige koppeling.
  6. Alle resultaten van deze turn in één user-bericht.
  7. Pas na de lus: de eindtekst. In een echte loop controleer je ook max_tokens en andere stop-redenen.

Edge cases

  • Fouten in een tool stuur je als tool_result met "is_error": true terug; 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 ontvangt hook_event_name, tool_name en tool_input als 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 ..." } ] }
  ]
}
  1. stop_reason: tool_use betekent “niet klaar, voer uit en kom terug”. Bij end_turn was dit de laatste response.
  2. Het model verzint dit id. De harness moet het letterlijk teruggeven.
  3. Het volledige assistant-bericht van turn 1 staat in turn 2, letterlijk. Het request is dus groter dan het vorige.
  4. Dezelfde waarde als bij markering 2. Zo weet het model welke aanroep dit resultaat beantwoordt.
  5. De uitvoer komt uit jouw code (het gelezen bestand), niet uit het model. Het model ziet het pas nu, als tekst in zijn context.
Doe-opdracht

Schrijf je eigen minimale loop

Opdracht

  1. Kies een taal (Python of TypeScript) en de officiële Anthropic SDK. Zet een API-key in je omgeving.
  2. Definieer één tool, read_file, met een input_schema met een path-string. Implementeer hem als gewone functie.
  3. Schrijf de loop uit de motorkap-sectie opnieuw, zonder te kopiëren: stuur messages, check stop_reason, voer de tool uit, stuur tool_result terug.
  4. Geef de agent de opdracht: “Lees README.md en vertel in één zin waar het project over gaat.” Print per turn de stop_reason.
  5. 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_use zonder tool_result: je hebt het tool_use_id vergeten of verkeerd overgenomen. Neem block.id letterlijk over.
  • Het model vraagt steeds hetzelfde bestand op: je hebt het assistant-bericht niet aan messages toegevoegd, of het resultaat niet teruggestuurd. Het model ziet dan zijn eigen aanroep niet terug.
  • De lus stopt direct: je controleert op end_turn in plaats van op tool_use, of je leest stop_reason van 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_result hoort in een bericht met role: user, niet assistant.

Zelftoets