Agent Events uitgelegd: Het Runtime Contract achter betrouwbare AI Agents

Het definitieve antwoord van een agent vertelt wat de gebruiker zag. De events vertellen uw applicatie wat er is gebeurd, wat er nog gebeurt, waarvoor een mens nodig is en hoe te herstellen wanneer de verbinding wegvalt.

1. Waarom een final-answer API te beperkt is voor agents

Een conventionele modelaanroep heeft een geruststellende vorm: stuur invoer, ontvang uitvoer. Zelfs als de respons streamt, reconstrueert de applicatie meestal één antwoord. De uitvoering van een agent is anders. Een run kan meerdere modelaanroepen doen, tools opvragen, wachten op goedkeuring, authenticeer op een MCP-server, een sandbox aanmaken, delegeer aan subagents en later in een verzoek hervatten.

Als de runtime alleen de laatste tekstrespons weergeeft, verliest de applicatie de structuur die nodig is om die workflow te beheren. Het kan basisvragen niet betrouwbaar beantwoorden:

• Is de agent aan het nadenken, roept hij een tool aan, wacht hij op een mens of is hij klaar?
• Welk modelbericht stelde deze tool-aanroep voor?
• Welke events behoren tot een subagent in plaats van de root agent?
• Welke fragmenten zijn al gerenderd?
• Moet de client na een onderbreking opnieuw verbinden met de live run of herbouwen vanuit de gepersisteerde status?

Dit is waarom events belangrijk zijn. Ze vormen de interface tussen de verborgen uitvoering en alles wat daarop moet reageren: de gebruikersinterface, goedkeuringsdienst, operationele console, debugger en evaluator.

2. Wat "event" betekent in TrueForge

TrueForge structureert de uitvoering als Agent → Session → Turn → Event → Delta. Elk niveau beantwoordt een andere vraag:

De agent is een definitie, geen continu draaiend proces. Een session behoudt de context over turns heen. Een turn vertegenwoordigt één verzoekcyclus, en er draait slechts één turn tegelijk binnen een session. Events zijn de getypeerde records die binnen die turn worden gegenereerd. Sommige events—vooral modelberichten—kunnen incrementeel worden opgebouwd via deltas.

Deze hiërarchie voorkomt twee veelvoorkomende ontwerpfouten. Ten eerste moet de session-geschiedenis niet worden behandeld als één onbegrensd transcript: turns bieden natuurlijke uitvoeringsgrenzen. Ten tweede moet een gestreamde delta niet worden opgeslagen of geëvalueerd alsof het het definitieve semantische event is.

3. De eventtaxonomie is de runtime-statemachine

TrueForge's gedocumenteerde event-union omvat verschillende categorieën. Het gaat niet om het aantal eventtypen; het gaat erom dat elke categorie ander applicatiegedrag vereist.

Een nuttig detail ziet men snel over het hoofd: huidige TrueForge-events gebruiken geen tool.call event op het hoogste niveau. Gevraagde aanroepen bevinden zich in model.message.toolCalls; de latere tool.response verwijst terug naar de call ID. Dat onderscheid is van belang voor reducers en audit-weergaven. Een verwerker die is ontworpen rond een niet-bestaand event op het hoogste niveau zou er niet in slagen de voorgestelde actie op het juiste moment te tonen.

De stream begint met turn.created en sluit af met exact één turn.done. Die laatste meldt een eindstatus van de turn van done, cancelled of error. Een nieuwe turn annuleert bovendien een eerdere turn die nog actief is binnen dezelfde session. Applicaties moeten daarom de runtime-lifecycle gebruiken in plaats van de afronding af te leiden uit stilte of het binnenkomen van tekst.

4. Vier identificatoren, vier verschillende taken

Event-verwerkers falen vaak omdat ze elke identificator reduceren tot "de event ID." TrueForge biedt afzonderlijke identificatoren voor volgorde, opbouw, concurrency en causaliteit.

Volgorde is geen identiteit. Een event kan meerdere gestreamde deltas ontvangen met dezelfde event ID terwijl elke envelope het sequence number verhoogt. Thread-lidmaatschap is geen causaliteit: twee events kunnen dezelfde subagent-thread delen zonder dat de ene de andere veroorzaakt. Causale referenties zorgen ervoor dat een goedkeuringsscherm met precisie kan aangeven: "dit modelbericht heeft deze tool-aanroep voorgesteld."

5. Deltas zijn transport; events zijn status

Wanneer tekst streamt, verzendt TrueForge eerst een basis-model.message, en vervolgens model.message.delta-fragmenten die dezelfde event ID delen. De UI kan die fragmenten direct renderen. Zodra het event is gepersisteerd, retourneert de history-API de samengevoegde model.message; deltas worden niet als afzonderlijke gepersisteerde records geretourneerd.

Dit is een goed contract omdat het twee zaken gescheiden houdt:

• Live transport: optimaliseer de tijd tot de eerste zichtbare uitvoer en behoud een geordende herverbindingspositie.
• Afgewikkelde status: bied één samenhangend bericht voor replay, inspectie en evaluatie.

Een reducer aan de clientzijde moet semantische events daarom indexeren op ID, deltas samenvoegen en het laatst verwerkte sequence number afzonderlijk bijhouden:

De exacte SDK-helpers en stream-envelopes variëren per integratievlak, dus productiecode moet de huidige TrueForge UI SDK event referentie volgen. De invariant is belangrijker dan de syntaxis: voeg niet elke delta toe als een nieuw chat-item en gebruik een semantische event ID niet als herverbindingscursor.

6. Een pauze is een expliciete statusovergang

Tool-goedkeuring, aanvullende gebruikersinvoer en MCP-authenticatie zijn geen uitzonderlijke fouten. Het zijn normale statussen in de workflow van een agent. TrueForge vertegenwoordigt deze als tool.approval_required-, tool.response_required- en mcp.auth_required-events.

De subtiliteit is dat de huidige turn kan eindigen met de status done terwijl requiredActions niet leeg is. De turn is terminaal; de workflow is gepauzeerd. Nadat de gebruiker goedkeuring geeft, afwijst, de gevraagde waarde levert of de authenticatie voltooit, maakt de applicatie een nieuwe turn aan binnen dezelfde session. Goedkeurings- en tool-input-reacties worden gerepresenteerd als getypte gebruikersinvoer; MCP-authenticatie wordt hervat met een nieuwe turn zodra credentials beschikbaar zijn.

Dit model heeft een praktisch voordeel: wachten vereist niet dat er voor onbepaalde tijd één netwerkverzoek open wordt gehouden. De session behoudt de continuïteit, terwijl elke turn een begrensde uitvoeringseenheid blijft.

Goedkeuring is geen autorisatie

Een goedkeuringsevent geeft aan dat de runtime een menselijke beslissing vereist voordat er verder kan worden gegaan. Het stelt niet vast dat de agent of de goedkeurende gebruiker de zakelijke bevoegdheid heeft om de actie uit te voeren. Een terugbetaling, database-mutatie, deployment of machtigingswijziging vereist nog steeds policy enforcement tegen het geautoriseerde domeinsysteem.

Goede implementaties maken de scope van de goedkeuring expliciet: tool name, argumenten, resource, verzoekende identiteit, vervaltijd en de status waartegen de goedkeuring is verleend. Als de materiële status verandert vóór de uitvoering, moet de applicatie mogelijk opnieuw autoriseren of reconciliëren voordat ze doorgaat.

7. Threads maken subagent-concurrency zichtbaar

Wanneer een agent werk delegeert, kunnen events van verschillende subagents door elkaar lopen in één turn-stream. De volgorde van binnenkomst alleen vertelt de UI niet welke worker welk bericht heeft geproduceerd. TrueForge gebruikt thread IDs om die structuur te behouden: de root-agent gebruikt main, subagents ontvangen gegenereerde IDs, en thread.created/thread.done markeren hun levenscyclus.

Een parent-referentie kan de parent-thread bevatten en de tool call die de subagent heeft aangemaakt. Daarmee kan een interface een geneste uitvoeringsboom renderen zonder een hiërarchie te hoeven bedenken uit de berichttekst. Het verbetert ook het debuggen. In plaats van één platte tijdlijn te zien, kan een engineer een research-subagent isoleren, de inputs vergelijken met de output, en bepalen of de fout optrad bij delegatie, toolgebruik of synthese.

Thread-groepering is niet alleen visuele afwerking. Bij parallel werk kunnen twee geldige event-sequences verschillend door elkaar lopen tussen uitvoeringen. Consumers moeten de volgorde binnen de turn behouden, terwijl de presentatie en analyse per thread worden gegroepeerd. Anders kan een correcte gelijktijdige uitvoering er oorzakelijk onsamenhangend uitzien.

8. Live opnieuw verbinden; replayen wanneer live status verdwenen is

Netwerken falen vaker dan langlopende agent-taken. Een productieclient moet drie waarden opslaan zodra ze beschikbaar zijn: session ID, turn ID en het laatste sequence number dat is verwerkt.

Bij opnieuw verbinden controleert de client de turn:

1. Als de turn nog steeds draait, abonneer dan na het laatste sequence number. De cursor is exclusief, dus de client hervat met de volgende envelope.
2. Als de turn is voltooid, herbouw de weergave dan vanuit opgeslagen turn-events.
3. Als de live stream niet langer beschikbaar is, kan de subscription-API 412 retourneren; val terug op opgeslagen events in plaats van dat te behandelen als verloren werk.

Het subscription contract en persisted event endpoint bedienen bewust verschillende statussen. Herverbinding zet een live transport voort; replay reconstrueert de vastgelegde semantische historie.

9. Wat events mogelijk maken

Een responsieve productervaring

Getypte levenscyclus- en delta-events stellen een UI in staat meer te tonen dan een typ-indicator. Het kan de actieve agent of subagent, een voorgestelde tool-actie, een controlepunt voor machtigingen, een overdracht van authenticatie en een terminale fout weergeven zonder proza te hoeven parsen.

Duurzame human-in-the-loop workflows

Events voor goedkeuring en vereiste reacties veranderen pauzes in hervatbare protocolstatussen. De applicatie kan de vereiste actie opslaan, de juiste reviewer op de hoogte stellen, later een beslissing verzamelen en doorgaan in dezelfde session.

Debuggen op het juiste niveau

Een definitief antwoord kan onjuist zijn vanwege een slechte modelreactie, een verkeerde tool-keuze, verouderde tool-data, een mislukte subagent of een mutatie aan de applicatiezijde. Event-structuur helpt de fout te lokaliseren. TrueForge model-message gebruiksgegevens kunnen ook input tokens uitsplitsen in harness, instructies, berichten, skills en tool-definities, wat teams helpt bij het diagnosticeren van context-groei en kosten in plaats van te gissen op basis van de uiteindelijke output.

Herstel en ondersteuning

Opgeslagen turn- en session-events stellen een operator in staat de actieve tak van een gesprek te reconstrueren. Dat ondersteunt pagina-verversingen, overdrachten, incidentbeoordeling en klantondersteuning zonder dat de oorspronkelijke browserverbinding vereist is.

Een evaluatiesubstraat

Trajectory-evaluators hebben meer nodig dan output-tekst. Ze kunnen vragen of de agent de juiste tool heeft gekozen, goedkeuring heeft gevraagd vóór een gevoelige actie, heeft gedelegeerd aan de juiste specialist, of is hersteld na een fout. Events bieden het gestructureerde bewijs waarop die evaluators kunnen werken.

Maar events zijn inputs voor evaluatie—niet de evaluatie zelf. Taaksucces, veiligheid en zakelijke impact vereisen nog steeds door de applicatie gedefinieerde criteria en vaak stroomafwaartse resultaatgegevens.

10. Waar TrueForge-events passen in de TrueFoundry-stack

TrueForge biedt het agent-runtime inzicht: sessions, turns, berichten, calls, pauzes, threads en statusovergangen. Productiebewijs wordt nuttiger wanneer het wordt gecorreleerd met de control planes rondom de runtime.

Het natuurlijke TrueFoundry-verhaal is niet dat één laag "observability oplost." Het is dat de lagen verschillende bewijslasten bewaren en verschillende grenzen afdwingen. Een TrueForge-event kan vastleggen dat een tool call werd voorgesteld en geretourneerd. MCP Gateway kan gerouteerde toegang tot die tool beheren. Het stroomafwaartse systeem kan bewijzen of het neveneffect is gecommitteerd. Een evaluator kan het gecombineerde traject en de uitkomst beoordelen.

11. Een terugbetaling uitvoeren, event voor event

Overweeg een support agent die "Refund order 4821" afhandelt. Het volgende is een conceptuele sequentie, geen belofte dat elke deployment identieke payloads zal uitsturen:

1. turn.created opent de verzoekcyclus.
2. Een model.message stelt get_order voor in de toolCalls.
3. tool.response retourneert de orderdetails en verwijst naar die call via toolCallId.
4. Een latere model.message stelt process_refund voor.
5. tool.approval_required wijst naar de voorgestelde actie en het bronbericht.
6. turn.done sluit deze turn met een vereiste actie. De workflow wacht en is nog niet voltooid.
7. De applicatie valideert de bevoegdheid van de beoordelaar en toont de exacte omvang van de terugbetaling.
8. Een nieuwe turn bevat de goedkeuringsrespons.
9. De tool-grens voert de terugbetaling uit met behulp van een operatie- of idempotentie-sleutel waar dit wordt ondersteund.
10. tool.response legt het geretourneerde resultaat vast; het betalingssysteem blijft gezaghebbend voor de vraag of de terugbetaling is gecommitteerd.
11. Een definitieve model.message streamt de bevestiging via deltas, en turn.done sluit de turn zonder vereiste acties.

Dit voorbeeld laat zien waarom de event-laag nuttig is en waarom deze niet op zichzelf kan staan. De event-stream verklaart het runtime-traject. Autorisatie stelt vast of de beoordelaar mag goedkeuren. Idempotentie en reconciliatie beschermen de mutatie. Het betalingssysteem bewijst het zakelijke resultaat.

12. Wat events niet garanderen

Deze beperkingen verzwakken het event-model niet. Ze maken de verantwoordelijkheid ervan helder. Een sterke productiearchitectuur wordt gebouwd op expliciete grenzen, niet door te vragen of één telemetrie-oppervlak elke betekenis kan dragen.

13. Een productie-checklist voor event-consumers

• Modelleer de UI-status op basis van event-typen, niet op basis van geparste statusberichten in natuurlijke taal.
• Sla de session ID, turn ID en het laatst verwerkte sequentienummer op.
• Dedupliceer en merge op basis van event ID; checkpoint op basis van sequentienummer.
• Bewaar threadId zodat parallelle subagent-events begrijpelijk blijven.
• Bewaar tool-call- en source-event-referenties voor goedkeuringen en debugging.
• Inspecteer requiredActions voordat u een workflow als voltooid markeert.
• Herstel de verbinding met actieve turns; herbouw voltooide turns op basis van gepersisteerde events.
• Verwacht dat live deltas uit de gepersisteerde geschiedenis verdwijnen nadat ze zijn gemerged.
• Correleer runtime-events met gateway-telemetrie en domeinresultaten.
• Pas retentie-, redactie- en toegangsbeleid toe op event-payloads die gevoelige gegevens kunnen bevatten.
• Versioneer reducers tegen de gedocumenteerde event union en verwerk onbekende event-typen op een veilige manier.

14. Het diepere punt: events veranderen agency in een interface

Agents worden operationeel interessant wanneer ze werk verrichten over tijd, tools, mensen en systemen heen. Dat is ook het moment waarop een enkele response niet langer een toereikend contract is.

TrueForge-events leggen de tussenliggende structuur bloot: model-messages, tool-resultaten, approval gates, authenticatiebehoeften, resourcecreatie, subagent-threads en de turn-lifecycle. Live deltas maken de ervaring responsief. Gepersisteerde events maken deze herstelbaar. Stabiele identiteiten en causale referenties maken het debugbaar. Samen geven ze product- en platformteams een gemeenschappelijk vocabulaire voor wat de runtime doet.

Het meest volwassen gebruik van dat vocabulaire is gedisciplineerd in plaats van maximalistisch. Laat TrueForge-events de runtime-uitvoering beschrijven. Laat AI Gateway en MCP Gateway de model- en toolgrenzen beheren. Laat systems of record de definitieve business-state vastleggen. Laat evaluators de samengevoegde bewijslast omzetten in oordelen.

Veelgestelde vragen

Zijn TrueForge-events hetzelfde als traces?

Nee. Ze kunnen worden gecorreleerd, maar ze dienen verschillende contracten. Events vertegenwoordigen applicatierelevante runtime-gebeurtenissen en statusovergangen. Traces organiseren operaties in spans en zijn vooral nuttig voor latency-, afhankelijkheids- en request-flow-analyses. Een productiesysteem profiteert van beide.

Worden deltas opgeslagen als individuele events?

Ze maken deel uit van de live stream. Gepersisteerde turn-event listings tonen het samengestelde model-message in plaats van de individuele deltas.

Kan ik een run hervatten nadat de verbinding met de browser is verbroken?

Ja. Controleer of de turn nog actief is. Als dat het geval is, abonneer je dan na het laatst verwerkte sequentienummer. Als deze is voltooid—of de live stream niet langer beschikbaar is—herbouw dan vanuit de gepersisteerde events.

Betekent een turn.done event dat de taak van de gebruiker is voltooid?

Niet noodzakelijkerwijs. De turn is beëindigd, maar kan vereiste acties bevatten zoals een tool-goedkeuring, gebruikersrespons of authenticatiestap. De workflow gaat verder via een nieuwe turn binnen dezelfde sessie.

Kunnen events bewijzen dat een externe actie is geslaagd?

Ze kunnen het verzoek en de door de runtime waargenomen response registreren. Voor ingrijpende mutaties dient u de vastgelegde status in het autoritatieve downstream-systeem te controleren en retries te ontwerpen rondom idempotentie of reconciliatie.

Referenties

1. TrueForge API-overzicht: agent, session, turn, event, en delta-hiërarchie
2. TrueForge-gids: sessies maken en turns streamen
3. TrueForge UI SDK: event union, deltas, en thread-groepering
4. TrueForge API: gepersisteerde turn-events weergeven
5. TrueForge API: events weergeven over de actieve sessie-branch
6. TrueForge API: abonneren op een actieve turn
7. TrueFoundry AI Gateway overzicht
8. TrueFoundry MCP Gateway overzicht
9. TrueFoundry Agent Registry overzicht
10. TrueFoundry Skills Registry en Agent Harness skills
11. OpenTelemetry generatieve AI semantische attributen
12. WHATWG Server-Sent Events specificatie

Redactionele verklaring: Productgedrag is beschreven op basis van openbare TrueForge- en TrueFoundry-documentatie beschikbaar op 3 september 2026. Voorbeelden dienen ter illustratie en moeten worden aangepast aan de autorisatie-, privacy-, betrouwbaarheids- en compliance-eisen van elke specifieke applicatie.

‍