Use an agent

This guide covers everything you need to run a saved agent: open a session, send turns, consume the event stream, and handle pauses, threads, and disconnects.

Prerequisite: an agent saved in the Registry. See Create an agent or the Agent Playground. For the conceptual overview and a full walkthrough, see SDK overview.

Install and connect

Running agents uses the gateway SDK, not the truefoundry client.

pip install -U truefoundry-gateway-sdk

export TFY_GATEWAY_URL="https://<your-gateway-host>/<tenant>"
export TFY_API_KEY="<your-api-key>"

For TypeScript, install truefoundry-gateway-sdk from npm. Python examples use the sync TrueFoundryGateway client; see Create a client for AsyncTrueFoundryGateway. TypeScript uses TrueFoundryGateway with await / for await. Both call client.agents.sessions.*. Set TFY_GATEWAY_URL and TFY_API_KEY as above. Every example below comes in both languages. SSE streams return a Stream. Iterating yields typed event bodies. When you need the SSE id (for resume with after_sequence_number), use Python .with_metadata() or TypeScript .withMetadata() — each item exposes .id and .data — see Resume streaming.

Create a client

Construct a TrueFoundryGateway (Python sync or TypeScript) or AsyncTrueFoundryGateway (Python asyncio). Examples below use the sync client unless noted.

import os
from truefoundry_gateway_sdk import TrueFoundryGateway

client = TrueFoundryGateway(
    base_url=os.environ["TFY_GATEWAY_URL"],
    api_key=os.environ["TFY_API_KEY"],
)

import os
from truefoundry_gateway_sdk import AsyncTrueFoundryGateway

client = AsyncTrueFoundryGateway(
    base_url=os.environ["TFY_GATEWAY_URL"],
    api_key=os.environ["TFY_API_KEY"],
)

import { TrueFoundryGateway } from "truefoundry-gateway-sdk";

const client = new TrueFoundryGateway({
  apiKey: process.env.TFY_API_KEY!,
  baseUrl: process.env.TFY_GATEWAY_URL!,
});

Create a session

A session is the conversation context for a saved agent — one customer working through one issue. It persists across many turns; persist session.id to resume later.

Open a session

A Session is the conversation context for a saved agent. Create one by name with create / create. The response wraps the session in .data.

import os
from truefoundry_gateway_sdk import TrueFoundryGateway

# Use `truefoundry_gateway_sdk.AsyncTrueFoundryGateway` client for asyncio usage
client = TrueFoundryGateway(
    base_url=os.environ["TFY_GATEWAY_URL"],
    api_key=os.environ["TFY_API_KEY"],
)

response = client.agents.sessions.create(agent_name="support-bot")
session = response.data

import { TrueFoundryGateway } from "truefoundry-gateway-sdk";

const client = new TrueFoundryGateway({
  apiKey: process.env.TFY_API_KEY!,
  baseUrl: process.env.TFY_GATEWAY_URL!,
});

const { data: session } = await client.agents.sessions.create({ agentName: "support-bot" });

List sessions for an agent

List the existing sessions for a saved agent with list / list. It iterates newest-first and auto-paginates. Use it to resume an earlier conversation — each Session exposes its id (persist or reuse it to continue).

import os
from truefoundry_gateway_sdk import TrueFoundryGateway

client = TrueFoundryGateway(
    base_url=os.environ["TFY_GATEWAY_URL"],
    api_key=os.environ["TFY_API_KEY"],
)

for session in client.agents.sessions.list(agent_name="support-bot"):
    print("session id:", session.id)
    print("created at:", session.created_at)

import { TrueFoundryGateway } from "truefoundry-gateway-sdk";

const client = new TrueFoundryGateway({
  apiKey: process.env.TFY_API_KEY!,
  baseUrl: process.env.TFY_GATEWAY_URL!,
});

for await (const session of await client.agents.sessions.list({ agentName: "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.

Create and stream a turn

Start a turn with create_turn_stream / createTurnStream and iterate the returned SSE stream. The first event is always turn.created (carrying the turn_id); the stream closes with turn.done. When the stream runs to completion, read the terminal state from the final turn.done event (or refetch with get_turn). To continue the conversation, create another turn on the same session. Turns within a session are chained automatically, so each turn sees the history of the ones before it.

Creating a new turn in a session automatically cancels any other turn that is still running in that session.

import os
from truefoundry_gateway_sdk import TrueFoundryGateway, UserMessage
from truefoundry_gateway_sdk.agents import (
    TurnDoneEvent,
    TurnStateDone,
    TurnStateCancelled,
    TurnStateError,
)

client = TrueFoundryGateway(
    base_url=os.environ["TFY_GATEWAY_URL"],
    api_key=os.environ["TFY_API_KEY"],
)
response = client.agents.sessions.create(agent_name="support-bot")
session = response.data
# Each turn is one request/response cycle. create_turn_stream returns a Stream.
turn_state = None
stream = client.agents.sessions.create_turn_stream(
    session.id,
    input=[UserMessage(content="I would like to file a support ticket.")],
)
for event in stream:
    print(event)
    if isinstance(event, TurnDoneEvent):
        turn_state = event.state

if isinstance(turn_state, TurnStateDone):
    # output and required_actions are mutually exclusive: if output is present,
    # required_actions is empty, and vice versa.
    # output is the final assistant message, or None if the turn paused.
    if turn_state.output is not None:
        print(turn_state.output.content)
    # required_actions holds any pause events (tool.approval_required,
    # tool.response_required, mcp.auth_required).
    else:
        print("required actions:", turn_state.required_actions)
elif isinstance(turn_state, TurnStateCancelled):
    print("cancelled:", turn_state.reason)
elif isinstance(turn_state, TurnStateError):
    print("error:", turn_state.message)

print("completed at:", turn_state.completed_at)

# Create another turn on the same session. Turns are chained automatically,
# so this turn sees the history of the first one.
# Use with_metadata() when you need the SSE id (resume); otherwise iterate the Stream directly.
next_stream = client.agents.sessions.create_turn_stream(
    session.id,
    input=[UserMessage(content="Use my last order, ORD-2031.")],
)
for item in next_stream.with_metadata():
    print(item.id, item.data)

import { TrueFoundryGateway } from "truefoundry-gateway-sdk";

const client = new TrueFoundryGateway({
  apiKey: process.env.TFY_API_KEY!,
  baseUrl: process.env.TFY_GATEWAY_URL!,
});
const { data: session } = await client.agents.sessions.create({ agentName: "support-bot" });

// Each turn is one request/response cycle. createTurnStream returns a Stream.
let turnState;
const stream = await client.agents.sessions.createTurnStream(session.id, {
  input: [{ type: "user.message", content: "I would like to file a support ticket." }],
});
for await (const event of stream) {
  console.log(event);
  if (event.type === "turn.done") {
    turnState = event.state;
  }
}

if (turnState.status === "done") {
  // output and requiredActions are mutually exclusive: if output is present,
  // requiredActions is empty, and vice versa.
  // output is the final assistant message, or null if the turn paused.
  if (turnState.output != null) {
    console.log(turnState.output.content);
  // requiredActions holds any pause events (tool.approval_required,
  // tool.response_required, mcp.auth_required).
  } 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);
}

console.log("completed at:", turnState.completedAt);

// Create another turn on the same session. Turns are chained automatically,
// so this turn sees the history of the first one.
// Use withMetadata() when you need the SSE id (resume); otherwise iterate the Stream directly.
const nextStream = await client.agents.sessions.createTurnStream(session.id, {
  input: [{ type: "user.message", content: "Use my last order, ORD-2031." }],
});
for await (const item of nextStream.withMetadata()) {
  console.log(item.id, item.data);
}

List turns

List the turns in a session with list_turns / listTurns. Each turn exposes its input, and state holds the current lifecycle state.

list_turns() always returns turns in descending order (newest-first).

import os
from truefoundry_gateway_sdk import TrueFoundryGateway
from truefoundry_gateway_sdk.agents import (
    TurnStateRunning,
    TurnStateDone,
    TurnStateCancelled,
    TurnStateError,
)

client = TrueFoundryGateway(
    base_url=os.environ["TFY_GATEWAY_URL"],
    api_key=os.environ["TFY_API_KEY"],
)

# list_turns() always returns turns in descending order (newest-first).
for turn in client.agents.sessions.list_turns(session_id="sess-abc123"):
    turn_state = turn.state
    print("turn id:", turn.id)
    # input is the list that started the turn: UserMessage(s), or
    # UserToolApprovalEvent / UserToolResponseEvent items.
    print("input:", turn.input)

    if isinstance(turn_state, TurnStateRunning):
        print("status: running (no output yet)")
    elif isinstance(turn_state, TurnStateDone):
        print("status: done")
        # output is the final assistant message (model.message), or None.
        if turn_state.output is not None:
            print("output:", turn_state.output.content)
        # required_actions lists any pause events the turn surfaced
        # (tool.approval_required, tool.response_required, mcp.auth_required).
        for item in turn_state.required_actions:
            print("required action:", item)
    elif isinstance(turn_state, TurnStateCancelled):
        print("status: cancelled", turn_state.reason)
    elif isinstance(turn_state, TurnStateError):
        print("status: error", turn_state.message)

import { TrueFoundryGateway } from "truefoundry-gateway-sdk";

const client = new TrueFoundryGateway({
  apiKey: process.env.TFY_API_KEY!,
  baseUrl: process.env.TFY_GATEWAY_URL!,
});

// listTurns() always returns turns in descending order (newest-first).
for await (const turn of await client.agents.sessions.listTurns("sess-abc123")) {
  const turnState = turn.state;
  console.log("turn id:", turn.id);
  // input is the list that started the turn: user.message items, or
  // user.tool_approval / user.tool_response items.
  console.log("input:", turn.input);

  if (turnState.status === "running") {
    console.log("status: running (no output yet)");
  } else if (turnState.status === "done") {
    console.log("status: done");
    // output is the final assistant message (model.message), or null.
    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, call create_turn / createTurn. It returns the turn object immediately (no SSE) — the turn may still be running. Use get_turn / getTurn or create_turn_stream when you need terminal state or events.

import os
from truefoundry_gateway_sdk import TrueFoundryGateway, UserMessage

client = TrueFoundryGateway(
    base_url=os.environ["TFY_GATEWAY_URL"],
    api_key=os.environ["TFY_API_KEY"],
)
response = client.agents.sessions.create(agent_name="support-bot")
session = response.data

response = client.agents.sessions.create_turn(
    session.id,
    input=[UserMessage(content="Summarize my last order.")],
)
turn = response.data
print(turn.id, turn.state)

import { TrueFoundryGateway } from "truefoundry-gateway-sdk";

const client = new TrueFoundryGateway({
  apiKey: process.env.TFY_API_KEY!,
  baseUrl: process.env.TFY_GATEWAY_URL!,
});
const { data: session } = await client.agents.sessions.create({ agentName: "support-bot" });

const { data: turn } = await client.agents.sessions.createTurn(session.id, {
  input: [{ type: "user.message", content: "Summarize my last order." }],
});

console.log(turn.id, turn.state);

Attach images or files to a turn

A UserMessage’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 of the form data:<mime>;base64,<payload>.

import base64
import os
from truefoundry_gateway_sdk import TrueFoundryGateway, UserMessage
from truefoundry_gateway_sdk.types import TextContent, FileContent

client = TrueFoundryGateway(
    base_url=os.environ["TFY_GATEWAY_URL"],
    api_key=os.environ["TFY_API_KEY"],
)
response = client.agents.sessions.create(agent_name="support-bot")
session = response.data
def to_data_uri(path: str, mime: str) -> str:
    with open(path, "rb") as f:
        return f"data:{mime};base64,{base64.b64encode(f.read()).decode()}"

# Attach both an image and a document in the same message.
image_uri = to_data_uri("invoice.png", "image/png")
doc_uri = to_data_uri("notes.txt", "text/plain")

stream = client.agents.sessions.create_turn_stream(
    session.id,
    input=[
        UserMessage(
            content=[
                TextContent(text="Does the invoice total match the notes?"),
                FileContent(name="invoice.png", data=image_uri),
                FileContent(name="notes.txt", data=doc_uri),
            ]
        )
    ],
)
for event in stream:
    print(event)

import { readFileSync } from "node:fs";
import { TrueFoundryGateway } from "truefoundry-gateway-sdk";

const client = new TrueFoundryGateway({
  apiKey: process.env.TFY_API_KEY!,
  baseUrl: process.env.TFY_GATEWAY_URL!,
});
const { data: session } = await client.agents.sessions.create({ agentName: "support-bot" });

function toDataUri(path: string, mime: string): string {
  return `data:${mime};base64,${readFileSync(path).toString("base64")}`;
}

// Attach both an image and a document in the same message.
const imageUri = toDataUri("invoice.png", "image/png");
const docUri = toDataUri("notes.txt", "text/plain");

const stream = await client.agents.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 event of stream) {
  console.log(event);
}

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.

Non-image files such as PDFs require the sandbox to be enabled on the agent - the harness uses it to process the document.

Cancel a turn

To stop the currently running turn, call cancel / cancel on the session. 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.

import os
from truefoundry_gateway_sdk import TrueFoundryGateway, UserMessage
from truefoundry_gateway_sdk.agents import TurnCreatedEvent

client = TrueFoundryGateway(
    base_url=os.environ["TFY_GATEWAY_URL"],
    api_key=os.environ["TFY_API_KEY"],
)
response = client.agents.sessions.create(agent_name="support-bot")
session = response.data
# Start a turn, then cancel the session partway through the stream.
turn_id = None
i = 0
stream = client.agents.sessions.create_turn_stream(
    session.id,
    input=[UserMessage(content="Run a long research task.")],
)
for event in stream:
    print(event)
    if isinstance(event, TurnCreatedEvent):
        turn_id = event.turn_id
    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.
        client.agents.sessions.cancel(session.id)
    i += 1

# A cancelled turn is terminal, so its event log is stored and can be replayed.
for event in client.agents.sessions.list_turn_events(session.id, turn_id, order="asc"):
    print(event)

# Continue the conversation: a new turn chains on the cancelled turn's history.
stream = client.agents.sessions.create_turn_stream(
    session.id,
    input=[UserMessage(content="Actually, just give me a quick summary instead.")],
)
for event in stream:
    print(event)

import { TrueFoundryGateway } from "truefoundry-gateway-sdk";

const client = new TrueFoundryGateway({
  apiKey: process.env.TFY_API_KEY!,
  baseUrl: process.env.TFY_GATEWAY_URL!,
});
const { data: session } = await client.agents.sessions.create({ agentName: "support-bot" });

// Start a turn, then cancel the session partway through the stream.
let turnId: string | undefined;
let i = 0;
const stream = await client.agents.sessions.createTurnStream(session.id, {
  input: [{ type: "user.message", content: "Run a long research task." }],
});
for await (const event of stream) {
  console.log(event);
  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. Keep consuming until
    // the loop finishes so cancellation completes cleanly.
    await client.agents.sessions.cancel(session.id);
  }
  i += 1;
}

// A cancelled turn is terminal, so its event log is stored and can be replayed.
for await (const event of await client.agents.sessions.listTurnEvents(session.id, turnId!, {
  order: "asc",
})) {
  console.log(event);
}

// Continue the conversation: a new turn chains on the cancelled turn's history.
const nextStream = await client.agents.sessions.createTurnStream(session.id, {
  input: [{ type: "user.message", content: "Actually, just give me a quick summary instead." }],
});
for await (const event of nextStream) {
  console.log(event);
}

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 event and the turn ends. The event lists each server that needs authentication along with an auth_url. Depending on how the server is configured, this may be an OAuth flow or an API-key entry - see MCP authentication scenarios for details. Send the user to that URL to complete authentication, then resume by creating a new turn.

When the previous turn ended with mcp.auth_required, passing a UserMessage in the resuming turn is not allowed.

import os
from truefoundry_gateway_sdk import TrueFoundryGateway, UserMessage
from truefoundry_gateway_sdk.agents import McpAuthRequiredEvent

client = TrueFoundryGateway(
    base_url=os.environ["TFY_GATEWAY_URL"],
    api_key=os.environ["TFY_API_KEY"],
)
response = client.agents.sessions.create(agent_name="support-bot")
session = response.data
# First turn: the agent needs an MCP server the user hasn't authorized yet.
# A turn emits at most one mcp.auth_required event.
pending_auth = None
stream = client.agents.sessions.create_turn_stream(
    session.id,
    input=[UserMessage(content="Summarize my latest GitHub issues.")],
)
for event in stream:
    print(event)
    if isinstance(event, McpAuthRequiredEvent):
        pending_auth = event

# Direct the user to each server's auth URL and wait for them to finish.
for server in pending_auth.mcp_servers:
    print(f"Authorize {server.name}: {server.auth_url}")
input("Press Enter once you have authorized the server(s)...")

# Second turn: resume — the agent continues the interrupted work.
stream = client.agents.sessions.create_turn_stream(session.id)
for event in stream:
    print(event)

import { createInterface } from "node:readline/promises";
import { stdin, stdout } from "node:process";
import { TrueFoundryGateway } from "truefoundry-gateway-sdk";

const client = new TrueFoundryGateway({
  apiKey: process.env.TFY_API_KEY!,
  baseUrl: process.env.TFY_GATEWAY_URL!,
});
const { data: session } = await client.agents.sessions.create({ agentName: "support-bot" });
const rl = createInterface({ input: stdin, output: stdout });

// First turn: the agent needs an MCP server the user hasn't authorized yet.
// A turn emits at most one mcp.auth_required event.
let pendingAuth;
const stream = await client.agents.sessions.createTurnStream(session.id, {
  input: [{ type: "user.message", content: "Summarize my latest GitHub issues." }],
});
for await (const event of stream) {
  console.log(event);
  if (event.type === "mcp.auth_required") {
    pendingAuth = event;
  }
}

// Direct the user to each server's auth URL and wait for them to finish.
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)...");

// Second turn: resume - the agent continues the interrupted work.
const resumeStream = await client.agents.sessions.createTurnStream(session.id);
for await (const event of resumeStream) {
  console.log(event);
}
rl.close();

Handle tool approvals

When a tool call is configured to require human approval, the agent emits a tool.approval_required event and the turn ends. Each event carries a thread_id and the tool_calls 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 UserToolApprovalEvent per pending tool call — allow it, or deny it with an optional reason. Each pending ToolCallRef carries the source_event_id of the model.message that emitted the tool call. Keep the same id-keyed event index you build while streaming, then look up events[source_event_id] to read the tool’s name and arguments — no separate bookkeeping required.

import os
from truefoundry_gateway_sdk import TrueFoundryGateway, UserMessage
from truefoundry_gateway_sdk.agents import (
    ToolApprovalRequiredEvent,
    TurnEvent,
    UserToolApprovalEvent,
    is_event_delta,
    merge_event_delta,
)
from truefoundry_gateway_sdk.types import ApprovalAllow, ApprovalDeny

client = TrueFoundryGateway(
    base_url=os.environ["TFY_GATEWAY_URL"],
    api_key=os.environ["TFY_API_KEY"],
)
response = client.agents.sessions.create(agent_name="support-bot")
session = response.data
# First turn: the agent calls one or more tools that need approval.
events: dict[str, TurnEvent] = {}  # event id -> assembled event
pending_approvals = []             # a turn can emit multiple tool.approval_required events

stream = client.agents.sessions.create_turn_stream(
    session.id,
    input=[UserMessage(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 isinstance(event, ToolApprovalRequiredEvent):
        pending_approvals.append(event)

# Decide on each pending tool call, showing its name and arguments.
approvals = []
for pending in pending_approvals:
    for ref in pending.tool_calls:
        # Look up the model.message that emitted this tool call, then find the call.
        model_message = events[ref.source_event_id]
        tool_call = next(tc for tc in (model_message.tool_calls or []) if tc.id == ref.id)
        print(f"\napproval needed: {tool_call.tool_info.name}")
        print(f"  arguments: {tool_call.function.arguments}")
        answer = input("allow? [y/n] ").strip().lower()
        approvals.append(
            UserToolApprovalEvent(
                thread_id=pending.thread_id,
                tool_call_id=ref.id,
                approval=ApprovalAllow() if answer == "y" else ApprovalDeny(reason="denied by user"),
            )
        )

# Second turn: resume with the approval decisions.
stream = client.agents.sessions.create_turn_stream(session.id, input=approvals)
for event in stream:
    print(event)

import { createInterface } from "node:readline/promises";
import { stdin, stdout } from "node:process";
import { TrueFoundryGateway } from "truefoundry-gateway-sdk";
import {
  isEventDelta,
  mergeEventDelta,
  type TurnEvent,
} from "truefoundry-gateway-sdk/agents";

const client = new TrueFoundryGateway({
  apiKey: process.env.TFY_API_KEY!,
  baseUrl: process.env.TFY_GATEWAY_URL!,
});
const { data: session } = await client.agents.sessions.create({ agentName: "support-bot" });
const rl = createInterface({ input: stdin, output: stdout });

// First turn: the agent calls one or more tools that need approval.
const events = new Map<string, TurnEvent>(); // event id -> assembled event
const pendingApprovals = [];                  // a turn can emit multiple tool.approval_required events

const stream = await client.agents.sessions.createTurnStream(session.id, {
  input: [{ type: "user.message", content: "Restart the billing service." }],
});
for await (const event of stream) {
  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);
  }
}

// Decide on each pending tool call, showing its name and arguments.
const approvals = [];
for (const pending of pendingApprovals) {
  for (const ref of pending.toolCalls) {
    // Look up the model.message that emitted this tool call, then find the call.
    const modelMessage = events.get(ref.sourceEventId)!;
    const toolCall = modelMessage.toolCalls!.find((tc) => tc.id === ref.id)!;
    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" },
    });
  }
}

// Second turn: resume with the approval decisions.
const resumeStream = await client.agents.sessions.createTurnStream(session.id, { input: approvals });
for await (const event of resumeStream) {
  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 tool. Since the tool runs on your side, the agent emits a 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 UserToolResponseEvent per pending tool call. Each pending ToolCallRef carries the source_event_id of the model.message that emitted the tool call. Keep the same id-keyed event index you build while streaming, then look up events[source_event_id] to read the tool’s name and arguments — no separate bookkeeping required.

import json
import os
from truefoundry_gateway_sdk import TrueFoundryGateway, UserMessage
from truefoundry_gateway_sdk.agents import (
    ToolResponseRequiredEvent,
    TurnEvent,
    UserToolResponseEvent,
    is_event_delta,
    merge_event_delta,
)
from truefoundry_gateway_sdk.types import TrueFoundrySystemToolInfo

client = TrueFoundryGateway(
    base_url=os.environ["TFY_GATEWAY_URL"],
    api_key=os.environ["TFY_API_KEY"],
)
response = client.agents.sessions.create(agent_name="support-bot")
session = response.data
# First turn: the agent asks the user a question.
events: dict[str, TurnEvent] = {}  # event id -> assembled event
pending_questions = []             # a turn can emit multiple tool.response_required events

stream = client.agents.sessions.create_turn_stream(
    session.id,
    input=[UserMessage(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 isinstance(event, ToolResponseRequiredEvent):
        pending_questions.append(event)

# Answer each pending question, reading the prompt and options from arguments.
responses = []
for pending in pending_questions:
    for ref in pending.tool_calls:
        # Look up the model.message that emitted this tool call, then find the call.
        model_message = events[ref.source_event_id]
        tool_call = next(tc for tc in (model_message.tool_calls or []) if tc.id == ref.id)
        # tool.response_required covers any client-side tool; handle ask_user_question here.
        if not (
            isinstance(tool_call.tool_info, TrueFoundrySystemToolInfo)
            and tool_call.tool_info.name == "ask_user_question"
        ):
            continue
        args = json.loads(tool_call.function.arguments or "{}")
        print(f"\n{args.get('question', '')}")
        for idx, option in enumerate(args.get("options") or [], 1):
            print(f"  {idx}. {option}")
        answer = input("your answer: ").strip()
        responses.append(
            UserToolResponseEvent(
                thread_id=pending.thread_id,
                tool_call_id=ref.id,
                # content is a free-form string — the chosen option, or any text.
                content=answer,
            )
        )

# Second turn: resume with the user's answers.
stream = client.agents.sessions.create_turn_stream(session.id, input=responses)
for event in stream:
    print(event)

import { createInterface } from "node:readline/promises";
import { stdin, stdout } from "node:process";
import { TrueFoundryGateway } from "truefoundry-gateway-sdk";
import {
  isEventDelta,
  mergeEventDelta,
  type TurnEvent,
} from "truefoundry-gateway-sdk/agents";

const client = new TrueFoundryGateway({
  apiKey: process.env.TFY_API_KEY!,
  baseUrl: process.env.TFY_GATEWAY_URL!,
});
const { data: session } = await client.agents.sessions.create({ agentName: "support-bot" });
const rl = createInterface({ input: stdin, output: stdout });

// First turn: the agent asks the user a question.
const events = new Map<string, TurnEvent>(); // event id -> assembled event
const pendingQuestions = [];                  // a turn can emit multiple tool.response_required events

const stream = await client.agents.sessions.createTurnStream(session.id, {
  input: [{ type: "user.message", content: "Create a new environment called testing-1." }],
});
for await (const event of stream) {
  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);
  }
}

// Answer each pending question, reading the prompt and options from arguments.
const responses = [];
for (const pending of pendingQuestions) {
  for (const ref of pending.toolCalls) {
    // Look up the model.message that emitted this tool call, then find the call.
    const modelMessage = events.get(ref.sourceEventId)!;
    const toolCall = modelMessage.toolCalls!.find((tc) => tc.id === ref.id)!;
    // 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 || "{}");
    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,
    });
  }
}

// Second turn: resume with the user's answers.
const resumeStream = await client.agents.sessions.createTurnStream(session.id, { input: responses });
for await (const event of resumeStream) {
  console.log(event);
}
rl.close();

Every turn emits a stream of events over SSE. The stream opens with turn.created and closes with turn.done. See the Turn events reference 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 Event Deltas - incremental fragments that you merge into the base. All deltas for one update share the base event’s id. The SSE id (sequence number used for resume) increases across the base and all its deltas — read it with Python .with_metadata() / TypeScript .withMetadata().

// 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 sub-agents) always merge into the right base.

Both languages ship is_event_delta and merge_event_delta from truefoundry_gateway_sdk.agents (Python) and truefoundry-gateway-sdk/agents (TypeScript).

Event Deltas appear only while streaming. When you list turn events via the events API, the deltas are already merged into a single assembled event.

The most common example is the assistant’s model output: a base ModelMessageEvent followed by ModelMessageDeltaEvent deltas that carry incremental text and tool-call chunks. Merge the deltas into the base as they arrive — read the base’s growing content for a live typing effect.

import os
from truefoundry_gateway_sdk import TrueFoundryGateway, UserMessage
from truefoundry_gateway_sdk.agents import (
    TurnEvent,
    is_event_delta,
    merge_event_delta,
)

client = TrueFoundryGateway(
    base_url=os.environ["TFY_GATEWAY_URL"],
    api_key=os.environ["TFY_API_KEY"],
)
response = client.agents.sessions.create(agent_name="support-bot")
session = response.data
events: dict[str, TurnEvent] = {}  # event id -> assembled event

stream = client.agents.sessions.create_turn_stream(
    session.id,
    input=[UserMessage(content="Summarize my last order.")],
)
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

import { TrueFoundryGateway } from "truefoundry-gateway-sdk";
import {
  isEventDelta,
  mergeEventDelta,
  type TurnEvent,
} from "truefoundry-gateway-sdk/agents";

const client = new TrueFoundryGateway({
  apiKey: process.env.TFY_API_KEY!,
  baseUrl: process.env.TFY_GATEWAY_URL!,
});
const { data: session } = await client.agents.sessions.create({ agentName: "support-bot" });

const events = new Map<string, TurnEvent>(); // event id -> assembled event

const stream = await client.agents.sessions.createTurnStream(session.id, {
  input: [{ type: "user.message", content: "Summarize my last order." }],
});
for await (const event of stream) {
  if (isEventDelta(event)) {
    const base = events.get(event.id);
    if (base) mergeEventDelta(base, event);
  } else {
    events.set(event.id, event);
  }
}

Resume streaming

When you lose the original create_turn_stream / createTurnStream stream (for example, after a page reload), call get and get_turn, then check turn.state. If it is still running, reconnect with subscribe_to_turn / subscribeToTurn and keep merging; if it has already finished, rebuild the index from list_turn_events / listTurnEvents instead. When resuming a running turn, pass after_sequence_number to continue after a known point; the stream closes when the turn reaches a terminal state. Either way, merge into the same id-keyed index of assembled events, so base events and their deltas keep merging seamlessly across the reconnect. The sequence number is the SSE id, not a field on the event body. Track it while streaming with Python .with_metadata() or TypeScript .withMetadata():

# Default iteration: typed event body only
async for event in stream:
    ...

# With metadata: StreamEvent with .id (SSE id) + .data (typed body) — needed for resume
async for item in stream.with_metadata():
    last_sequence_number = int(item.id)
    event = item.data

// Default iteration: typed event body only
for await (const event of stream) { ... }

// With metadata: ServerSentEvent with .id (SSE id) + .data (typed body) — needed for resume
for await (const item of stream.withMetadata()) {
  lastSequenceNumber = Number(item.id);
  const event = item.data;
}

from truefoundry_gateway_sdk.agents import (
    TurnStateRunning,
    is_event_delta,
    merge_event_delta,
)

# `client`, `session_id`, `turn_id`, `events`, and `last_sequence_number` already exist from the original stream:
#   session_id: str               - the id of the session
#   turn_id: str                  - the id of the turn you were streaming
#   events: dict[str, TurnEvent]  - the id-keyed index of assembled events
#   last_sequence_number: int     - int(SSE id) of the last event you processed (from with_metadata())
# Persist all four (for example, in your session store) so you can resume after a restart.

response = client.agents.sessions.get(session_id)
session = response.data
response = client.agents.sessions.get_turn(session_id, turn_id)
turn = response.data

if isinstance(turn.state, TurnStateRunning):
    # Still running: reconnect to the live stream. after_sequence_number skips events
    # you've already processed.
    stream = client.agents.sessions.subscribe_to_turn(
        session_id,
        turn_id,
        after_sequence_number=last_sequence_number,
    )
    for item in stream.with_metadata():
        if item.id is not None:
            last_sequence_number = int(item.id)
        event = item.data
        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 the index from the stored event log, which is
    # authoritative and overwrites any partial state from the lost stream.
    # list_turn_events() returns already-merged events, so there are no deltas to merge here.
    for event in client.agents.sessions.list_turn_events(session_id, turn_id):
        events[event.id] = event

import { isEventDelta, mergeEventDelta, type TurnEvent } from "truefoundry-gateway-sdk/agents";

// `client`, `sessionId`, `turnId`, `events`, and `lastSequenceNumber` already exist from the original stream:
//   sessionId: string              - the id of the session
//   turnId: string                 - the id of the turn you were streaming
//   events: Map<string, TurnEvent> - the id-keyed index of assembled events
//   lastSequenceNumber: number     - Number(SSE id) of the last event you processed (from withMetadata())
// Persist all four (for example, in your session store) so you can resume after a restart.

const { data: session } = await client.agents.sessions.get(sessionId);
const { data: turn } = await client.agents.sessions.getTurn(sessionId, turnId);

if (turn.state.status === "running") {
  // Still running: reconnect to the live stream. afterSequenceNumber skips events
  // you've already processed.
  const stream = await client.agents.sessions.subscribeToTurn(sessionId, turnId, {
    afterSequenceNumber: lastSequenceNumber,
  });
  for await (const { id, data: event } of stream.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 the index from the stored event log, which is
  // authoritative and overwrites any partial state from the lost stream.
  // listTurnEvents() returns already-merged events, so there are no deltas to merge here.
  for await (const event of await client.agents.sessions.listTurnEvents(sessionId, turnId)) {
    events.set(event.id, event);
  }
}

Handle threads

A single turn stream interleaves events from the root agent and any sub-agents that run in parallel. Every event carries a thread_id:

"main" — the root agent.
A unique ID — a sub-agent thread. thread.created and thread.done mark sub-agent thread lifecycle; they are not emitted for the main thread.
null — a turn-level event, not tied to any thread: turn.created and turn.done (first and last on the stream), sandbox.created, and mcp.auth_required.

See Turn Events for the full reference. The sequence below shows a turn where the root agent spawns a research sub-agent. Events interleave across two threads (main and the sub-agent), and the run pauses for an approval before a second turn resumes it. Solid arrows are turn inputs you send; dashed arrows are SSE events streamed back to your client.

import os
from collections import defaultdict
from truefoundry_gateway_sdk import TrueFoundryGateway, UserMessage
from truefoundry_gateway_sdk.agents import (
    ModelMessageDeltaEvent,
    ModelMessageEvent,
    ThreadCreatedEvent,
    ThreadDoneEvent,
    TurnEvent,
    is_event_delta,
    merge_event_delta,
)
from truefoundry_gateway_sdk.types import TrueFoundrySystemToolInfo

client = TrueFoundryGateway(
    base_url=os.environ["TFY_GATEWAY_URL"],
    api_key=os.environ["TFY_API_KEY"],
)
response = client.agents.sessions.create(agent_name="support-bot")
session = response.data
threads: dict[str, dict[str, TurnEvent]] = defaultdict(dict)

stream = client.agents.sessions.create_turn_stream(
    session.id,
    input=[UserMessage(content="Summarize my last order.")],
)
for event in stream:
    if event.thread_id is None:
        print("turn level event:", event)
        continue

    if isinstance(event, (ModelMessageEvent, ModelMessageDeltaEvent)):
        for tool_call in event.tool_calls or []:
            if (
                isinstance(tool_call.tool_info, TrueFoundrySystemToolInfo)
                and tool_call.tool_info.name == "create_sub_agent"
            ):
                print("sub agent is getting initialized")
    if isinstance(event, ThreadCreatedEvent):
        print(f"{event.thread_id} created: {event.title}")

    if is_event_delta(event):
        thread_events = threads.get(event.thread_id)
        if thread_events is not None:
            base = thread_events.get(event.id)
            if base is not None:
                merge_event_delta(base, event)
    else:
        threads[event.thread_id][event.id] = event

    if isinstance(event, ThreadDoneEvent):
        events_for_thread = threads.pop(event.thread_id)
        print(f"{event.thread_id} done: {event.title} ({len(events_for_thread)} events)")

import { TrueFoundryGateway } from "truefoundry-gateway-sdk";
import {
  isEventDelta,
  mergeEventDelta,
  type TurnEvent,
} from "truefoundry-gateway-sdk/agents";

const client = new TrueFoundryGateway({
  apiKey: process.env.TFY_API_KEY!,
  baseUrl: process.env.TFY_GATEWAY_URL!,
});
const { data: session } = await client.agents.sessions.create({ agentName: "support-bot" });

const threads = new Map<string, Map<string, TurnEvent>>();

const stream = await client.agents.sessions.createTurnStream(session.id, {
  input: [{ type: "user.message", content: "Summarize my last order." }],
});
for await (const event of stream) {
  if (event.threadId == null) {
    console.log("turn level event:", event);
    continue;
  }

  if (event.type === "model.message" || event.type === "model.message.delta") {
    for (const toolCall of event.toolCalls ?? []) {
      if (
        toolCall.toolInfo?.type === "truefoundry-system" &&
        toolCall.toolInfo.name === "create_sub_agent"
      ) {
        console.log("sub agent is getting initialized");
      }
    }
  }
  if (event.type === "thread.created") {
    console.log(`${event.threadId} created: ${event.title}`);
  }

  if (isEventDelta(event)) {
    const base = threads.get(event.threadId)?.get(event.id);
    if (base) mergeEventDelta(base, event);
  } else {
    let bucket = threads.get(event.threadId);
    if (!bucket) {
      bucket = new Map();
      threads.set(event.threadId, bucket);
    }
    bucket.set(event.id, event);
  }

  if (event.type === "thread.done") {
    const eventsForThread = threads.get(event.threadId) ?? new Map();
    threads.delete(event.threadId);
    console.log(`${event.threadId} done: ${event.title} (${eventsForThread.size} events)`);
  }
}

Listing Events

Fetch the full event log of a finished turn with list_turn_events / listTurnEvents. It yields the turn’s events in order and auto-paginates. Pass order="asc" (default, oldest-first) or order="desc" to control the direction. Unlike live create_turn_stream / subscribe_to_turn streams, list_turn_events returns already-merged events: each model message arrives as a single assembled ModelMessageEvent, 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:

// On create_turn_stream / subscribe_to_turn: 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 list_turn_events as one fully-merged event:

// On list_turn_events: the same message, already assembled
{ "type": "model.message", "id": "0f3a...", "content": "Hello!", "finish_reason": "stop" }

list_turn_events is only available for turns that have completed. A running turn has no stored event log yet — use create_turn_stream or subscribe_to_turn for live delivery instead.

import os
from truefoundry_gateway_sdk import TrueFoundryGateway
from truefoundry_gateway_sdk.agents import TurnStateRunning

client = TrueFoundryGateway(
    base_url=os.environ["TFY_GATEWAY_URL"],
    api_key=os.environ["TFY_API_KEY"],
)

# Find the latest completed turn (newest-first).
for turn in client.agents.sessions.list_turns("sess-abc123"):
    # list_turn_events() is only available once the turn has completed.
    if isinstance(turn.state, TurnStateRunning):
        continue
    # order="asc" (default) yields oldest-first; use "desc" for newest-first.
    for event in client.agents.sessions.list_turn_events(
        "sess-abc123", turn.id, order="asc"
    ):
        print(event)
    break

import { TrueFoundryGateway } from "truefoundry-gateway-sdk";

const client = new TrueFoundryGateway({
  apiKey: process.env.TFY_API_KEY!,
  baseUrl: process.env.TFY_GATEWAY_URL!,
});

// Find the latest completed turn (newest-first).
for await (const turn of await client.agents.sessions.listTurns("sess-abc123")) {
  const turnState = turn.state;
  // listTurnEvents() is only available once the turn has completed.
  if (turnState.status === "running") {
    continue;
  }
  // order "asc" (default) yields oldest-first; use "desc" for newest-first.
  for await (const event of await client.agents.sessions.listTurnEvents(
    "sess-abc123",
    turn.id,
    { order: "asc" },
  )) {
    console.log(event);
  }
  break;
}

Complete example

The Complete example is a runnable terminal chat client that implements every pattern in this guide — streaming, delta merging, approvals, questions, MCP auth, sub-agent threads, and multi-turn chaining.

Agent Harness

Agent Governance

Install and connect

Create a client

Create a session

Open a session

List sessions for an agent

Create a turn

Create and stream a turn

List turns

Non-streaming turn

Attach images or files to a turn

Cancel a turn

Handle MCP outbound auth

Handle tool approvals

Answer agent questions

Handling Event Delta while streaming

Resume streaming

Handle threads

Listing Events

Complete example

​Install and connect

​Create a client

​Create a session

​Open a session

​List sessions for an agent

​Create a turn

​Create and stream a turn

​List turns

​Non-streaming turn

​Attach images or files to a turn

​Cancel a turn

​Handle MCP outbound auth

​Handle tool approvals

​Answer agent questions

​Subscribe to events

​Handling Event Delta while streaming

​Resume streaming

​Handle threads

​Listing Events

​Complete example

Install and connect

Create a client

Create a session

Open a session

List sessions for an agent

Create a turn

Create and stream a turn

List turns

Non-streaming turn

Attach images or files to a turn

Cancel a turn

Handle MCP outbound auth

Handle tool approvals

Answer agent questions

Subscribe to events

Handling Event Delta while streaming

Resume streaming

Handle threads

Listing Events

Complete example