Agent Events, Explained: The Runtime Contract Behind Reliable AI Agents

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.

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:

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.

This hierarchy prevents two common design mistakes. First, session history should not be treated as one unbounded transcript: turns provide natural execution boundaries. Second, a streamed delta should not be stored or evaluated as if it were the final semantic event.

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.

A useful detail is easy to miss: current TrueForge events do not use a top-level tool.call event. Requested calls live on model.message.toolCalls; the later tool.response refers back to the call ID. That distinction matters to reducers and audit views. A consumer designed around a nonexistent top-level event would fail to show the proposed action at the right time.

The stream begins with turn.created and closes with exactly one turn.done. The latter reports a terminal turn state of done, cancelled, or error. A new turn also cancels a prior turn that is still running in the same session. Applications should therefore use the runtime lifecycle rather than infer completion from silence or from the arrival of text.

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.

Sequence is not identity. An event can receive several streamed deltas with the same event ID while each envelope advances the sequence number. Thread membership is not causality: two events can share a subagent thread without one causing the other. Causal references are what let an approval screen say, with precision, “this model message proposed this tool call.”

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.

This is a good contract because it keeps two concerns separate:

• Live transport: optimize time to first visible output and preserve an ordered reconnect position.
• Settled state: expose one coherent message for replay, inspection, and evaluation.

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.
}

The exact SDK helpers and stream envelope vary by integration surface, so production code should follow the current TrueForge UI SDK event reference. The invariant is more important than the syntax: do not append every delta as a new chat item, and do not use a semantic event ID as a reconnect cursor.

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.

The subtlety is that the current turn can end with state done while requiredActions is non-empty. The turn is terminal; the workflow is paused. After the user approves, rejects, supplies the requested value, or completes authentication, the application creates a new turn in the same session. Approval and tool-input responses are represented as typed user input; MCP authentication resumes with a new turn after credentials are available.

This model has a practical advantage: waiting does not require holding one network request open indefinitely. The session preserves continuity, while each turn remains a bounded execution unit.

Approval is not authorization

An approval event says that the runtime requires a human decision before proceeding. It does not establish that the agent or approving user has business authority to perform the action. A refund, database mutation, deployment, or permission change still needs policy enforcement against the authoritative domain system.

Good implementations make the approval scope explicit: tool name, arguments, resource, requesting identity, expiration, and the state against which the approval was granted. If material state changes before execution, the application may need to reauthorize or reconcile before continuing.

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: the root agent uses main, subagents receive generated IDs, and thread.created/thread.done mark their lifecycles.

A parent reference can include the parent thread and the tool call that created the subagent. That lets an interface render a nested execution tree without inventing hierarchy from message text. It also improves debugging. Instead of seeing one flat timeline, an engineer can isolate a research subagent, compare its inputs with its output, and determine whether failure occurred in delegation, tool use, or synthesis.

Thread grouping is not just visual polish. With parallel work, two valid event sequences can interleave differently across runs. Consumers should preserve order within the turn while grouping presentation and analysis by thread. Otherwise a correct concurrent execution can look causally incoherent.

8. Reconnect live; replay when live state is gone

Networks fail more frequently than long-running agent tasks. A production client should persist three values as soon as they are available: session ID, turn ID, and the last sequence number it processed.

On reconnect, the client checks the turn:

1. If the turn is still running, subscribe after the last sequence number. The cursor is exclusive, so the client resumes with the next envelope.
2. If the turn has finished, rebuild the view from persisted turn events.
3. If the live stream is no longer available, the subscription API can return 412; fall back to persisted events rather than treating that as lost work.

async function resumeOrReplay(sessionId: string, turnId: string, checkpoint: number) {
  const { data: turn } = await client.sessions.getTurn(sessionId, turnId);

  if (turn.state.status === "running") {
    return client.sessions.subscribeToTurn(sessionId, turnId, {
      afterSequenceNumber: checkpoint
    });
  }

  return client.sessions.listTurnEvents(sessionId, turnId, { order: "asc" });
}

The subscription contract and persisted event endpoint deliberately serve different states. Reconnection continues a live transport; replay reconstructs settled semantic history.

9. What events make possible

A responsive product experience

Typed lifecycle and delta events let a UI show more than a typing indicator. It can display the active agent or subagent, a proposed tool action, a permission checkpoint, an authentication handoff, and a terminal error without parsing prose.

Durable human-in-the-loop workflows

Approval and response-required events turn pauses into resumable protocol states. The application can persist the required action, notify the right reviewer, collect a decision later, and continue in the same session.

Debugging at the right level

A final answer can be wrong because of a poor model response, an incorrect tool choice, stale tool data, a failed subagent, or an application-side mutation. Event structure helps localize the failure. TrueForge model-message usage data can also break input tokens into harness, instructions, messages, skills, and tool definitions, helping teams diagnose context growth and cost instead of guessing from the final output.

Recovery and support

Persisted turn and session events let an operator reconstruct the active branch of a conversation. That supports page refreshes, handoffs, incident review, and customer support without requiring the original browser connection.

An evaluation substrate

Trajectory evaluators need more than output text. They may ask whether the agent chose the right tool, requested approval before a sensitive action, delegated to the appropriate specialist, or recovered after an error. Events provide the structured evidence on which those evaluators can operate.

But events are inputs to evaluation—not evaluation itself. Task success, safety, and business impact still require application-defined criteria and, often, downstream outcome data.

10. Where TrueForge events fit in the TrueFoundry stack

TrueForge provides the agent-runtime view: sessions, turns, messages, calls, pauses, threads, and state transitions. Production evidence becomes more useful when it is correlated with the control planes around the runtime.

The natural TrueFoundry story is not that one layer “solves observability.” It is that the layers preserve different evidence and enforce different boundaries. A TrueForge event can record that a tool call was proposed and returned. MCP Gateway can govern routed access to that tool. The downstream system can prove whether the side effect committed. An evaluator can judge the combined trajectory and outcome.

11. A refund run, event by event

Consider a support agent handling “Refund order 4821.” The following is a conceptual sequence, not a promise that every deployment will emit identical payloads:

1. turn.created opens the request cycle.
2. A model.message proposes get_order in its toolCalls.
3. tool.response returns the order details and refers to that call by toolCallId.
4. A later model.message proposes process_refund.
5. tool.approval_required points to the proposed action and its source message.
6. turn.done closes this turn with a required action. The workflow is waiting, not complete.
7. The application validates the reviewer’s authority and presents the exact refund scope.
8. A new turn carries the approval response.
9. The tool boundary executes the refund using an operation or idempotency key where supported.
10. tool.response records the returned result; the payment system remains authoritative for whether the refund committed.
11. A final model.message streams confirmation through deltas, and turn.done closes the turn without required actions.

This example shows why the event layer is useful and why it cannot stand alone. The event stream explains the runtime trajectory. Authorization establishes whether the reviewer may approve. Idempotency and reconciliation protect the mutation. The payment system proves the business outcome.

12. What events do not guarantee

These limits do not weaken the event model. They make its responsibility clear. Strong production architecture is built from explicit boundaries, not from asking one telemetry surface to carry every meaning.

13. A production checklist for event consumers

• Model UI state from event types, not from parsed natural-language status messages.
• Store session ID, turn ID, and the last processed sequence number.
• Deduplicate and merge by event ID; checkpoint by sequence number.
• Keep threadId so parallel subagent events remain intelligible.
• Preserve tool-call and source-event references for approvals and debugging.
• Inspect requiredActions before declaring a workflow complete.
• Reconnect to running turns; rebuild finished turns from persisted events.
• Expect live deltas to disappear from persisted history after they are merged.
• Correlate runtime events with gateway telemetry and domain outcomes.
• Apply retention, redaction, and access policies to event payloads that may contain sensitive data.
• Version reducers against the documented event union and handle unknown event types safely.

14. The deeper point: events turn agency into an interface

Agents become operationally interesting when they do work across time, tools, people, and systems. That is also when a single response stops being an adequate contract.

TrueForge events expose the intermediate structure: model messages, tool results, approval gates, authentication needs, resource creation, subagent threads, and turn lifecycle. Live deltas make the experience responsive. Persisted events make it recoverable. Stable identities and causal references make it debuggable. Together, they give product and platform teams a shared vocabulary for what the runtime is doing.

The most mature use of that vocabulary is disciplined rather than maximalist. Let TrueForge events describe runtime execution. Let AI Gateway and MCP Gateway govern model and tool boundaries. Let systems of record establish committed business state. Let evaluators turn the joined evidence into judgments.

Frequently asked questions

Are TrueForge events the same as traces?

No. They can be correlated, but they serve different contracts. Events represent application-relevant runtime occurrences and state transitions. Traces organize operations into spans and are especially useful for latency, dependency, and request-flow analysis. A production system benefits from both.

Are deltas stored as individual events?

They are part of the live stream. Persisted turn-event listings return the assembled model message rather than its individual deltas.

Can I resume a run after the browser disconnects?

Yes. Check whether the turn is still running. If it is, subscribe after the last processed sequence number. If it has finished—or the live stream is no longer available—rebuild from persisted events.

Does a turn.done event mean the user’s task is complete?

Not necessarily. The turn is terminal, but it can include required actions such as a tool approval, user response, or authentication step. The workflow continues through a new turn in the same session.

Can events prove that an external action succeeded?

They can record the request and the response observed by the runtime. For consequential mutations, confirm committed state in the authoritative downstream system and design retries around idempotency or reconciliation.

References

1. TrueForge API overview: agent, session, turn, event, and delta hierarchy
2. TrueForge guide: creating sessions and streaming turns
3. TrueForge UI SDK: event union, deltas, and thread grouping
4. TrueForge API: list persisted turn events
5. TrueForge API: list events across the active session branch
6. TrueForge API: subscribe to a running turn
7. TrueFoundry AI Gateway overview
8. TrueFoundry MCP Gateway overview
9. TrueFoundry Agent Registry overview
10. TrueFoundry Skills Registry and Agent Harness skills
11. OpenTelemetry generative AI semantic attributes
12. WHATWG Server-Sent Events specification

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.

‍