Context Engineering voor AI Agents: Memory en Tools

Viacheslav Dubrov

2025-10-05 · Bijgewerkt 2026-08-16 · 14 min · AI-agenten

Automatische vertaling Dit artikel is automatisch vertaald vanuit de oorspronkelijke Engelse versie.

Context engineering is de pipeline die vóór elke beslissing selecteert wat een model ziet: instructies, voorbeelden, kennis, memory, tooldefinities, observaties en guardrails. Een agent handelt niet op basis van alles wat het systeem weet. Hij handelt op basis van de working set die voor de volgende model call is samengesteld.

Veel failures beginnen bij die selectie. Een verouderde voorkeur lijkt actueel. Retrieved text bevat een instructie. Een lang tool result verbergt de mislukte precondition. Een samenvatting onthoudt de beslissing, maar verliest welk bestand is gewijzigd.

Voor engineers die AI agents, retrievalsystemen en applicaties met tool use bouwen of beheren, is de praktische taak het samenstellen van de kleinste toereikende working set voor elke agentbeslissing, met behoud van scope, provenance en permissies. Dit artikel laat zien hoe je een contextpipeline per beslissing ontwerpt, waar de trust boundaries liggen, hoe je test of de working set de taak ondersteunt en hoe je failures inspecteerbaar maakt, in plaats van een model de schuld te geven dat alleen de samengestelde input ziet.

TL;DR. Behandel context als een typed runtime-artifact dat provenance meedraagt. Selecteer context per step, dwing tenant- en permissionscope af vóór retrieval en houd trusted instructions gescheiden van untrusted data. Budgetteer op basis van utility, valideer actions buiten het model en evalueer task outcomes in plaats van alleen de contextlengte.

Context is een decision input, geen memory

Het context window is de huidige input van het model plus de gegenereerde tokens. Het kan conversation turns bevatten, maar is geen durable memory-systeem. Long-term memory, documentindexes, databases en artifact stores bevinden zich buiten het window. Een contextpipeline bepaalt wat daarin wordt gekopieerd.

De windowgrootte is een capaciteitslimiet, geen kwaliteitsgarantie. Lost in the Middle en RULER laten zien dat retrieval en reasoning kunnen variëren met positie, task, model en sequence length. De operationele les is niet dat middle tokens altijd worden genegeerd. Het is dat extra tokens die relevant lijken de task performance alsnog kunnen verlagen.

Het diagram toont het kwalitatieve resultaat van de studie, geen universele attention curve. Liu et al. testten multi-document question answering en key-value retrieval. Ze zagen vaak betere performance wanneer het relevante item aan het begin of einde stond. De omvang en vorm van het effect verschilden per model, task en context length. Test positie als variabele in je eigen evaluation set in plaats van uit te gaan van een vaste middle penalty.

Het volgende is een illustratief Pydantic-schema, geen geteste repositoryimplementatie. Het valideert alleen field types en literal values. Het autoriseert de tenant niet, houdt total_input_tokens consistent met items, persist de manifest niet en dwingt modelgedrag niet af.

from datetime import datetime
from typing import Literal

from pydantic import BaseModel

class ContextItem(BaseModel):
    item_id: str
    kind: Literal["instruction", "task_state", "evidence", "memory", "tool"]
    source: str
    trust: Literal["trusted", "untrusted"]
    retrieved_at: datetime | None = None
    version: str | None = None
    token_count: int

class ContextManifest(BaseModel):
    request_id: str
    tenant_id: str
    items: list[ContextItem]
    total_input_tokens: int

De manifest maakt een failure reproduceerbaar. “Het model hallucineerde” wordt een testbare vraag: welke evidence, version, permissionscope en tool schema heeft het daadwerkelijk ontvangen?

De assembly lifecycle

Een betrouwbare pipeline voert deze operaties in deze volgorde uit:

1. Resolve trusted request context. Authenticeer de actor, tenant, locale, tijd en huidige task state buiten het model.
2. Choose the next decision. Een planning step, evidence lookup, toolselectie en final response hebben verschillende context nodig.
3. Retrieve within scope. Pas authorization- en tenantfilters toe vóór semantic ranking, niet nadat documenten de candidate set zijn binnengekomen.
4. Rank and budget. Selecteer items op utility, freshness, authority en diversity binnen een input budget.
5. Assemble with trust boundaries. Houd policy in instruction channels en citeer retrieved content als data. Retrieved instructions worden geen system policy.
6. Generate a typed proposal. Constrained output kan ondersteunde syntax en vorm afdwingen. Het maakt waarden niet correct.
7. Validate and execute. Application code controleert authorization, business rules, tool arguments en postconditions.
8. Record provenance and outcome. Sla de manifest, geselecteerde source IDs, referenties naar tool results, het validation result en de task outcome op.

De lifecycle geldt per decision. Eén grote context hergebruiken voor een volledige agent run creëert stale evidence en geeft elke step toegang tot materiaal dat niet nodig is.

Geef elke contextbron één taak

Instructions definiëren duurzaam gedrag

Instructions beschrijven role, policy, output contract en escalation behavior. Houd stabiele content stabiel om prefix caching te verbeteren, maar zet waarden die tijdens runtime veranderen niet vast. Een refund threshold hoort in een policy service of versioned data record te staan, niet permanent in een prompt te worden gekopieerd.

Instruction hierarchy is een control boundary, geen security sandbox. Een model kan malicious text in een retrieved document nog steeds volgen. Delimiteer untrusted content, geef aan dat het om evidence en niet om instruction gaat, beperk tools onafhankelijk en test prompt-injectioncases.

Kopieer de role names van één provider niet naar een universele hiërarchie. De OpenAI Model Spec definieert authority levels voor platform- of system-, developer- en user-instructions. De Anthropic Messages API gebruikt een parameter op topniveau, system, en de messages user en assistant. Deze API biedt geen equivalente developer-role. Andere runtimes maken andere keuzes. Map je policy naar de gedocumenteerde channels van de provider en dwing permissies en side effects vervolgens af in application code.

Task state legt commitments vast

Conversation prose is een slechte source of truth voor multi-step work. Houd expliciete state bij voor objective, current phase, completed actions, pending approvals, artifact references en test status. Het model mag die state samenvatten voor narration. Application code beheert de canonical version.

Examples demonstreren edge decisions

Few-shot examples zijn nuttig wanneer ze een moeilijke boundary verduidelijken, niet wanneer ze alleen het schema herhalen. Selecteer voorbeelden die bij de huidige decision passen en consequential edge cases bevatten. Evalueer example retrieval zoals document retrieval: een oppervlakkig vergelijkbaar maar policy-incompatibel voorbeeld kan slechter zijn dan geen voorbeeld.

Knowledge levert evidence

Retrieval is geschikt voor actuele, private of citeerbare feiten. Er bestaat geen universele beste top_k, chunk size, hybrid weight of reranker cutoff. Tune de volledige path aan de hand van vragen met bekende supporting evidence.

Een nuttig evidence item bevat:

• source en stabiele document identifier
• version of effective date
• permissionscope
• quoted span en locatie
• retrieval- en rerankingscores voor debugging

Vraag het model niet om een URL te citeren die het niet heeft ontvangen. Log geen volledige private documenten alleen om selection te debuggen.

Memory levert scoped continuity

Memory is retrieved data met extra lifecycle risk. Houd als designmetadata subject, provenance, purpose, toepasselijke consent- of legal-basisbeslissing, creation time, expiry- of review policy en deletion path bij. Toepasselijke privacywetgeving en product counsel bepalen de legal basis voor een product en zijn data, niet deze checklist.

Vaste regels zoals “preferences worden 365 dagen bewaard” zijn geen portable policy. Retention volgt uit productbehoefte, user expectation en wetgeving. Controleer vóór het laden van memory:

1. Is deze bedoeld voor deze geauthenticeerde subject en tenant?
2. Is het purpose relevant voor deze decision?
3. Is de memory voldoende actueel?
4. Is de source authoritative of slechts door het model afgeleid?

Behandel inferred memories als hypotheses. Maak niet stilzwijgend van één model response een permanent user fact.

Tool contracts maken capabilities zichtbaar

Tool descriptions moeten preconditions, effects, authorization scope, input schema, output schema, idempotency en betekenisvolle failures beschrijven. Een schema-valid call kan nog steeds unauthorized of unsafe zijn.

Vervang na execution verbose raw output door een typed observation die het voor de decision relevante result en een reference naar het volledige artifact behoudt:

{
    "tool": "check_api_key_status",
    "status": "revoked",
    "checked_at": "2026-07-15T09:30:00Z",
    "account_id": "A-123",
    "artifact_ref": "toolrun://req-42/step-3"
}

De MCP specification standaardiseert hoe clients met tools, resources en prompts communiceren. De specification autoriseert het gebruik ervan niet en maakt returned content niet trustworthy. Houd gateway-, credential- en policychecks buiten het model en de protocoldescription.

Laad detail wanneer een decision dit nodig heeft

Progressive disclosure is een context-assembly pattern: houd identifiers en trusted task state beschikbaar en haal detail op voor de huidige decision. Het is geen belofte dat een specifieke token budget voor elk model werkt.

De router moet authorization en tenant scope toepassen vóór retrieval. Hij moet evidence spans, memory records en tool schemas retourneren die de huidige decision ondersteunen. Het model stelt vervolgens een action voor. Application code valideert die proposal vóór execution. Anthropic’s tool-context guidance gebruikt hetzelfde selectieve principe voor grote toolsets. Tool search houdt definitions buiten het context window totdat het model erom vraagt. Meet of de extra routing step in jouw systeem task success, latency en tokens per succesvolle task verbetert.

Hoe context degradeert

Slechte context faalt niet op slechts één manier. Het volgende five-pattern degradation model is mijn synthese voor debugging, gebaseerd op de bovenstaande long-context evaluations en onderzoek naar prompt injection:

• Position loss: de vereiste evidence is aanwezig, maar het model gebruikt die inconsistent vanwege de positie en de omringende sequence. Long-context evaluations laten zien dat het effect per model en task varieert. Er bestaat geen universeel “bad middle”-bereik.
• Poisoning: een incorrecte memory, stale document, malicious instruction of bad tool observation komt in de working set terecht en beïnvloedt latere decisions.
• Distraction: relevante evidence concurreert met materiaal dat recent of semantisch vergelijkbaar maar onnodig voor de huidige step is.
• Confusion: overlappende instructions, examples of tool descriptions laten het model achter met meerdere plausibele interpretaties van de task.
• Clash: twee authoritative-looking items spreken elkaar tegen over een waarde, policy of volgende action, en de assembler toont hun versions of precedence niet.

Deze failures vereisen verschillende oplossingen. Betere ranking kan distraction helpen, maar repareert geen stale source. Delimiters kunnen data van instructions helpen scheiden, maar kunnen een tool niet autoriseren. Een groter context window kan meer conflicterend materiaal behouden zonder het conflict op te lossen.

Inspecteer bij een mislukte run de manifest en bepaal eerst welk pattern is opgetreden voordat je de prompt wijzigt of een extra retrieval stage toevoegt.

Budgetteer op utility, niet met componentquota

Een context budget reserveert ruimte voor output en wijst vervolgens input toe aan de huidige decision. Begin met het door het model ondersteunde window, trek de maximale output en protocol overhead af en pack candidates in de resterende ruimte.

Score candidates met features die je evaluations kunnen uitdagen:

utility = relevance × authority × freshness × scope_match
          − redundancy_penalty − injection_risk

Gebruik de formule als design prompt. In een policy answer kan authority zwaarder wegen dan semantic similarity. Bij debugging kan een recent failing log hoger worden gerankt dan algemene documentatie.

Ook de volgorde is belangrijk. Houd stabiele trusted instructions vooraan wanneer de cache semantics van de provider baat hebben bij een gedeelde prefix. Plaats de huidige task en decision dicht bij de evidence waarnaar ze verwijzen. Zet timestamps of request IDs niet in stabiele prefixes wanneer ze daar niet nodig zijn.

Comprimeer zonder state te verliezen

Compression is lossy tenzij het origineel addressable blijft. Factory Research’s evaluation van drie compression approaches over long-running agent sessions formuleert het doel als tokens per task, niet tokens per request. Ik vertaal dat naar de volgende engineering recommendation: optimaliseer tokens per succesvolle task, niet tokens per request, onder vergelijkbare task conditions — niet als universele wet. Factory Research evaluation

Gebruik afzonderlijke mechanisms voor afzonderlijk materiaal:

• Conversation: vat decisions, unresolved questions en commitments samen.
• Tool observations: behoud typed findings en artifact references. Verwijder boilerplate en herhaalde payloads.
• Retrieved evidence: behoud source IDs, supporting spans en effective dates zodat het systeem opnieuw kan fetchen.
• Task state: sla deze canonical buiten de summary op.
• File- of artifact trail: houd een expliciete index bij van reads, writes, hashes en test results.

Trigger compaction op basis van gemeten degradation of een budget threshold die voor het model en de task is gekozen. Publiceer geen algemene regel zoals “compress at 70%” alsof alle models op hetzelfde punt falen.

Evalueer compression met probes die continuation vereisen, niet met lexical overlap:

• Wat is de huidige objective en next action?
• Welke files of records zijn gewijzigd?
• Welke decision is afgewezen en waarom?
• Welke source ondersteunt de huidige claim?
• Welke approval staat nog open?

Voer dezelfde task uit met en zonder compression. Vergelijk success, incorrect actions, re-fetches, latency en total tokens.

Optimaliseer de context path

Optimization moet het decision contract behouden. Vier techniques zijn nuttig zodra je een gemeten bottleneck hebt:

Deze techniques lossen verschillende problemen op. Compaction en context editing kunnen de content die naar het model wordt gestuurd verminderen. Selective tool loading voorkomt dat ongebruikte schemas worden meegestuurd. Prompt caching kan de kosten van herhaalde prefixes verlagen, maar vermindert niet het aantal tokens in het context window. Partitioning verandert welke capabilities en evidence elke decision ontvangt. De Anthropic tool-context guide maakt deze verschillen expliciet en de context-editing documentation biedt configureerbare triggers in plaats van een universele threshold.

Compact completed history

Vervang oude conversation turns door een structured handoff waarin decisions, unresolved questions, gewijzigde artifacts en test state worden vastgelegd. Houd het oorspronkelijke transcript of de artifacts addressable wanneer review of recovery dat vereist.

Mask verbose observations

Een tool kan pagina’s met logs retourneren terwijl de volgende step alleen een status, error code en artifact reference nodig heeft. Zet het raw result na validation om in een typed observation en houd de volledige payload buiten de prompt. Laat het model niet de enige evidence van een failure weg-samenvatten.

Behoud cacheable prefixes

Providers en runtimes kunnen werk hergebruiken wanneer het begin van een request stabiel blijft. Houd durable instructions en tool schemas in een consistente volgorde en verplaats timestamps, request IDs, retrieved evidence en current state naar de dynamic suffix. Controleer de cache semantics van de provider voordat je je ontwerp daarop baseert.

Partition by decision

Een planner, retriever, tool caller en final-answer step hebben niet hetzelfde materiaal nodig. Geef elke step de minimale trusted instructions, state, evidence en tools die nodig zijn. Partitioning vermindert tegelijk token use en capability exposure, maar alleen evaluations op taskniveau kunnen aantonen of noodzakelijke informatie is verwijderd.

Beveilig de context supply chain

Onderzoek naar prompt injection behandelt untrusted external content als een attack surface (paper). In het operationele model van dit artikel kan context poisoning binnenkomen via documenten, memories, tool results, skills of eerdere assistant messages. Tekst markeren als “untrusted” helpt het model, maar enforcement moet architectural zijn.

De volgende supply-chainchecklist is mijn engineering recommendation. Deze vertaalt protocol- en threat-model boundaries naar application controls. Noch de MCP specification, noch het prompt-injectionpaper dwingt deze volledige checklist af.

Gebruik deze boundaries:

1. Autoriseer vóór retrieval en tool execution.
2. Scheid data van instruction channels en delimiteer external text.
3. Allowlist tools per step en actor. Gebruik standaard geen side-effect capability.
4. Valideer resource identifiers in plaats van het model tenant keys of file paths te laten verzinnen.
5. Vereis confirmation voor high-impact operations op basis van policy, niet van model confidence.
6. Scan en review executable skills of connectors vóór installatie.
7. Voorkom dat secrets en raw sensitive context in logs en long-term memory terechtkomen.

Automatische “repair” is alleen geschikt voor wijzigingen die de betekenis behouden, zoals het parsen van een bekend date format. Ontbrekende tool arguments invullen met “sensible defaults” kan de operation veranderen. Vraag om clarification of reject wanneer de betekenis onzeker is.

Uitgewerkt voorbeeld: een supportrequest over een API-key

Voor “Why is my API key not working?” is de volgende decision het verzamelen van diagnostic evidence, niet het genereren van een final answer. De assembler kan het volgende opnemen:

• trusted support policy en response contract
• authenticated account ID en plan uit application state
• de current ticket objective en reeds uitgevoerde actions
• twee actuele runbook spans, geselecteerd binnen de product/version scope
• een scoped memory dat de key drie dagen geleden is aangemaakt, inclusief provenance
• check_api_key_status en search_incidents, maar geen tools voor key deletion of rotation

Het model stelt een read-only status check voor. Application code autoriseert het account, roept de tool aan en legt een typed observation vast. Een tweede model call ontvangt de relevante runbook spans plus die observation. De final response citeert de runbookversion, print de key nooit uit en biedt rotation alleen aan als afzonderlijk geautoriseerde action.

Let op wat buiten de context blijft: irrelevante ticket history, elk support example, raw account dumps, mutation tools en memories van andere tenants.

Anti-patterns die je expliciet moet testen

• Stuff the window: alle retrieved documents, history, memories en tools laden omdat er nog capaciteit beschikbaar is.
• RAG everywhere: semantic retrieval gebruiken voor waarden die in een database, policy service of authenticated application state thuishoren.
• Unbounded memory: inferred facts bewaren zonder scope, expiry, correction- of deletion semantics.
• One call for every stage: één prompt vragen om te retrieven, redeneren, autoriseren, muteren en uitleggen zonder observable boundaries.
• Schema equals correctness: valid JSON behandelen als bewijs dat waarden, permissies of business decisions geldig zijn.
• No component evaluations: alleen de final prose beoordelen en retrieval-, contextselectie- of tool failures missen.

Maak van elk anti-pattern een counterexample in de evaluation set. Een guideline die nooit door een task of trace wordt uitgeoefend, is eenvoudig te overtreden zonder dat iemand het merkt.

Evalueer de assembler, niet alleen het antwoord

Maak een vaste task set met evidence labels, permission boundaries, vereiste tool calls en verboden actions. Meet voor elke wijziging aan de context policy:

Gebruik ablations om causale waarde te vinden: verwijder memory, reranking, examples of compression één voor één. Een component die tokens toevoegt zonder de relevante slice te verbeteren, moet niet standaard worden geladen.

Conclusie

Goede context engineering is selectief en accountable. Vul geen groot window omdat er capaciteit beschikbaar is. Bouw een step-specifieke working set op uit trusted instructions, canonical task state, scoped evidence, reviewed memory en permitted tools.

De loop is kort: assemble, manifest, propose, validate, execute en evaluate. Wanneer een decision faalt, laat die loop zien of het ontbrekende onderdeel evidence, freshness, authority, state of policy was. Hij geeft je ook een test voor de volgende wijziging.

Referenties

• Lost in the Middle — position-dependent gebruik van long context
• RULER — multi-task evaluation van effectieve context length
• OpenAI Model Spec — provider-specifieke authority levels voor instructions
• Anthropic Messages API — system parameter en message-role structure
• Manage tool context — selective tool loading, caching en context editing
• Anthropic context editing — configureerbaar wissen van tool results en compaction
• Model Context Protocol specification — protocolconcepten en de huidige specification
• Evaluating Context Compression for AI Agents — tokens-per-task framing en probe-based evaluation
• Formalizing and Benchmarking Prompt Injection Attacks and Defenses — threat taxonomy en defenses