Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Add docs page for use agent (#133)

Chirag Jain97cc41054ee5
diff --git a/docs/api/overview.mdx b/docs/api/overview.mdx
index 797f49ed1..208e1fcbe 100644
--- a/docs/api/overview.mdx
+++ b/docs/api/overview.mdx
@@ -4,7 +4,7 @@ sidebarTitle: 'Overview'
description: 'Understand Agent, Session, Turn, Event, and Delta — then create sessions, run turns, and stream events over REST or the TypeScript SDK.'
---
-Everything the chat UI does goes through the HTTP API, so anything you can do in the UI you can automate. The API is served under `/api/v1`, documented interactively at `/api/v1/docs` (OpenAPI 3.1 at `/api/v1/openapi.json`). A generated TypeScript client, [`trueforge`](https://www.npmjs.com/package/trueforge), wraps the same API.
+Everything the chat UI does goes through the HTTP API, so anything you can do in the UI you can automate. The API is served under `/api/v1`, documented interactively at `/api/v1/docs` (OpenAPI 3.1 at `/api/v1/openapi.json`). A generated TypeScript client, [`trueforge-sdk`](https://www.npmjs.com/package/trueforge-sdk), wraps the same API. For a full SDK cookbook (streaming, approvals, reconnects, threads), see [Use an agent](/api/use-agent).
## Core concepts
@@ -301,7 +301,7 @@ A separate issue — Bob's shipping question, or even Jane's next problem — ru
### 1. Create a session
-Pass an inline agent spec (`type: "value"`), or reference a saved agent by id (`type: "ref"`):
+Pass an inline agent spec (`{ "spec": ... }`), or reference a saved agent by name (`{ "name": "..." }`):
<Tabs>
<Tab title="curl">
@@ -311,8 +311,7 @@ curl -X POST http://localhost:8790/api/v1/sessions \
-H 'Content-Type: application/json' \
-d '{
"agent": {
- "type": "value",
- "agent_spec": {
+ "spec": {
"model": { "name": "anthropic/claude-sonnet-4-6" },
"instructions": "You help customers with orders. Always confirm before processing refunds.",
"mcp_servers": [
@@ -331,10 +330,9 @@ import { TrueForge } from 'trueforge-sdk';
const client = new TrueForge({ baseUrl: 'http://localhost:8790' });
-const session = await client.sessions.create({
+const { data: session } = await client.sessions.create({
agent: {
- type: 'value',
- agent_spec: {
+ spec: {
model: { name: 'anthropic/claude-sonnet-4-6' },
instructions: 'You help customers with orders. Always confirm before processing refunds.',
mcp_servers: [{ name: 'orders-api', require_approval_for_tools: ['process_refund'] }],
@@ -365,11 +363,11 @@ curl -N -X POST http://localhost:8790/api/v1/sessions/sess-7f2a9c1b/turns \
<Tab title="TypeScript">
```typescript
-const stream = await client.sessions.createTurnStream(sessionId, {
+const stream = await client.sessions.createTurnStream(session.id, {
input: [{ type: 'user.message', content: 'What is the status of order ORD-2031?' }],
});
-for await (const event of stream) {
+for await (const { data: event } of stream.withMetadata()) {
switch (event.type) {
case 'model.message.delta':
process.stdout.write(event.content ?? '');
@@ -381,6 +379,8 @@ for await (const event of stream) {
}
```
+See [Use an agent](/api/use-agent) for delta merging, approvals, reconnects, and more.
+
</Tab>
</Tabs>
diff --git a/docs/api/use-agent.mdx b/docs/api/use-agent.mdx
new file mode 100644
index 000000000..ef5829d7c
--- /dev/null
+++ b/docs/api/use-agent.mdx
@@ -0,0 +1,795 @@
+---
+title: 'Use an agent'
+sidebarTitle: 'Use an agent'
+description: 'Run a saved agent with the TypeScript SDK — create sessions, stream turns, merge deltas, and handle approvals, questions, threads, and reconnects.'
+---
+
+This guide covers everything you need to **run** an agent with [`trueforge-sdk`](https://www.npmjs.com/package/trueforge-sdk): open a session, send turns, consume the event stream, and handle pauses, threads, and disconnects.
+
+For the conceptual hierarchy (Agent → Session → Turn → Event → Delta) and a short end-to-end walkthrough, see [Using the API](/api/overview). For every event field, see [Turn events](/api/turn-events).
+
+<Note>
+Prerequisite: a named agent in the registry, or an inline [agent spec](/api/agent-spec) you pass when creating the session. The quickest path to a named agent is the [Quickstart](/quickstart) UI.
+</Note>
+
+## Install and connect
+
+```bash
+npm i -s trueforge-sdk
+```
+
+```typescript
+import { TrueForge } from 'trueforge-sdk';
+
+const client = new TrueForge({
+ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
+ // Raise for long-running SSE turns (default is 60s).
+ timeoutInSeconds: 600,
+ // Optional: pass whatever your deployment uses for auth.
+ // headers: { Authorization: `Bearer ${process.env.TRUEFORGE_TOKEN}` },
+});
+```
+
+The harness has no built-in API-key auth. Point `baseUrl` at your deployment (standalone default: `http://localhost:8790`). Pass `headers` when your reverse proxy or OIDC layer requires them.
+
+## Create a session
+
+A **session** is the conversation context for one issue with an agent. It persists across many turns; persist `session.id` to resume later.
+
+```mermaid
+stateDiagram-v2
+ [*] --> active: sessions.create()
+ active --> active: createTurnStream() (many turns)
+ active --> cancelled: sessions.cancel()
+ cancelled --> [*]
+```
+
+### Open a session
+
+Create a session by agent name, or pass an inline [agent spec](/api/agent-spec):
+
+```typescript
+import { TrueForge } from 'trueforge-sdk';
+
+const client = new TrueForge({
+ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
+ timeoutInSeconds: 600,
+});
+
+// Reference a saved agent by name.
+const { data: session } = await client.sessions.create({
+ agent: { name: 'support-bot' },
+});
+
+// Or pass an inline spec:
+// const { data: session } = await client.sessions.create({
+// agent: {
+// spec: {
+// model: { name: 'anthropic/claude-sonnet-4-6' },
+// instructions: 'You help customers with orders.',
+// },
+// },
+// });
+
+console.log('session id:', session.id);
+```
+
+### List sessions
+
+List your sessions with `sessions.list()`. Newest-first by default; filter with `agentId` when you only want sessions for one saved agent. The returned `Page` is an async iterable and auto-paginates.
+
+```typescript
+import { TrueForge } from 'trueforge-sdk';
+
+const client = new TrueForge({
+ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
+});
+
+for await (const session of await client.sessions.list({ agentId: 'agent-support-bot' })) {
+ console.log('session id:', session.id);
+ console.log('created at:', session.createdAt);
+}
+```
+
+## Create a turn
+
+A **turn** is one request/response cycle. Send input, the agent runs until it finishes or pauses, then the stream closes. Create another turn on the same session to continue — turns chain automatically (`previousTurnId` defaults to `"auto"`).
+
+### Create and stream a turn
+
+`sessions.createTurnStream` creates the turn and returns a stream of [turn events](/api/turn-events). The first event is always `turn.created` (carrying `turnId`); the stream closes with `turn.done`.
+
+`stream.withMetadata()` yields each SSE message as `{ data, id }`: `data` is the parsed event, and `id` is the per-stream sequence number used to [resume after a disconnect](#resume-streaming).
+
+Read the terminal state from the final `turn.done` event (or call `sessions.getTurn` afterward). To continue the conversation, create another turn on the same session — each turn sees the history of the ones before it.
+
+<Note>
+Creating a new turn in a session automatically cancels any other turn that is still running in that session.
+</Note>
+
+```typescript
+import { TrueForge } from 'trueforge-sdk';
+
+const client = new TrueForge({
+ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
+ timeoutInSeconds: 600,
+});
+const { data: session } = await client.sessions.create({
+ agent: { name: 'support-bot' },
+});
+
+const stream = await client.sessions.createTurnStream(session.id, {
+ input: [{ type: 'user.message', content: 'I would like to file a support ticket.' }],
+});
+
+let turnId: string | undefined;
+let lastSequenceNumber = 0;
+for await (const { data: event, id } of stream.withMetadata()) {
+ if (id != null) {
+ lastSequenceNumber = Number(id);
+ }
+ console.log(event.type);
+ if (event.type === 'turn.created') {
+ turnId = event.turnId;
+ }
+ if (event.type === 'turn.done') {
+ console.log('final status:', event.state.status);
+ }
+}
+
+// Create another turn on the same session. Turns are chained automatically.
+const next = await client.sessions.createTurnStream(session.id, {
+ input: [{ type: 'user.message', content: 'Use my last order, ORD-2031.' }],
+});
+for await (const { data: event, id } of next.withMetadata()) {
+ if (id != null) {
+ lastSequenceNumber = Number(id);
+ }
+ console.log(event.type);
+}
+```
+### List turns
+
+List turns in a session with `sessions.listTurns()`. Turns are returned oldest-first. Each turn exposes its `input` and `state`.
+
+```typescript
+import { TrueForge } from 'trueforge-sdk';
+
+const client = new TrueForge({
+ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
+});
+
+for await (const turn of await client.sessions.listTurns('sess-abc123')) {
+ console.log('turn id:', turn.id);
+ console.log('input:', turn.input);
+
+ const turnState = turn.state;
+ if (turnState.status === 'running') {
+ console.log('status: running (no output yet)');
+ } else if (turnState.status === 'done') {
+ console.log('status: done');
+ if (turnState.output != null) {
+ console.log('output:', turnState.output.content);
+ }
+ // requiredActions lists any pause events the turn surfaced
+ // (tool.approval_required, tool.response_required, mcp.auth_required).
+ for (const item of turnState.requiredActions) {
+ console.log('required action:', item);
+ }
+ } else if (turnState.status === 'cancelled') {
+ console.log('status: cancelled', turnState.reason);
+ } else if (turnState.status === 'error') {
+ console.log('status: error', turnState.message);
+ }
+}
+```
+
+### Non-streaming turn
+
+If you don't need live events on the create call, use `sessions.createTurn` (sets `stream: false`). It returns the turn immediately with `state.status: "running"` while execution continues in the background. Poll `sessions.getTurn` until `state.status` is terminal (`done`, `cancelled`, or `error`).
+
+```typescript
+import { TrueForge } from 'trueforge-sdk';
+
+const client = new TrueForge({
+ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
+});
+const { data: session } = await client.sessions.create({
+ agent: { name: 'support-bot' },
+});
+
+const { data: created } = await client.sessions.createTurn(session.id, {
+ input: [{ type: 'user.message', content: 'Summarize my last order.' }],
+});
+
+let turn = created;
+while (turn.state.status === 'running') {
+ await new Promise((resolve) => setTimeout(resolve, 500));
+ ({ data: turn } = await client.sessions.getTurn(session.id, created.id));
+}
+
+const turnState = turn.state;
+if (turnState.status === 'done') {
+ if (turnState.output != null) {
+ console.log(turnState.output.content);
+ } else {
+ console.log('required actions:', turnState.requiredActions);
+ }
+} else if (turnState.status === 'cancelled') {
+ console.log('cancelled:', turnState.reason);
+} else if (turnState.status === 'error') {
+ console.log('error:', turnState.message);
+}
+```
+
+### Attach images or files to a turn
+
+A `user.message`'s `content` can be a plain string or a list of content parts. Use content parts to send text alongside one or more file uploads (images, PDFs, and other documents). Each file is passed as a [data URI](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) of the form `data:<mime>;base64,<payload>`.
+
+```typescript
+import { readFileSync } from 'node:fs';
+import { TrueForge } from 'trueforge-sdk';
+
+const client = new TrueForge({
+ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
+ timeoutInSeconds: 600,
+});
+const { data: session } = await client.sessions.create({
+ agent: { name: 'support-bot' },
+});
+
+function toDataUri(path: string, mime: string): string {
+ return `data:${mime};base64,${readFileSync(path).toString('base64')}`;
+}
+
+const imageUri = toDataUri('invoice.png', 'image/png');
+const docUri = toDataUri('notes.txt', 'text/plain');
+
+const stream = await client.sessions.createTurnStream(session.id, {
+ input: [
+ {
+ type: 'user.message',
+ content: [
+ { type: 'text', text: 'Does the invoice total match the notes?' },
+ { type: 'file', name: 'invoice.png', data: imageUri },
+ { type: 'file', name: 'notes.txt', data: docUri },
+ ],
+ },
+ ],
+});
+for await (const { data: event, id } of stream.withMetadata()) {
+ console.log(event.type, id);
+}
+```
+
+<Note>
+Whether an attached file is understood depends on the agent's model. Send images only to a vision-capable model; document handling (for example, PDFs) likewise depends on model and agent configuration.
+</Note>
+
+<Note>
+Non-image files such as PDFs require the [sandbox](/sandbox) to be enabled on the agent — the harness uses it to process the document.
+</Note>
+
+### Cancel a turn
+
+To stop the currently running turn, call `sessions.cancel(sessionId)`. Cancelling aborts any in-flight model request, waits for running MCP tool calls to finish, and force-stops any sandbox the turn provisioned. Cancellation is idempotent. You can continue by creating a new turn, which chains on the cancelled turn's history.
+
+```typescript
+import { TrueForge } from 'trueforge-sdk';
+
+const client = new TrueForge({
+ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
+ timeoutInSeconds: 600,
+});
+const { data: session } = await client.sessions.create({
+ agent: { name: 'support-bot' },
+});
+
+const stream = await client.sessions.createTurnStream(session.id, {
+ input: [{ type: 'user.message', content: 'Run a long research task.' }],
+});
+
+let i = 0;
+let turnId: string | undefined;
+let lastSequenceNumber = 0;
+for await (const { data: event, id } of stream.withMetadata()) {
+ if (id != null) {
+ lastSequenceNumber = Number(id);
+ }
+ console.log(event.type);
+ if (event.type === 'turn.created') {
+ turnId = event.turnId;
+ }
+ if (i === 5) {
+ // Don't break here. After cancel(), the backend closes the SSE stream
+ // gracefully: it emits a terminal turn.done event and then ends the
+ // stream, which closes this iterator on its own.
+ await client.sessions.cancel(session.id);
+ }
+ i += 1;
+}
+
+// A cancelled turn is terminal, so its event log is stored and can be replayed.
+if (turnId != null) {
+ for await (const event of await client.sessions.listTurnEvents(session.id, turnId, { order: 'asc' })) {
+ console.log(event);
+ }
+}
+
+// Continue the conversation: a new turn chains on the cancelled turn's history.
+const next = await client.sessions.createTurnStream(session.id, {
+ input: [{ type: 'user.message', content: 'Actually, just give me a quick summary instead.' }],
+});
+for await (const { data: event, id } of next.withMetadata()) {
+ if (id != null) {
+ lastSequenceNumber = Number(id);
+ }
+ console.log(event.type);
+}
+```
+
+### Handle MCP outbound auth
+
+When the agent needs to call a tool on an MCP server that requires a separate outbound authentication, it emits an [`mcp.auth_required`](/api/turn-events#mcp-auth-required) event and the turn ends. The event lists each server that needs authentication along with an `authUrl`. Send the user to that URL to complete authentication, then resume by creating a new turn. See [In-chat authentication](/mcp-servers#in-chat-authentication).
+
+<Note>
+When the previous turn ended with `mcp.auth_required`, passing a `user.message` in the resuming turn is not allowed. Resume with an empty `input` (or omit `input`).
+</Note>
+
+```typescript
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { TrueForge, TrueForgeApi } from 'trueforge-sdk';
+
+const client = new TrueForge({
+ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
+ timeoutInSeconds: 600,
+});
+const { data: session } = await client.sessions.create({
+ agent: { name: 'support-bot' },
+});
+const rl = createInterface({ input: stdin, output: stdout });
+
+let pendingAuth: TrueForgeApi.McpAuthRequiredEvent | undefined;
+const stream = await client.sessions.createTurnStream(session.id, {
+ input: [{ type: 'user.message', content: 'Summarize my latest GitHub issues.' }],
+});
+for await (const { data: event } of stream.withMetadata()) {
+ console.log(event);
+ if (event.type === 'mcp.auth_required') {
+ pendingAuth = event;
+ }
+}
+
+if (pendingAuth != null) {
+ for (const server of pendingAuth.mcpServers) {
+ console.log(`Authorize ${server.name}: ${server.authUrl}`);
+ }
+ await rl.question('Press Enter once you have authorized the server(s)...');
+}
+
+// Resume — the agent continues the interrupted work.
+const resume = await client.sessions.createTurnStream(session.id, {});
+for await (const { data: event } of resume.withMetadata()) {
+ console.log(event);
+}
+rl.close();
+```
+
+### Handle tool approvals
+
+When a tool call is configured to require [human approval](/human-in-the-loop), the agent emits a [`tool.approval_required`](/api/turn-events#tool-approval-required) event and the turn ends. Each event carries a `threadId` and the `toolCalls` awaiting a decision — a single turn can emit more than one (for example, when parallel threads each call a gated tool), so collect all of them. Resume by creating a new turn with one `user.tool_approval` item per pending tool call — allow it, or deny it with an optional reason.
+
+Each pending tool-call ref carries the `sourceEventId` of the [`model.message`](/api/turn-events#model-message) that emitted the tool call. Keep the same `id`-keyed [event index](#handling-event-delta-while-streaming) you build while streaming, then look up `events.get(sourceEventId)` to read the tool's name and arguments.
+
+```typescript
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import {
+ TrueForge,
+ TrueForgeApi,
+ isEventDelta,
+ mergeEventDelta,
+} from 'trueforge-sdk';
+
+const client = new TrueForge({
+ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
+ timeoutInSeconds: 600,
+});
+const { data: session } = await client.sessions.create({
+ agent: { name: 'support-bot' },
+});
+const rl = createInterface({ input: stdin, output: stdout });
+
+const events = new Map<string, TrueForgeApi.TurnStreamingEvent>();
+const pendingApprovals: TrueForgeApi.ToolApprovalRequiredEvent[] = [];
+
+const stream = await client.sessions.createTurnStream(session.id, {
+ input: [{ type: 'user.message', content: 'Restart the billing service.' }],
+});
+for await (const { data: message } of stream.withMetadata()) {
+ if (isEventDelta(message)) {
+ const base = events.get(message.id);
+ if (base) mergeEventDelta(base, message);
+ } else {
+ events.set(message.id, message);
+ }
+ if (message.type === 'tool.approval_required') {
+ pendingApprovals.push(message);
+ }
+}
+
+const approvals: TrueForgeApi.UserToolApprovalEvent[] = [];
+for (const pending of pendingApprovals) {
+ for (const ref of pending.toolCalls) {
+ const modelMessage = events.get(ref.sourceEventId);
+ if (modelMessage?.type !== 'model.message') continue;
+ const toolCall = modelMessage.toolCalls?.find((tc) => tc.id === ref.id);
+ if (toolCall == null) continue;
+ console.log(`\napproval needed: ${toolCall.toolInfo.name}`);
+ console.log(` arguments: ${toolCall.function.arguments}`);
+ const answer = (await rl.question('allow? [y/n] ')).trim().toLowerCase();
+ approvals.push({
+ type: 'user.tool_approval',
+ threadId: pending.threadId,
+ toolCallId: ref.id,
+ approval: answer === 'y' ? { status: 'allow' } : { status: 'deny', reason: 'denied by user' },
+ });
+ }
+}
+
+const resume = await client.sessions.createTurnStream(session.id, { input: approvals });
+for await (const { data: event } of resume.withMetadata()) {
+ console.log(event);
+}
+rl.close();
+```
+
+### Answer agent questions
+
+When the agent needs input it cannot safely assume, it can ask the user a structured question via the built-in client-side [`ask_user_question`](/ask-user-questions) tool. Since the tool runs on your side, the agent emits a [`tool.response_required`](/api/turn-events#tool-response-required) event and the turn ends. The pending tool call's `arguments` carry the `question` and its `options`. Collect the user's answer and resume by creating a new turn with one `user.tool_response` item per pending tool call.
+
+```typescript
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import {
+ TrueForge,
+ TrueForgeApi,
+ isEventDelta,
+ mergeEventDelta,
+} from 'trueforge-sdk';
+
+const client = new TrueForge({
+ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
+ timeoutInSeconds: 600,
+});
+const { data: session } = await client.sessions.create({
+ agent: { name: 'support-bot' },
+});
+const rl = createInterface({ input: stdin, output: stdout });
+
+const events = new Map<string, TrueForgeApi.TurnStreamingEvent>();
+const pendingQuestions: TrueForgeApi.ToolResponseRequiredEvent[] = [];
+
+const stream = await client.sessions.createTurnStream(session.id, {
+ input: [{ type: 'user.message', content: 'Create a new environment called testing-1.' }],
+});
+for await (const { data: message } of stream.withMetadata()) {
+ if (isEventDelta(message)) {
+ const base = events.get(message.id);
+ if (base) mergeEventDelta(base, message);
+ } else {
+ events.set(message.id, message);
+ }
+ if (message.type === 'tool.response_required') {
+ pendingQuestions.push(message);
+ }
+}
+
+const responses: TrueForgeApi.UserToolResponseEvent[] = [];
+for (const pending of pendingQuestions) {
+ for (const ref of pending.toolCalls) {
+ const modelMessage = events.get(ref.sourceEventId);
+ if (modelMessage?.type !== 'model.message') continue;
+ const toolCall = modelMessage.toolCalls?.find((tc) => tc.id === ref.id);
+ if (toolCall == null) continue;
+ // tool.response_required covers any client-side tool; handle ask_user_question here.
+ if (!(toolCall.toolInfo.type === 'truefoundry-system' && toolCall.toolInfo.name === 'ask_user_question')) {
+ continue;
+ }
+ const args = JSON.parse(toolCall.function.arguments || '{}') as {
+ question?: string;
+ options?: string[];
+ };
+ console.log(`\n${args.question ?? ''}`);
+ (args.options ?? []).forEach((option, idx) => {
+ console.log(` ${idx + 1}. ${option}`);
+ });
+ const answer = (await rl.question('your answer: ')).trim();
+ responses.push({
+ type: 'user.tool_response',
+ threadId: pending.threadId,
+ toolCallId: ref.id,
+ // content is a free-form string — the chosen option, or any text.
+ content: answer,
+ });
+ }
+}
+
+const resume = await client.sessions.createTurnStream(session.id, { input: responses });
+for await (const { data: event } of resume.withMetadata()) {
+ console.log(event);
+}
+rl.close();
+```
+
+## Subscribe to events
+
+Every turn emits a stream of **events** over SSE. The stream opens with [`turn.created`](/api/turn-events#turn-created) and closes with [`turn.done`](/api/turn-events#turn-done). See the [turn events reference](/api/turn-events) for every event type.
+
+### Handling event delta while streaming
+
+Most events in a turn are complete on their own — a single payload you can use directly. Some updates are streamed instead: the base event arrives first, followed by a series of deltas — incremental fragments that you merge into the base. All deltas for one update share the base event's `id`.
+
+```json
+// Base assembled event arrives first
+{ "type": "model.message", "id": "0f3a9c2b-7d41-4e8a-b2c6-1a5f9e3d2b48", "content": "" }
+
+// Deltas follow: same id, each merged into the base
+{ "type": "model.message.delta", "id": "0f3a9c2b-7d41-4e8a-b2c6-1a5f9e3d2b48", "content": "Hel" }
+{ "type": "model.message.delta", "id": "0f3a9c2b-7d41-4e8a-b2c6-1a5f9e3d2b48", "content": "lo" }
+{ "type": "model.message.delta", "id": "0f3a9c2b-7d41-4e8a-b2c6-1a5f9e3d2b48", "content": "!", "finish_reason": "stop" }
+
+// After merging every delta, the base holds the full message
+{ "type": "model.message", "id": "0f3a9c2b-7d41-4e8a-b2c6-1a5f9e3d2b48", "content": "Hello!", "finish_reason": "stop" }
+```
+
+Because every delta carries the base event's `id`, keep an `id`-keyed index of assembled events: store each non-delta event under its `id`, and merge each delta into the base with the same `id`. The `id` is unique per message, so deltas from concurrently streaming threads (the main agent and any subagents) always merge into the right base.
+
+The SDK exports `isEventDelta` and `mergeEventDelta` for this:
+
+```typescript
+import { TrueForge, TrueForgeApi, isEventDelta, mergeEventDelta } from 'trueforge-sdk';
+
+const client = new TrueForge({
+ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
+ timeoutInSeconds: 600,
+});
+const { data: session } = await client.sessions.create({
+ agent: { name: 'support-bot' },
+});
+
+const events = new Map<string, TrueForgeApi.TurnStreamingEvent>();
+
+const stream = await client.sessions.createTurnStream(session.id, {
+ input: [{ type: 'user.message', content: 'Summarize my last order.' }],
+});
+for await (const { data: message } of stream.withMetadata()) {
+ if (isEventDelta(message)) {
+ const base = events.get(message.id);
+ if (base) mergeEventDelta(base, message);
+ } else {
+ events.set(message.id, message);
+ }
+}
+```
+
+<Note>
+Event deltas appear only while streaming. When you [list turn events](#listing-events) via the events API, the deltas are already merged into a single assembled event.
+</Note>
+
+### Resume streaming
+
+When you lose the original `createTurnStream` connection (for example, after a process restart), call `sessions.getTurn`, then check `turn.state`. If it is still running, reconnect with `sessions.subscribeToTurn` and pass `afterSequenceNumber` to continue after a known point; if it has already finished, rebuild the index from `sessions.listTurnEvents` instead.
+
+```typescript
+import { TrueForge, TrueForgeApi, isEventDelta, mergeEventDelta } from 'trueforge-sdk';
+
+const client = new TrueForge({
+ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
+ timeoutInSeconds: 600,
+});
+const { data: session } = await client.sessions.create({
+ agent: { name: 'support-bot' },
+});
+
+const stream = await client.sessions.createTurnStream(session.id, {
+ input: [{ type: 'user.message', content: 'Summarize my last order.' }],
+});
+
+let turnId: string | undefined;
+let lastSequenceNumber = 0;
+const events = new Map<string, TrueForgeApi.TurnStreamingEvent>();
+
+for await (const { data: message, id } of stream.withMetadata()) {
+ if (id != null) {
+ lastSequenceNumber = Number(id);
+ }
+ if (message.type === 'turn.created') {
+ turnId = message.turnId;
+ }
+ if (isEventDelta(message)) {
+ const base = events.get(message.id);
+ if (base) mergeEventDelta(base, message);
+ } else {
+ events.set(message.id, message);
+ }
+}
+
+// Persist session.id, turnId, lastSequenceNumber (and optionally `events`) so you
+// can resume after a process restart. After a disconnect:
+
+const { data: turn } = await client.sessions.getTurn(session.id, turnId!);
+
+if (turn.state.status === 'running') {
+ // Still running: reconnect. afterSequenceNumber skips events you've already processed.
+ const resume = await client.sessions.subscribeToTurn(
+ session.id,
+ turnId!,
+ { afterSequenceNumber: lastSequenceNumber },
+ { timeoutInSeconds: 600 },
+ );
+ for await (const { data: message, id } of resume.withMetadata()) {
+ if (id != null) {
+ lastSequenceNumber = Number(id);
+ }
+ if (isEventDelta(message)) {
+ const base = events.get(message.id);
+ if (base) mergeEventDelta(base, message);
+ } else {
+ events.set(message.id, message);
+ }
+ }
+} else {
+ // Already finished: rebuild from the stored event log (deltas already merged).
+ for await (const event of await client.sessions.listTurnEvents(session.id, turnId!)) {
+ events.set(event.id, event);
+ }
+}
+```
+
+<Tip>
+`sessions.createTurn` followed by `sessions.subscribeToTurn` is resumable: the SDK reconnects with `Last-Event-ID` on transient drops. Persist the sequence number from `.withMetadata()` so you can call `subscribeToTurn({ afterSequenceNumber })` again after a process restart.
+</Tip>
+
+### Handle threads
+
+A single turn stream interleaves events from the root agent and any [subagents](/context-engineering/subagents) that run in parallel. Every event carries a `threadId`:
+
+- `"main"` — the root agent.
+- A unique id — a subagent thread. [`thread.created`](/api/turn-events#thread-created) and [`thread.done`](/api/turn-events#thread-done) mark subagent thread lifecycle; they are not emitted for the main thread.
+- `null` — a turn-level event, not tied to any thread: [`turn.created`](/api/turn-events#turn-created) and [`turn.done`](/api/turn-events#turn-done) (first and last on the stream), [`sandbox.created`](/api/turn-events#sandbox-created), and [`mcp.auth_required`](/api/turn-events#mcp-auth-required).
+
+The sequence below shows a turn where the root agent spawns a **research** subagent. Events interleave across two threads (`main` and the subagent), and the run pauses for an approval before a second turn resumes it.
+
+```mermaid
+sequenceDiagram
+ actor Client
+ box Session
+ participant Main as main thread
+ participant Research as research thread
+ end
+
+ Note over Client,Research: Turn 1 — user message
+ Client->>Main: user.message
+ Note over Client,Main: SSE stream opens
+ Main-->>Client: model.message
+ Main-->>Client: model.message.delta
+ Main-->>Client: model.message.delta
+ Main->>Research: spawn sub-agent
+ Main-->>Client: thread.created
+ Research-->>Client: model.message
+ Research-->>Client: model.message.delta
+ Research-->>Client: model.message.delta
+ Research-->>Client: tool.approval_required
+ Note over Client,Research: Turn 1 pauses — awaiting approval
+
+ Note over Client,Research: Turn 2 — approval resumes the run
+ Client->>Research: user.tool_approval
+ Research-->>Client: tool.response
+ Research-->>Client: model.message
+ Research-->>Client: model.message.delta
+ Research->>Main: sub-agent completes
+ Main-->>Client: thread.done
+ Main-->>Client: model.message
+ Main-->>Client: model.message.delta
+ Main-->>Client: model.message.delta
+```
+
+```typescript
+import { TrueForge, TrueForgeApi, isEventDelta, mergeEventDelta } from 'trueforge-sdk';
+
+const client = new TrueForge({
+ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
+ timeoutInSeconds: 600,
+});
+const { data: session } = await client.sessions.create({
+ agent: { name: 'support-bot' },
+});
+
+const threads = new Map<string, Map<string, TrueForgeApi.TurnStreamingEvent>>();
+
+const stream = await client.sessions.createTurnStream(session.id, {
+ input: [{ type: 'user.message', content: 'Summarize my last order.' }],
+});
+for await (const { data: message } of stream.withMetadata()) {
+ if (message.threadId == null) {
+ console.log('turn level event:', message);
+ continue;
+ }
+
+ if (message.type === 'model.message' || message.type === 'model.message.delta') {
+ for (const toolCall of message.toolCalls ?? []) {
+ if (toolCall.toolInfo?.type === 'truefoundry-system' && toolCall.toolInfo.name === 'create_sub_agent') {
+ console.log('sub agent is getting initialized');
+ }
+ }
+ }
+ if (message.type === 'thread.created') {
+ console.log(`${message.threadId} created: ${message.title}`);
+ }
+
+ if (isEventDelta(message)) {
+ const base = threads.get(message.threadId)?.get(message.id);
+ if (base) mergeEventDelta(base, message);
+ } else {
+ let bucket = threads.get(message.threadId);
+ if (!bucket) {
+ bucket = new Map();
+ threads.set(message.threadId, bucket);
+ }
+ bucket.set(message.id, message);
+ }
+
+ if (message.type === 'thread.done') {
+ const eventsForThread = threads.get(message.threadId) ?? new Map();
+ threads.delete(message.threadId);
+ console.log(`${message.threadId} done: ${message.title} (${eventsForThread.size} events)`);
+ }
+}
+```
+### Listing events
+
+Fetch the full event log of a finished turn with `sessions.listTurnEvents()`. It yields the turn's [events](/api/turn-events) in order and auto-paginates. Pass `order: "asc"` (default, oldest-first) or `order: "desc"`.
+
+Unlike `createTurnStream` and `subscribeToTurn`, `listTurnEvents` returns already-merged events: each model message arrives as a single assembled `model.message`, never as a base plus deltas. There is nothing to merge — you can use each event directly.
+
+For example, a model message that the live stream delivers as a base event followed by deltas:
+
+```json
+// On the live stream: a base event plus its deltas, all sharing one id
+{ "type": "model.message", "id": "0f3a...", "content": "" }
+{ "type": "model.message.delta", "id": "0f3a...", "content": "Hel" }
+{ "type": "model.message.delta", "id": "0f3a...", "content": "lo!", "finish_reason": "stop" }
+```
+
+is returned by `listTurnEvents` as one fully-merged event:
+
+```json
+// On listTurnEvents: the same message, already assembled
+{ "type": "model.message", "id": "0f3a...", "content": "Hello!", "finish_reason": "stop" }
+```
+
+<Note>
+`listTurnEvents` is only available for turns that have completed. A running turn has no stored event log yet — use `createTurnStream` or `subscribeToTurn` for live delivery instead.
+</Note>
+
+```typescript
+import { TrueForge } from 'trueforge-sdk';
+
+const client = new TrueForge({
+ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
+});
+
+// Turns are returned oldest-first; walk them and skip any still running.
+for await (const turn of await client.sessions.listTurns('sess-abc123')) {
+ if (turn.state.status === 'running') {
+ continue;
+ }
+ for await (const event of await client.sessions.listTurnEvents('sess-abc123', turn.id, {
+ order: 'asc',
+ })) {
+ console.log(event);
+ }
+}
+```
diff --git a/docs/docs.json b/docs/docs.json
index 1e1acef02..b258a5b30 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -59,7 +59,7 @@
},
{
"group": "API",
- "pages": ["api/overview", "api/agent-spec", "api/turn-events"]
+ "pages": ["api/overview", "api/use-agent", "api/agent-spec", "api/turn-events"]
},
{
"group": "Project",
diff --git a/packages/sdk/.fernignore b/packages/sdk/.fernignore
index 7f5ed9c0c..f8e765c41 100644
--- a/packages/sdk/.fernignore
+++ b/packages/sdk/.fernignore
@@ -1,2 +1,3 @@
pnpm-workspace.yaml
-src/index.ts
\ No newline at end of file
+src/index.ts
+src/events.ts
diff --git a/packages/sdk/src/events.ts b/packages/sdk/src/events.ts
new file mode 100644
index 000000000..9625db0ee
--- /dev/null
+++ b/packages/sdk/src/events.ts
@@ -0,0 +1,117 @@
+import type * as TrueForge from "./api/index.js";
+
+/**
+ * Returns true when `event` is a streaming delta that must be merged into a
+ * base `model.message` with the same `id`.
+ */
+export function isEventDelta(event: { type: string }): event is TrueForge.ModelMessageDeltaEvent {
+ return event.type === "model.message.delta";
+}
+
+/**
+ * Merges a `model.message.delta` into its base `model.message` in place.
+ *
+ * Deltas and their base share an `id`. Content / reasoning text is appended;
+ * tool-call fragments are merged by `index`; `finishReason`, `usage`, and
+ * `refusal` overwrite when present on the delta.
+ *
+ * No-ops when `base` is not a `model.message` or the ids do not match.
+ */
+export function mergeEventDelta(
+ base: TrueForge.TurnStreamingEvent | TrueForge.ModelMessageEvent,
+ delta: TrueForge.ModelMessageDeltaEvent,
+): void {
+ if (base.type !== "model.message") {
+ return;
+ }
+ if (base.id !== delta.id) {
+ return;
+ }
+
+ if (delta.content != null && delta.content.length > 0) {
+ if (base.content == null || typeof base.content === "string") {
+ base.content = `${base.content ?? ""}${delta.content}`;
+ }
+ }
+
+ if (delta.reasoningContent != null && delta.reasoningContent.length > 0) {
+ base.reasoningContent = `${base.reasoningContent ?? ""}${delta.reasoningContent}`;
+ }
+
+ if (delta.refusal !== undefined) {
+ base.refusal = delta.refusal;
+ }
+
+ if (delta.finishReason !== undefined) {
+ base.finishReason = delta.finishReason;
+ }
+
+ if (delta.usage !== undefined) {
+ base.usage = delta.usage;
+ }
+
+ if (delta.toolCalls != null && delta.toolCalls.length > 0) {
+ if (base.toolCalls == null) {
+ base.toolCalls = [];
+ }
+ for (const deltaToolCall of delta.toolCalls) {
+ mergeToolCallDelta(base.toolCalls, deltaToolCall);
+ }
+ }
+}
+
+function mergeToolCallDelta(
+ toolCalls: TrueForge.ToolCall[],
+ deltaToolCall: TrueForge.ExtendedChunkDeltaToolCall,
+): void {
+ const { index } = deltaToolCall;
+ const existing = toolCalls[index];
+
+ if (existing !== undefined) {
+ if (deltaToolCall.id !== undefined) {
+ existing.id = deltaToolCall.id;
+ }
+ if (deltaToolCall.toolInfo !== undefined) {
+ existing.toolInfo = deltaToolCall.toolInfo;
+ }
+ if (deltaToolCall.providerSpecificFields !== undefined) {
+ existing.providerSpecificFields = deltaToolCall.providerSpecificFields;
+ }
+ if (deltaToolCall.function !== undefined) {
+ if (deltaToolCall.function.name !== undefined) {
+ existing.function.name = deltaToolCall.function.name;
+ }
+ if (deltaToolCall.function.arguments !== undefined) {
+ existing.function.arguments += deltaToolCall.function.arguments;
+ }
+ }
+ return;
+ }
+
+ // Only append sequentially — sparse / out-of-order indexes are ignored until
+ // earlier slots exist (streaming tool calls are emitted in index order).
+ if (index !== toolCalls.length) {
+ return;
+ }
+
+ const id = deltaToolCall.id;
+ const name = deltaToolCall.function?.name;
+ const toolInfo = deltaToolCall.toolInfo;
+ if (id === undefined || name === undefined || toolInfo === undefined) {
+ return;
+ }
+
+ const created: TrueForge.ToolCall = {
+ id,
+ type: "function",
+ function: {
+ name,
+ arguments: deltaToolCall.function?.arguments ?? "",
+ },
+ toolInfo,
+ };
+ if (deltaToolCall.providerSpecificFields !== undefined) {
+ created.providerSpecificFields = deltaToolCall.providerSpecificFields;
+ }
+ toolCalls.push(created);
+}
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
index 30bb55d8c..cadc6846d 100644
--- a/packages/sdk/src/index.ts
+++ b/packages/sdk/src/index.ts
@@ -2,5 +2,6 @@ export * as TrueForgeApi from "./api/index.js";
export type { BaseClientOptions, BaseRequestOptions } from "./BaseClient.js";
export { TrueForge } from "./Client.js";
export * from "./errors/index.js";
+export { isEventDelta, mergeEventDelta } from "./events.js";
export * from "./exports.js";
export * as serialization from "./serialization/index.js";
diff --git a/packages/sdk/tests/unit/events.test.ts b/packages/sdk/tests/unit/events.test.ts
new file mode 100644
index 000000000..32f8015b2
--- /dev/null
+++ b/packages/sdk/tests/unit/events.test.ts
@@ -0,0 +1,164 @@
+import type * as TrueForge from "../../src/api/index";
+import { isEventDelta, mergeEventDelta } from "../../src/events";
+
+function baseMessage(overrides: Partial<TrueForge.ModelMessageEvent> = {}): TrueForge.ModelMessageEvent {
+ return {
+ type: "model.message",
+ id: "msg-1",
+ threadId: "main",
+ createdAt: "2026-06-24T10:00:00Z",
+ content: "",
+ ...overrides,
+ };
+}
+
+function delta(overrides: Partial<TrueForge.ModelMessageDeltaEvent> = {}): TrueForge.ModelMessageDeltaEvent {
+ return {
+ type: "model.message.delta",
+ id: "msg-1",
+ threadId: "main",
+ ...overrides,
+ };
+}
+
+describe("isEventDelta", () => {
+ it("returns true for model.message.delta", () => {
+ expect(isEventDelta(delta())).toBe(true);
+ });
+
+ it("returns false for other event types", () => {
+ expect(isEventDelta(baseMessage())).toBe(false);
+ expect(isEventDelta({ type: "turn.done" })).toBe(false);
+ });
+});
+
+describe("mergeEventDelta", () => {
+ it("appends content and reasoningContent", () => {
+ const base = baseMessage({ content: "Hel", reasoningContent: "think" });
+ mergeEventDelta(base, delta({ content: "lo", reasoningContent: "ing" }));
+ expect(base.content).toBe("Hello");
+ expect(base.reasoningContent).toBe("thinking");
+ });
+
+ it("treats null/undefined content as empty string when appending", () => {
+ const base = baseMessage({ content: null });
+ mergeEventDelta(base, delta({ content: "Hi" }));
+ expect(base.content).toBe("Hi");
+ });
+
+ it("does not append string content onto array content", () => {
+ const parts: TrueForge.ModelMessageEventContentOneItem[] = [{ type: "text", text: "x" }];
+ const base = baseMessage({ content: parts });
+ mergeEventDelta(base, delta({ content: "y" }));
+ expect(base.content).toBe(parts);
+ });
+
+ it("overwrites finishReason, usage, and refusal", () => {
+ const base = baseMessage({
+ finishReason: null,
+ refusal: null,
+ });
+ const usage: TrueForge.ModelMessageUsage = {
+ inputTokens: 1,
+ outputTokens: 2,
+ inputTokensBreakdown: {
+ harness: 0,
+ instructions: 0,
+ messages: 1,
+ skills: 0,
+ toolDefinitions: 0,
+ },
+ };
+ mergeEventDelta(
+ base,
+ delta({
+ finishReason: "stop",
+ refusal: "nope",
+ usage,
+ }),
+ );
+ expect(base.finishReason).toBe("stop");
+ expect(base.refusal).toBe("nope");
+ expect(base.usage).toEqual(usage);
+ });
+
+ it("merges tool call fragments by index", () => {
+ const base = baseMessage();
+ const toolInfo: TrueForge.McpToolInfo = {
+ type: "mcp",
+ name: "get_order",
+ serverId: "orders-api",
+ serverName: "orders-api",
+ };
+
+ mergeEventDelta(
+ base,
+ delta({
+ toolCalls: [
+ {
+ index: 0,
+ id: "call-1",
+ type: "function",
+ function: { name: "get_order", arguments: "" },
+ toolInfo,
+ },
+ ],
+ }),
+ );
+ mergeEventDelta(
+ base,
+ delta({
+ toolCalls: [
+ {
+ index: 0,
+ function: { arguments: '{"order_id":' },
+ },
+ ],
+ }),
+ );
+ mergeEventDelta(
+ base,
+ delta({
+ toolCalls: [
+ {
+ index: 0,
+ function: { arguments: '"ORD-2031"}' },
+ },
+ ],
+ }),
+ );
+
+ expect(base.toolCalls).toEqual([
+ {
+ id: "call-1",
+ type: "function",
+ function: { name: "get_order", arguments: '{"order_id":"ORD-2031"}' },
+ toolInfo,
+ },
+ ]);
+ });
+
+ it("no-ops when ids do not match", () => {
+ const base = baseMessage({ content: "keep" });
+ mergeEventDelta(base, delta({ id: "other", content: "x" }));
+ expect(base.content).toBe("keep");
+ });
+
+ it("no-ops when base is not a model.message", () => {
+ const turnDone: TrueForge.TurnDoneEvent = {
+ type: "turn.done",
+ id: "msg-1",
+ threadId: null,
+ createdAt: "2026-06-24T10:00:00Z",
+ state: { status: "done", output: null, requiredActions: [], completedAt: "2026-06-24T10:00:00Z" },
+ };
+ mergeEventDelta(turnDone, delta({ content: "x" }));
+ expect(turnDone).toEqual({
+ type: "turn.done",
+ id: "msg-1",
+ threadId: null,
+ createdAt: "2026-06-24T10:00:00Z",
+ state: { status: "done", output: null, requiredActions: [], completedAt: "2026-06-24T10:00:00Z" },
+ });
+ });
+});