TrueForge Agent Events: The Runtime Contract | TrueFoundry
Meet TrueForge: The open-source, vendor-neutral agent harness. 50% lower cost. Explore Now→
Agent Events, Explained: The Runtime Contract Behind Reliable AI Agents
By Boyu Wang
Published: September 9, 2026
Built for Speed: ~10ms Latency, Even Under Load
Blazingly fast way to build, track and deploy your models!
- Handles 350+ RPS on just 1 vCPU — no tuning needed
- Production-ready with full enterprise support
An agent’s final answer tells you what the user saw. Its events tell your application what happened, what is still happening, what needs a human, and how to recover when the connection breaks.
Source note. This article describes the public TrueForge API and UI event contracts available on September 3, 2026. It separates documented behavior from architectural guidance. Event names and lifecycle semantics are grounded in the linked TrueForge documentation; the production patterns and control boundaries are TrueFoundry editorial analysis.
Key Takeaways
- An event is a typed runtime record, not merely a log line or a token fragment.
- TrueForge exposes lifecycle, model, tool, approval, authentication, sandbox, and subagent events through one stream.
- Live deltas and persisted events serve different jobs: responsive rendering versus settled recovery and analysis.
- A completed turn can still contain required actions. Turn completion and workflow completion are different states.
- Events provide evidence for debugging and evaluation, but do not by themselves guarantee authorization, exactly-once side effects, compliance, or business outcomes.
1. Why a final-answer API is too small for agents
A conventional model call has a reassuring shape: send input, receive output. Even when the response streams, the application is usually reconstructing one answer. Agent execution is different. A run can make several model calls, request tools, wait for approval, authenticate to an MCP server, create a sandbox, delegate to subagents, and resume in a later request.
If the runtime exposes only the last text response, the application loses the structure it needs to operate that workflow. It cannot reliably answer basic questions:
- Is the agent thinking, invoking a tool, waiting for a human, or finished?
- Which model message proposed this tool call?
- Which events belong to a subagent rather than the root agent?
- Which fragments have already been rendered?
- After a disconnect, should the client reconnect to the live run or rebuild from persisted state?
This is why events matter. They are the interface between hidden execution and everything that must respond to it: the user interface, approval service, operations console, debugger, and evaluator.
2. What “event” means in TrueForge
TrueForge organizes execution as Agent → Session → Turn → Event → Delta. Each level answers a different question:
| Level | Question it answers | Typical lifetime |
|---|---|---|
| Agent | Which reusable instructions, tools, model configuration, and runtime behavior define the worker? | Many user interactions |
| Session | Which ongoing issue or context does this work belong to? | Several turns |
| Turn | What happened in one request/response cycle? | One execution cycle |
| Event | What meaningful runtime occurrence happened? | One structured record in the stream or history |
| Delta | What incremental content arrived for an event that is still being assembled? | Live stream only |
The agent is a definition, not a continuously running process. A session persists context across turns. A turn represents one request cycle, and only one turn runs at a time within a session. Events are the typed records produced inside that turn. Some events—most visibly model messages—can be incrementally assembled through deltas.
Figure 1. An event sits inside a turn, which sits inside a durable session. The live view includes deltas and stream lifecycle markers; the persisted view returns settled events with message deltas already merged.
3. The event taxonomy is the runtime state machine
TrueForge’s documented event union covers several categories. The point is not the number of event types; it is that each category implies a different application behavior.
| Category | Representative events | What a consumer should do |
|---|---|---|
| Turn lifecycle | turn.created, turn.done | Open and close the local run state; inspect the terminal state and any required actions. |
| Model output | model.message, model.message.delta |
Create a message record, merge live fragments, render content, and inspect proposed tool calls. |
| Tool result | tool.response | Associate the result with the requested call through toolCallId. |
| Human pause | tool.approval_required, tool.response_required |
Render an approval or input surface and resume through a new turn. |
| MCP lifecycle | mcp.auth_required, mcp.initialize | Start the authentication flow or display server initialization status. |
| Runtime resource | sandbox.created | Expose or correlate the provisioned execution environment when useful. |
| Subagent thread | thread.created, thread.done | Create a nested execution view and group subsequent events by thread. |
4. Four identifiers, four different jobs
Event consumers often fail because they collapse every identifier into "the event ID." TrueForge exposes distinct identifiers for ordering, assembly, concurrency, and causality.
5. Deltas are transport; events are state
When text streams, TrueForge first emits a base model.message, then model.message.delta fragments that share its event ID. The UI can render those fragments immediately. Once the event is persisted, the history API returns the merged model.message; deltas are not returned as separate persisted records.
A client-side reducer should therefore index semantic events by ID, merge deltas, and keep the last processed sequence number separately:
import { TrueForgeApi, isEventDelta, mergeEventDelta } from "@truefoundry/trueforge-sdk";
const eventsById = new Map<string, TrueForgeApi.TurnStreamingEvent>();
let checkpoint = 0;
for await (const { data: event, id } of stream.withMetadata()) {
if (id != null) checkpoint = Number(id);
if (isEventDelta(event)) {
const base = eventsById.get(event.id);
if (base) mergeEventDelta(base, event);
continue;
}
eventsById.set(event.id, event);
render([...eventsById.values()]); // Application-defined UI update.
}
6. A pause is an explicit state transition
Tool approval, additional user input, and MCP authentication are not exceptional errors. They are ordinary states in an agent workflow. TrueForge represents them as tool.approval_required, tool.response_required, and mcp.auth_required events.
7. Threads make subagent concurrency visible
When an agent delegates work, events from several subagents may interleave in one turn stream. Arrival order alone does not tell the UI which worker produced which message. TrueForge uses thread IDs to preserve that structure.
8. Reconnect live; replay when live state is gone
9. What events make possible
A responsive product experience
Durable human-in-the-loop workflows
Debugging at the right level
Recovery and support
An evaluation substrate
10. Where TrueForge events fit in the TrueFoundry stack
11. A refund run, event by event
12. What events do not guarantee
13. A production checklist for event consumers
14. The deeper point: events turn agency into an interface
Frequently asked questions
Are TrueForge events the same as traces?
Are deltas stored as individual events?
Can I resume a run after the browser disconnects?
Does a turn.done event mean the user’s task is complete?
Can events prove that an external action succeeded?
References
Editorial disclosure: Product behavior is described from public TrueForge and TrueFoundry documentation available on September 3, 2026. Examples are illustrative and should be adapted to each application’s authorization, privacy, reliability, and compliance requirements.