Skip to content

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

51.8 KB
Raw Blame
---
title: 'Use an agent'
sidebarTitle: 'Use an agent'
description: 'Run a saved agent with the TypeScript or Python SDK: a Quick Start, then recipes for streaming, approvals, questions, threads, and reconnects.'
---

The recipe book for running an agent with [`@truefoundry/trueforge-sdk`](https://www.npmjs.com/package/@truefoundry/trueforge-sdk) or [`trueforge-sdk`](https://pypi.org/project/trueforge-sdk/). New here? Install and stream your first turn in the [SDK Quickstart](/api/quickstart) first. For the mental model (Agent → Session → Turn → Event → Delta), see [Concepts](/api/overview); for every event field, see the [turn events reference](#turn-events-reference) at the bottom of this page.

<Note>
Prerequisite: a named agent in the registry, or an inline [agent spec](/create-agent/overview#create-an-agent-via-the-api) you pass when creating the session. The examples below run the **`web-research-brief`** agent from the [Quickstart](/quickstart); build it there first, or swap in your own agent name / inline spec.
</Note>

Every snippet is self-contained and runnable. They all use the `client` from [Install and connect](#install-and-connect).

## Install and connect

<CodeGroup>
```bash TypeScript wrap
npm i @truefoundry/trueforge-sdk
```

```bash Python wrap
pip install trueforge-sdk
```
</CodeGroup>

<CodeGroup>
```typescript TypeScript wrap
import { TrueForge } from '@truefoundry/trueforge-sdk';

const client = new TrueForge({
  baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
  timeoutInSeconds: 600, // raise for long-running SSE turns (default 60s)
  // token: process.env.TRUEFORGE_TOKEN, // ID token when OIDC login is enabled
});
```

```python Python wrap
import os
from trueforge_sdk import TrueForge

client = TrueForge(
    base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"),
    timeout=600,  # raise for long-running SSE turns (default 60s)
    # token=os.environ.get("TRUEFORGE_TOKEN"),  # ID token when OIDC login is enabled
)
```
</CodeGroup>

Point `baseUrl` / `base_url` at your running TrueForge server; `http://localhost:8790` is the Quickstart default. When [OIDC login](/authentication/overview) is enabled, pass `token` (an ID token from your IdP; see [Get a token and connect](/api/quickstart#get-a-token-and-connect)). When login is off, omit it. TypeScript fields are camelCase; Python fields match the wire format (`snake_case`).

## Quick Start

The [Concepts](/api/overview) page explains the model with a conceptual `support-bot`; here is a real agent you can run. In the [Quickstart](/quickstart) you built **`web-research-brief`**, an agent with Exa web search and the web-artifacts-builder skill. Here it is from the SDK: open a session on that agent, stream one research turn, and print the brief as it arrives. It fans out to [subagents](/key-features/subagents), so you'll see their threads in the same stream. It has no approval gate, so it runs end to end without pausing; for the approval and question pauses, see [Handle pauses](#handle-pauses).

<CodeGroup>
```typescript TypeScript wrap
import { TrueForge } from '@truefoundry/trueforge-sdk';

const client = new TrueForge({
  baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790',
  timeoutInSeconds: 600,
});

// The agent you saved in the Quickstart.
const { data: session } = await client.sessions.create({ agent: { name: 'web-research-brief' } });

const stream = await client.sessions.createTurnStream(session.id, {
  input: [
    {
      type: 'user.message',
      content:
        'Compare Qdrant, Weaviate, and Milvus on performance, features, and licensing, then write a one-page brief with sources.',
    },
  ],
});

for await (const { data: event } of stream.withMetadata()) {
  if (event.type === 'thread.created') console.log(`\n↳ subagent: ${event.title}`);
  if (event.type === 'model.message.delta' && event.threadId === 'main') {
    process.stdout.write(event.content ?? ''); // the root agent's reply, streaming in
  }
  if (event.type === 'turn.done' && event.state.status === 'done') {
    console.log('\n\n--- brief ---\n', event.state.output?.content ?? '');
  }
}
```

```python Python wrap
import os
from trueforge_sdk import TrueForge

client = TrueForge(
    base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"),
    timeout=600,
)

# The agent you saved in the Quickstart.
session = client.sessions.create(agent={"name": "web-research-brief"})

stream = client.sessions.create_turn_stream(
    session_id=session.data.id,
    input=[
        {
            "type": "user.message",
            "content": "Compare Qdrant, Weaviate, and Milvus on performance, features, and licensing, then write a one-page brief with sources.",
        },
    ],
)

for event in stream:
    if event.type == "thread.created":
        print(f"\n↳ subagent: {event.title}")
    if event.type == "model.message.delta" and event.thread_id == "main":
        print(event.content or "", end="", flush=True)
    if event.type == "turn.done" and event.state.status == "done":
        output = event.state.output
        print("\n\n--- brief ---\n", None if output is None else output.content)
```
</CodeGroup>

That's the core loop: open a session, stream a turn, print the reply as it arrives, and read the final `turn.done`. This version writes each delta straight to stdout. The [next section](#create-and-stream-a-turn) keeps an id-keyed event index, the pattern the pause recipes build on. The rest of the page is a reference for each piece, plus the pauses (approvals, questions, MCP auth) a real agent runs into.

## Sessions

A **session** is the conversation context for one issue; it persists across 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

<CodeGroup>
```typescript TypeScript wrap
import { TrueForge } from '@truefoundry/trueforge-sdk';

const client = new TrueForge({ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790' });

// By saved agent name:
const { data: session } = await client.sessions.create({ agent: { name: 'web-research-brief' } });

// …or with an inline spec (no saved agent needed):
const { data: inlineSession } = await client.sessions.create({
  agent: {
    spec: {
      model: { name: 'anthropic/claude-sonnet-4-6' },
      instructions: 'You are a concise research assistant.',
    },
  },
});
```

```python Python wrap
import os
from trueforge_sdk import TrueForge

client = TrueForge(base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"))

# By saved agent name:
session = client.sessions.create(agent={"name": "web-research-brief"})

# …or with an inline spec (no saved agent needed):
inline_session = client.sessions.create(
    agent={
        "spec": {
            "model": {"name": "anthropic/claude-sonnet-4-6"},
            "instructions": "You are a concise research assistant.",
        },
    },
)
```
</CodeGroup>

### List sessions

Newest-first; filter with `agentId` / `agent_id`. TypeScript returns a `Page` async iterable; Python returns a `SyncPager`. Both auto-paginate.

<CodeGroup>
```typescript TypeScript wrap
import { TrueForge } from '@truefoundry/trueforge-sdk';

const client = new TrueForge({ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790' });

for await (const session of await client.sessions.list()) {
  console.log(session.id, session.createdAt);
}
```

```python Python wrap
import os
from trueforge_sdk import TrueForge

client = TrueForge(base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"))

for session in client.sessions.list():
    print(session.id, session.created_at)
```
</CodeGroup>

## Turns

A **turn** is one request/response cycle: send input, the agent runs until it finishes or pauses, then the stream closes. Turns chain automatically (`previousTurnId` defaults to `"auto"`), so you never resend history.

<Note>
Creating a new turn in a session automatically cancels any turn still running in that session.
</Note>

### Create and stream a turn

`createTurnStream` / `create_turn_stream` returns a stream of [turn events](#turn-events-reference). `stream.withMetadata()` / `stream.with_metadata()` yields `{ data, id }` (TypeScript) or `StreamEvent` (Python: `.data`, `.id`), where `data` is the parsed event and `id` is the per-stream sequence number used to [resume after a disconnect](#resume-a-stream). The stream opens with `turn.created` and closes with `turn.done`; read the terminal result from `turn.done.state`.

Keep an **`id`-keyed event index**. Model output streams as an empty `model.message` base followed by `model.message.delta` fragments that share the base's `id`. Store each non-delta event under its `id` and merge each delta into the base with TypeScript `isEventDelta` / `mergeEventDelta` or Python `is_event_delta` / `merge_event_delta` (`from trueforge_sdk.events import …`). (Deltas appear only while streaming; [`listTurnEvents`](#replay-a-finished-turn) / `list_turn_events` returns them already merged.) Pause handlers and the per-thread index below reuse this pattern.

<CodeGroup>
```typescript TypeScript wrap
import { TrueForge, TrueForgeApi, isEventDelta, mergeEventDelta } from '@truefoundry/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: 'web-research-brief' } });

const events = new Map<string, TrueForgeApi.TurnStreamingEvent>();
let turnId: string | undefined;
let lastSequenceNumber = 0;

const stream = await client.sessions.createTurnStream(session.id, {
  input: [{ type: 'user.message', content: 'Summarize the current state of open-source vector databases.' }],
});
for await (const { data: event, id } of stream.withMetadata()) {
  if (id != null) lastSequenceNumber = Number(id);
  if (event.type === 'turn.created') turnId = event.turnId;
  if (isEventDelta(event)) {
    const base = events.get(event.id);
    if (base) mergeEventDelta(base, event);
  } else {
    events.set(event.id, event);
  }
  if (event.type === 'turn.done') console.log('status:', event.state.status);
}
```

```python Python wrap
import os
from trueforge_sdk import TrueForge
from trueforge_sdk.events import is_event_delta, merge_event_delta

client = TrueForge(
    base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"),
    timeout=600,
)
session = client.sessions.create(agent={"name": "web-research-brief"})

events = {}
turn_id = None
last_sequence_number = 0

stream = client.sessions.create_turn_stream(
    session_id=session.data.id,
    input=[{"type": "user.message", "content": "Summarize the current state of open-source vector databases."}],
)
for meta in stream.with_metadata():
    event = meta.data
    if meta.id is not None:
        last_sequence_number = int(meta.id)
    if event.type == "turn.created":
        turn_id = event.turn_id
    if is_event_delta(event):
        base = events.get(event.id)
        if base is not None:
            merge_event_delta(base, event)
    else:
        events[event.id] = event
    if event.type == "turn.done":
        print("status:", event.state.status)
```
</CodeGroup>

Turn `input` accepts three item types (a single turn can't mix a `user.message` with approval or response items):

| `type` | Purpose |
| --- | --- |
| `user.message` | A message. `content` is a string, or an array of `text` / `file` parts (files as data URIs). |
| `user.tool_approval` | An [approval decision](/create-agent/overview#what’s-in-an-agent) for a paused tool call. |
| `user.tool_response` | An [answer](/create-agent/overview#what’s-in-an-agent) for a paused client-side tool call. |

### Non-streaming turn

If you don't need live events, TypeScript `sessions.createTurn` (`stream: false`) and Python `sessions.create_turn` return immediately with `state.status: "running"` and run in the background. Poll `getTurn` / `get_turn` until the status is terminal (`done`, `cancelled`, `error`).

<CodeGroup>
```typescript TypeScript wrap
import { TrueForge } from '@truefoundry/trueforge-sdk';

const client = new TrueForge({ baseUrl: process.env.TRUEFORGE_BASE_URL ?? 'http://localhost:8790' });
const { data: session } = await client.sessions.create({ agent: { name: 'web-research-brief' } });

const { data: created } = await client.sessions.createTurn(session.id, {
  input: [{ type: 'user.message', content: 'Give me a one-paragraph summary of the Qdrant licensing model.' }],
});

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));
}
console.log(turn.state); // done → state.output / required_actions; else reason / message
```

```python Python wrap
import os
import time
from trueforge_sdk import TrueForge

client = TrueForge(base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"))
session = client.sessions.create(agent={"name": "web-research-brief"})

created = client.sessions.create_turn(
    session_id=session.data.id,
    input=[{"type": "user.message", "content": "Give me a one-paragraph summary of the Qdrant licensing model."}],
)

turn = created.data
while turn.state.status == "running":
    time.sleep(0.5)
    turn = client.sessions.get_turn(session_id=session.data.id, turn_id=created.data.id).data
print(turn.state)  # done → state.output / required_actions; else reason / message
```
</CodeGroup>

### List turns

Oldest-first; each turn exposes its `input` and `state`. A `done` turn's `state.requiredActions` / `state.required_actions` lists any pauses it surfaced.

<CodeGroup>
```typescript TypeScript wrap
import { TrueForge } from '@truefoundry/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.state.status);
  if (turn.state.status === 'done' && turn.state.output != null) {
    console.log(turn.state.output.content);
  }
}
```

```python Python wrap
import os
from trueforge_sdk import TrueForge

client = TrueForge(base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"))

for turn in client.sessions.list_turns(session_id="sess-abc123"):
    print(turn.id, turn.state.status)
    if turn.state.status == "done" and turn.state.output is not None:
        print(turn.state.output.content)
```
</CodeGroup>

### Attach images or files

A `user.message`'s `content` can be an array of parts: text plus one or more files as [data URIs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) (`data:<mime>;base64,<payload>`).

<CodeGroup>
```typescript TypeScript wrap
import { readFileSync } from 'node:fs';
import { TrueForge } from '@truefoundry/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: 'web-research-brief' } });

const toDataUri = (path: string, mime: string) => `data:${mime};base64,${readFileSync(path).toString('base64')}`;

const stream = await client.sessions.createTurnStream(session.id, {
  input: [
    {
      type: 'user.message',
      content: [
        { type: 'text', text: 'Use this chart in the brief.' },
        { type: 'file', name: 'benchmarks.png', data: toDataUri('benchmarks.png', 'image/png') },
      ],
    },
  ],
});
for await (const { data: event } of stream.withMetadata()) console.log(event.type);
```

```python Python wrap
import base64
import os
from pathlib import Path
from trueforge_sdk import TrueForge

client = TrueForge(
    base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"),
    timeout=600,
)
session = client.sessions.create(agent={"name": "web-research-brief"})

def to_data_uri(path: str, mime: str) -> str:
    payload = base64.b64encode(Path(path).read_bytes()).decode("ascii")
    return f"data:{mime};base64,{payload}"

stream = client.sessions.create_turn_stream(
    session_id=session.data.id,
    input=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "Use this chart in the brief."},
                {"type": "file", "name": "benchmarks.png", "data": to_data_uri("benchmarks.png", "image/png")},
            ],
        },
    ],
)
for event in stream:
    print(event.type)
```
</CodeGroup>

<Note>
Whether a file is understood depends on the agent's model, so send images only to a vision-capable model. Non-image files (e.g. PDFs) need the [sandbox](/sandbox) enabled on the agent; the harness uses it to process the document.
</Note>

### Cancel a turn

`sessions.cancel(sessionId)` / `sessions.cancel(session_id=…)` stops the running turn: it aborts the in-flight model request, waits for running MCP tool calls to finish, and force-stops any sandbox the turn provisioned. It's idempotent, and the backend closes the SSE stream gracefully (a terminal `turn.done`, then it ends, so don't `break`). Continue by creating a new turn, which chains on the cancelled turn's history.

<CodeGroup>
```typescript TypeScript wrap
import { TrueForge } from '@truefoundry/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: 'web-research-brief' } });

const stream = await client.sessions.createTurnStream(session.id, {
  input: [{ type: 'user.message', content: 'Run a deep comparison across a dozen vector databases.' }],
});
let i = 0;
for await (const { data: event } of stream.withMetadata()) {
  if (i++ === 5) await client.sessions.cancel(session.id); // stream ends itself after the terminal turn.done
}
```

```python Python wrap
import os
from trueforge_sdk import TrueForge

client = TrueForge(
    base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"),
    timeout=600,
)
session = client.sessions.create(agent={"name": "web-research-brief"})

stream = client.sessions.create_turn_stream(
    session_id=session.data.id,
    input=[{"type": "user.message", "content": "Run a deep comparison across a dozen vector databases."}],
)
i = 0
for event in stream:
    if i == 5:
        client.sessions.cancel(session_id=session.data.id)  # stream ends itself after the terminal turn.done
    i += 1
```
</CodeGroup>

## Handle pauses

A turn ends **paused** when it needs something from you. Each pause populates `turn.done.state.requiredActions`; you resume by creating a **new turn** with the matching response item(s). A single turn can surface more than one pending item (e.g. parallel threads each hit a gate), so collect them all.

For approvals and questions, each pending ref carries the `sourceEventId` of the [`model.message`](#model-message) that made the call. Look it up in the [event index](#create-and-stream-a-turn) to read the tool's name and arguments.

<Note>
`web-research-brief` won't pause on its own; it has no gated tool or clarifying-question step. The snippets below are **illustrative**: point them at an agent that has a `require_approval_for_tools` tool, uses `ask_user_question`, or connects to an MCP server needing OAuth.
</Note>

### Tool approvals

A gated tool ([human approval](/create-agent/overview#what’s-in-an-agent)) emits [`tool.approval_required`](#tool-approval-required). Collect the pending events while streaming, then resume with one `user.tool_approval` per pending call, either allowing it or denying it with a reason. Look up each ref in the [event index](#create-and-stream-a-turn).

<CodeGroup>
```typescript TypeScript wrap
import { TrueForge, TrueForgeApi, isEventDelta, mergeEventDelta } from '@truefoundry/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: 'ops-bot' } });

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: event } of stream.withMetadata()) {
  if (isEventDelta(event)) {
    const base = events.get(event.id);
    if (base) mergeEventDelta(base, event);
  } else {
    events.set(event.id, event);
  }
  if (event.type === 'tool.approval_required') pendingApprovals.push(event);
}

const approvals: TrueForgeApi.UserToolApprovalEvent[] = [];
for (const pending of pendingApprovals) {
  for (const ref of pending.toolCalls) {
    const msg = events.get(ref.sourceEventId);
    if (msg?.type !== 'model.message') continue;
    const call = msg.toolCalls?.find((tc) => tc.id === ref.id);
    if (!call) continue;
    console.log(`approve ${call.toolInfo.name}? args: ${call.function.arguments}`);
    approvals.push({
      type: 'user.tool_approval',
      threadId: pending.threadId,
      toolCallId: ref.id,
      approval: { status: 'allow' }, // or { 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.type);
```

```python Python wrap
import os
from trueforge_sdk import TrueForge
from trueforge_sdk.events import is_event_delta, merge_event_delta

client = TrueForge(
    base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"),
    timeout=600,
)
session = client.sessions.create(agent={"name": "ops-bot"})

events = {}
pending_approvals = []

stream = client.sessions.create_turn_stream(
    session_id=session.data.id,
    input=[{"type": "user.message", "content": "Restart the billing service."}],
)
for event in stream:
    if is_event_delta(event):
        base = events.get(event.id)
        if base is not None:
            merge_event_delta(base, event)
    else:
        events[event.id] = event
    if event.type == "tool.approval_required":
        pending_approvals.append(event)

approvals = []
for pending in pending_approvals:
    for ref in pending.tool_calls:
        msg = events.get(ref.source_event_id)
        if msg is None or msg.type != "model.message":
            continue
        call = next((tc for tc in (msg.tool_calls or []) if tc.id == ref.id), None)
        if call is None:
            continue
        print(f"approve {call.tool_info.name}? args: {call.function.arguments}")
        approvals.append(
            {
                "type": "user.tool_approval",
                "thread_id": pending.thread_id,
                "tool_call_id": ref.id,
                "approval": {"status": "allow"},  # or {"status": "deny", "reason": "denied by user"}
            }
        )

resume = client.sessions.create_turn_stream(session_id=session.data.id, input=approvals)
for event in resume:
    print(event.type)
```
</CodeGroup>

### Agent questions

When the agent uses the built-in [`ask_user_question`](/create-agent/overview#what’s-in-an-agent) tool, it emits [`tool.response_required`](#tool-response-required); the pending call's `arguments` carry the `question` and `options`. Resume with one `user.tool_response` per pending call.

<CodeGroup>
```typescript TypeScript wrap
import { TrueForge, TrueForgeApi, isEventDelta, mergeEventDelta } from '@truefoundry/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: 'ops-bot' } });

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: event } of stream.withMetadata()) {
  if (isEventDelta(event)) {
    const base = events.get(event.id);
    if (base) mergeEventDelta(base, event);
  } else {
    events.set(event.id, event);
  }
  if (event.type === 'tool.response_required') pendingQuestions.push(event);
}

const responses: TrueForgeApi.UserToolResponseEvent[] = [];
for (const pending of pendingQuestions) {
  for (const ref of pending.toolCalls) {
    const msg = events.get(ref.sourceEventId);
    if (msg?.type !== 'model.message') continue;
    const call = msg.toolCalls?.find((tc) => tc.id === ref.id);
    // tool.response_required covers any client-side tool; handle ask_user_question here.
    if (call?.toolInfo.type !== 'truefoundry-system' || call.toolInfo.name !== 'ask_user_question') continue;
    const { question, options } = JSON.parse(call.function.arguments || '{}') as { question?: string; options?: string[] };
    console.log(question, options);
    responses.push({
      type: 'user.tool_response',
      threadId: pending.threadId,
      toolCallId: ref.id,
      content: 'the chosen option, or any text', // free-form answer
    });
  }
}

const resume = await client.sessions.createTurnStream(session.id, { input: responses });
for await (const { data: event } of resume.withMetadata()) console.log(event.type);
```

```python Python wrap
import json
import os
from trueforge_sdk import TrueForge
from trueforge_sdk.events import is_event_delta, merge_event_delta

client = TrueForge(
    base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"),
    timeout=600,
)
session = client.sessions.create(agent={"name": "ops-bot"})

events = {}
pending_questions = []

stream = client.sessions.create_turn_stream(
    session_id=session.data.id,
    input=[{"type": "user.message", "content": "Create a new environment called testing-1."}],
)
for event in stream:
    if is_event_delta(event):
        base = events.get(event.id)
        if base is not None:
            merge_event_delta(base, event)
    else:
        events[event.id] = event
    if event.type == "tool.response_required":
        pending_questions.append(event)

responses = []
for pending in pending_questions:
    for ref in pending.tool_calls:
        msg = events.get(ref.source_event_id)
        if msg is None or msg.type != "model.message":
            continue
        call = next((tc for tc in (msg.tool_calls or []) if tc.id == ref.id), None)
        if call is None:
            continue
        # tool.response_required covers any client-side tool; handle ask_user_question here.
        if call.tool_info.type != "truefoundry-system" or call.tool_info.name != "ask_user_question":
            continue
        payload = json.loads(call.function.arguments or "{}")
        print(payload.get("question"), payload.get("options"))
        responses.append(
            {
                "type": "user.tool_response",
                "thread_id": pending.thread_id,
                "tool_call_id": ref.id,
                "content": "the chosen option, or any text",
            }
        )

resume = client.sessions.create_turn_stream(session_id=session.data.id, input=responses)
for event in resume:
    print(event.type)
```
</CodeGroup>

### MCP outbound auth

When a tool needs a server's OAuth, the turn ends with [`mcp.auth_required`](#mcp-auth-required), listing each server and its `authUrl`. Send the user there, then resume. See [In-chat authentication](/mcp-servers#in-chat-authentication).

<Note>
After `mcp.auth_required`, the resuming turn must **not** include a `user.message`; resume with empty `input` (or omit it).
</Note>

<CodeGroup>
```typescript TypeScript wrap
import { TrueForge, TrueForgeApi } from '@truefoundry/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: 'github-bot' } });

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()) {
  if (event.type === 'mcp.auth_required') pendingAuth = event;
}

if (pendingAuth != null) {
  for (const server of pendingAuth.mcpServers) {
    console.log(`Authorize ${server.name}: ${server.authUrl}`);
  }
  // …wait for the user to authorize the server(s)…
}

// Resume with empty input; 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.type);
```

```python Python wrap
import os
from trueforge_sdk import TrueForge

client = TrueForge(
    base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"),
    timeout=600,
)
session = client.sessions.create(agent={"name": "github-bot"})

pending_auth = None
stream = client.sessions.create_turn_stream(
    session_id=session.data.id,
    input=[{"type": "user.message", "content": "Summarize my latest GitHub issues."}],
)
for event in stream:
    if event.type == "mcp.auth_required":
        pending_auth = event

if pending_auth is not None:
    for server in pending_auth.mcp_servers:
        print(f"Authorize {server.name}: {server.auth_url}")
    # …wait for the user to authorize the server(s)…

# Resume with empty input; the agent continues the interrupted work.
resume = client.sessions.create_turn_stream(session_id=session.data.id)
for event in resume:
    print(event.type)
```
</CodeGroup>

## Resilience and threads

### Resume a stream

If you lose the `createTurnStream` / `create_turn_stream` connection (e.g. a process restart), persist `session.id`, `turnId` / `turn_id`, and `lastSequenceNumber` / `last_sequence_number`. To resume: call `getTurn` / `get_turn` → if still `running`, reconnect with `subscribeToTurn` / `subscribe_to_turn` and `afterSequenceNumber` / `after_sequence_number` to skip events you already saw; if finished, rebuild from `listTurnEvents` / `list_turn_events`.

<CodeGroup>
```typescript TypeScript wrap
import { TrueForge, TrueForgeApi, isEventDelta, mergeEventDelta } from '@truefoundry/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: 'web-research-brief' } });

const events = new Map<string, TrueForgeApi.TurnStreamingEvent>();
let turnId: string | undefined;
let lastSequenceNumber = 0;

const stream = await client.sessions.createTurnStream(session.id, {
  input: [{ type: 'user.message', content: 'Compare Qdrant, Weaviate, and Milvus.' }],
});
for await (const { data: event, id } of stream.withMetadata()) {
  if (id != null) lastSequenceNumber = Number(id);
  if (event.type === 'turn.created') turnId = event.turnId;
  if (isEventDelta(event)) {
    const base = events.get(event.id);
    if (base) mergeEventDelta(base, event);
  } else {
    events.set(event.id, event);
  }
}

// …after a disconnect, with session.id / turnId / lastSequenceNumber restored:
const { data: turn } = await client.sessions.getTurn(session.id, turnId!);
if (turn.state.status === 'running') {
  const resume = await client.sessions.subscribeToTurn(
    session.id,
    turnId!,
    { afterSequenceNumber: lastSequenceNumber },
    { timeoutInSeconds: 600 },
  );
  for await (const { data: event, id } of resume.withMetadata()) {
    if (id != null) lastSequenceNumber = Number(id);
    if (isEventDelta(event)) {
      const base = events.get(event.id);
      if (base) mergeEventDelta(base, event);
    } else {
      events.set(event.id, event);
    }
  }
} else {
  // Already finished: rebuild from the stored log (deltas already merged).
  for await (const event of await client.sessions.listTurnEvents(session.id, turnId!)) {
    events.set(event.id, event);
  }
}
```

```python Python wrap
import os
from trueforge_sdk import TrueForge
from trueforge_sdk.events import is_event_delta, merge_event_delta

client = TrueForge(
    base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"),
    timeout=600,
)
session = client.sessions.create(agent={"name": "web-research-brief"})

events = {}
turn_id = None
last_sequence_number = 0

stream = client.sessions.create_turn_stream(
    session_id=session.data.id,
    input=[{"type": "user.message", "content": "Compare Qdrant, Weaviate, and Milvus."}],
)
for meta in stream.with_metadata():
    event = meta.data
    if meta.id is not None:
        last_sequence_number = int(meta.id)
    if event.type == "turn.created":
        turn_id = event.turn_id
    if is_event_delta(event):
        base = events.get(event.id)
        if base is not None:
            merge_event_delta(base, event)
    else:
        events[event.id] = event

# …after a disconnect, with session.id / turn_id / last_sequence_number restored:
turn = client.sessions.get_turn(session_id=session.data.id, turn_id=turn_id).data
if turn.state.status == "running":
    resume = client.sessions.subscribe_to_turn(
        session_id=session.data.id,
        turn_id=turn_id,
        after_sequence_number=last_sequence_number,
        request_options={"timeout": 600},
    )
    for meta in resume.with_metadata():
        event = meta.data
        if meta.id is not None:
            last_sequence_number = int(meta.id)
        if is_event_delta(event):
            base = events.get(event.id)
            if base is not None:
                merge_event_delta(base, event)
        else:
            events[event.id] = event
else:
    # Already finished: rebuild from the stored log (deltas already merged).
    for event in client.sessions.list_turn_events(session_id=session.data.id, turn_id=turn_id):
        events[event.id] = event
```
</CodeGroup>

<Tip>
`createTurn` / `create_turn` + `subscribeToTurn` / `subscribe_to_turn` is resilient: the SDK reconnects with `Last-Event-ID` on transient drops. Persist the sequence number from `.withMetadata()` / `.with_metadata()` so you can call `subscribeToTurn({ afterSequenceNumber })` / `subscribe_to_turn(..., after_sequence_number=…)` again after a restart.
</Tip>

### Subagent threads

A turn stream interleaves the root agent and any parallel [subagents](/key-features/subagents), exactly what the [Quick Start](#quick-start) above does. Every event carries a `threadId` / `thread_id`:

- `"main"`: the root agent.
- A unique id: a subagent thread. [`thread.created`](#thread-created) and [`thread.done`](#thread-done) bracket its lifecycle.
- `null`: a turn-level event, such as [`turn.created`](#turn-created), [`turn.done`](#turn-done), [`sandbox.created`](#sandbox-created), and [`mcp.auth_required`](#mcp-auth-required).

Keep a **per-thread** index (`Map<threadId, Map<id, event>>` in TypeScript; nested dicts in Python) and apply the same [event-index](#create-and-stream-a-turn) merge inside each thread's bucket.

```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
  Main-->>Client: model.message + deltas
  Main->>Research: spawn sub-agent
  Main-->>Client: thread.created
  Research-->>Client: model.message + deltas
  Research->>Main: sub-agent completes
  Main-->>Client: thread.done
  Main-->>Client: model.message + deltas
```

<CodeGroup>
```typescript TypeScript wrap
import { TrueForge, TrueForgeApi, isEventDelta, mergeEventDelta } from '@truefoundry/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: 'web-research-brief' } });

const threads = new Map<string, Map<string, TrueForgeApi.TurnStreamingEvent>>();

const stream = await client.sessions.createTurnStream(session.id, {
  input: [{ type: 'user.message', content: 'Compare Qdrant, Weaviate, and Milvus in parallel.' }],
});
for await (const { data: event } of stream.withMetadata()) {
  if (event.threadId == null) {
    console.log('turn-level event:', event.type);
    continue;
  }
  let bucket = threads.get(event.threadId);
  if (!bucket) threads.set(event.threadId, (bucket = new Map()));

  if (isEventDelta(event)) {
    const base = bucket.get(event.id);
    if (base) mergeEventDelta(base, event);
  } else {
    bucket.set(event.id, event);
  }
  if (event.type === 'thread.done') {
    console.log(`${event.threadId} done: ${event.title} (${bucket.size} events)`);
    threads.delete(event.threadId);
  }
}
```

```python Python wrap
import os
from trueforge_sdk import TrueForge
from trueforge_sdk.events import is_event_delta, merge_event_delta

client = TrueForge(
    base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"),
    timeout=600,
)
session = client.sessions.create(agent={"name": "web-research-brief"})

threads = {}

stream = client.sessions.create_turn_stream(
    session_id=session.data.id,
    input=[{"type": "user.message", "content": "Compare Qdrant, Weaviate, and Milvus in parallel."}],
)
for event in stream:
    if event.thread_id is None:
        print("turn-level event:", event.type)
        continue
    bucket = threads.setdefault(event.thread_id, {})
    if is_event_delta(event):
        base = bucket.get(event.id)
        if base is not None:
            merge_event_delta(base, event)
    else:
        bucket[event.id] = event
    if event.type == "thread.done":
        print(f"{event.thread_id} done: {event.title} ({len(bucket)} events)")
        del threads[event.thread_id]
```
</CodeGroup>

### Replay a finished turn

`sessions.listTurnEvents()` / `list_turn_events()` yields a finished turn's [events](#turn-events-reference) in order (auto-paginates; `order: "asc"` default, or `"desc"`). Events are **already merged**, so you can use each one directly.

<Note>
Only available for completed turns; a running turn has no stored log yet, so stream it with `createTurnStream` / `create_turn_stream` or `subscribeToTurn` / `subscribe_to_turn` instead.
</Note>

<CodeGroup>
```typescript TypeScript wrap
import { TrueForge } from '@truefoundry/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')) {
  if (turn.state.status === 'running') continue;
  for await (const event of await client.sessions.listTurnEvents('sess-abc123', turn.id, { order: 'asc' })) {
    console.log(event.type);
  }
}
```

```python Python wrap
import os
from trueforge_sdk import TrueForge

client = TrueForge(base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"))

for turn in client.sessions.list_turns(session_id="sess-abc123"):
    if turn.state.status == "running":
        continue
    for event in client.sessions.list_turn_events(session_id="sess-abc123", turn_id=turn.id, order="asc"):
        print(event.type)
```
</CodeGroup>

## Schedules

A **schedule** runs a saved agent on a recurring cadence, unattended. Each run sends the schedule's `task` to the agent and is recorded as a [session](/sessions). Manage them through `client.schedules`; the [Schedules guide](/schedules) covers the same feature in the UI.

### Create a schedule

<CodeGroup>
```typescript TypeScript
const { data: schedule } = await client.schedules.create({
  agentName: 'web-research-brief',
  name: 'morning-brief',
  manifest: {
    task: 'Summarize the most important AI news from the last 24 hours and list the top five items with links.',
    cron: '0 9 * * *', // 09:00 every day, evaluated in `timezone`
    timezone: 'Asia/Kolkata', // IANA time zone
    status: 'active', // or 'paused'
  },
});
```

```python Python
schedule = client.schedules.create(
    agent_name="web-research-brief",
    name="morning-brief",
    manifest={
        "task": "Summarize the most important AI news from the last 24 hours and list the top five items with links.",
        "cron": "0 9 * * *",  # 09:00 every day, evaluated in `timezone`
        "timezone": "Asia/Kolkata",  # IANA time zone
        "status": "active",  # or "paused"
    },
)
```
</CodeGroup>

The `cron` is a standard 5-field expression evaluated in `timezone`. The shortest interval is one hour.

### List, get, update, and delete

Update replaces the whole manifest, so pass every field you want to keep.

<CodeGroup>
```typescript TypeScript
for await (const schedule of await client.schedules.list()) {
  console.log(schedule.name, schedule.manifest.cron);
}

const { data: schedule } = await client.schedules.get('sched-abc123');

await client.schedules.update('sched-abc123', {
  name: 'morning-brief',
  manifest: {
    task: 'Summarize the most important AI news from the last 24 hours and list the top five items with links.',
    cron: '0 8 * * 1-5', // now weekdays at 08:00
    timezone: 'Asia/Kolkata',
    status: 'paused',
  },
});

await client.schedules.delete('sched-abc123');
```

```python Python
for schedule in client.schedules.list():
    print(schedule.name, schedule.manifest.cron)

schedule = client.schedules.get("sched-abc123").data

client.schedules.update(
    "sched-abc123",
    name="morning-brief",
    manifest={
        "task": "Summarize the most important AI news from the last 24 hours and list the top five items with links.",
        "cron": "0 8 * * 1-5",  # now weekdays at 08:00
        "timezone": "Asia/Kolkata",
        "status": "paused",
    },
)

client.schedules.delete("sched-abc123")
```
</CodeGroup>

### Runs

<CodeGroup>
```typescript TypeScript
// Trigger a run now, without waiting for the next scheduled time.
await client.schedules.createRun({ scheduleId: 'sched-abc123' });

// Review recent runs.
for await (const run of await client.schedules.listRuns('sched-abc123')) {
  console.log(run.scheduledFor, run.status); // 'scheduled' | 'triggered' | 'failed'
}
```

```python Python
# Trigger a run now, without waiting for the next scheduled time.
client.schedules.create_run(schedule_id="sched-abc123")

# Review recent runs.
for run in client.schedules.list_runs("sched-abc123"):
    print(run.scheduled_for, run.status)  # "scheduled" | "triggered" | "failed"
```
</CodeGroup>

Each run executes as a [session](/sessions), so open it there or through the session APIs above to read the transcript.

## Turn events reference

Field-level schemas for every event streamed while a turn runs. The recipes above link here for the exact shape of each event they handle.

<Note>
  Field names in this reference use the HTTP/JSON wire format (snake_case, e.g. `turn_id`, `source_event_id`). The Python SDK uses those same names. The TypeScript SDK returns the same fields camelCased (`turnId`, `sourceEventId`).
</Note>

Every event carries:

| Field        | Description                                                                                                                                                                                                        |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`       | The event type — one of the types below.                                                                                                                                                                           |
| `id`         | Unique event id (monotonic ULID — sortable by creation order).                                                                                                                                                     |
| `created_at` | ISO 8601 timestamp.                                                                                                                                                                                                |
| `thread_id`  | Which execution thread emitted it: `"main"` for the root agent, a generated id for [subagents](/key-features/subagents), or `null` for run-level events (`turn.*`, `sandbox.created`, `mcp.auth_required`). |

A stream always opens with `turn.created` and closes with `turn.done`. When you list persisted session events afterwards, you get the same events with deltas pre-merged into their `model.message`.

### Lifecycle events

#### `turn.created`

First event on every stream.

| Field              | Description                                               |
| ------------------ | --------------------------------------------------------- |
| `turn_id`          | Id of this turn.                                          |
| `previous_turn_id` | The turn this one chains from, or `null` for a root turn. |
| `input`            | The turn's input items, echoed back.                      |
| `state`            | `{ "status": "running" }`                                 |

#### `turn.done`

Last event on every stream. `state.status` is one of:

- **`done`** — carries `output` (the final `model.message`, or `null` when the turn ended paused), `required_actions` (pending `tool.approval_required` / `tool.response_required` / `mcp.auth_required` events, empty when none), `completed_at`, and optional `metrics`.
- **`cancelled`** — carries a `reason`: `client-cancelled`, `server-execution-timeout`, `cancelled-for-next-turn`, or `abandoned`.
- **`error`** — carries a `message`.

`metrics`, when present, aggregates the whole turn: `total_input_tokens`, `total_output_tokens`, `total_tokens`, `total_cache_read_tokens`, `total_cache_write_tokens`, `total_reasoning_tokens`, and `total_cost_in_usd`.

```json turn.done — paused for approval wrap
{
  "type": "turn.done",
  "id": "01jc...",
  "thread_id": null,
  "created_at": "2026-06-24T10:01:12Z",
  "state": {
    "status": "done",
    "output": null,
    "required_actions": [
      {
        "type": "tool.approval_required",
        "thread_id": "main",
        "tool_calls": [{ "id": "call-refund-01", "source_event_id": "msg-b2" }]
      }
    ],
    "completed_at": "2026-06-24T10:01:12Z",
    "metrics": { "total_tokens": 2451, "total_cost_in_usd": 0.011 }
  }
}
```

### Model output

#### `model.message`

An assistant message — text content and/or tool calls. On a live stream the base event arrives first and fills in via deltas; the merged event carries:

| Field           | Description                                                                                                                                                                                    |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content`       | Assistant text (may be empty when the message is only tool calls).                                                                                                                             |
| `tool_calls`    | Tool invocations, each with an `id` and `function` (`name`, `arguments`).                                                                                                                      |
| `finish_reason` | Why generation stopped (`stop`, `tool_calls`, ...), `null` mid-stream.                                                                                                                         |
| `usage`         | Token usage for this model call: `input_tokens`, `output_tokens`, optional cache counters, and `input_tokens_breakdown` (`harness`, `skills`, `instructions`, `tool_definitions`, `messages`). |

#### `model.message.delta`

An incremental fragment of a `model.message` — text and/or tool-call chunks. All deltas share the base event's `id`; append `content` chunks and merge tool-call fragments by index (`isEventDelta` / `mergeEventDelta` in TypeScript; `is_event_delta` / `merge_event_delta` from `trueforge_sdk.events` in Python). The most frequent event on a live stream. Not present when listing persisted events.

### Tool activity

#### `tool.response`

The result of a tool the harness executed, linked to its call by `tool_call_id`:

```json wrap
{
  "type": "tool.response",
  "id": "01jc...",
  "thread_id": "main",
  "tool_call_id": "call-get-order-01",
  "content": "{\"order_id\":\"ORD-2031\",\"status\":\"shipped\",\"total\":1240.0}",
  "created_at": "2026-06-24T10:00:04Z"
}
```

#### `tool.approval_required`

A tool call needs [human approval](/create-agent/overview#what’s-in-an-agent) before it can run. The turn ends after this event; resume with a `user.tool_approval` input.

| Field        | Description                                                                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tool_calls` | Pending calls: each `{ id, source_event_id }`, where `source_event_id` points at the `model.message` that contains the call's name and arguments. |

#### `tool.response_required`

A client-side tool (e.g. [`ask_user_question`](/create-agent/overview#what’s-in-an-agent)) needs a result from your app. Same shape as `tool.approval_required`; resume with a `user.tool_response` input.

### Subagent thread events

#### `thread.created`

A [subagent](/key-features/subagents) started. Subsequent events with this `thread_id` belong to it.

| Field        | Description                                                                            |
| ------------ | -------------------------------------------------------------------------------------- |
| `thread_id`  | The new thread's id.                                                                   |
| `title`      | Human-readable subagent name.                                                          |
| `parent`     | `{ thread_id, tool_call_id }` — the spawning thread and tool call.                     |
| `agent_info` | `{ type: "dynamic", name, input }` — the generated instructions the subagent received. |

#### `thread.done`

The subagent finished. `state` is `{ status: "done", output: <model.message> }` or `{ status: "error", error, output? }`. Does not close the turn stream — the root agent continues.

### Environment events

#### `mcp.initialize`

MCP server connections were initialized for a thread. `mcp_servers` lists each server: `{ id, name, session_id?, transport_type? }` (`streamable-http` or `sse`).

#### `mcp.auth_required`

One or more MCP servers need [OAuth authorization](/mcp-servers#in-chat-authentication) before the agent can proceed. `mcp_servers` lists `{ id, name, auth_url }` — send the user to `auth_url`, then start the next turn. The turn ends after this event.

#### `sandbox.created`

A [sandbox](/sandbox) was provisioned, carrying its `sandbox_id`. Emitted once per session — subsequent turns reuse the same sandbox and emit no new event.

### User input events

These are not streamed — they are the input items **you send** when creating a turn, listed here for completeness:

| Type                 | Fields                                                                                                                                   | Purpose                                    |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `user.message`       | `content` — string, or array of `{ type: "text", text }` / `{ type: "file", name, data }` parts (files as `data:<mime>;base64,...` URIs) | A user message.                            |
| `user.tool_approval` | `thread_id`, `tool_call_id`, `approval` — `{ status: "allow" }` or `{ status: "deny", reason? }`                                         | Decision for a paused tool call.           |
| `user.tool_response` | `thread_id`, `tool_call_id`, `content`                                                                                                   | Answer for a paused client-side tool call. |

A turn's `input` cannot mix `user.message` items with approval or tool-response items.