TrueForge 0.185.0+ introduces breaking changes to turn lifecycle - turns now pause when waiting for user input.
Click here to view the documentation for older versions.
@truefoundry/trueforge-sdk or trueforge-sdk. New here? Install and stream your first turn in the SDK Quickstart first. For the mental model (Agent → Session → Turn → Event → Delta), see Concepts; for every event field, see the turn events reference at the bottom of this page.
Prerequisite: a named agent in the registry, or an inline agent spec you pass when creating the session. The examples below run the
web-research-brief agent from the Quickstart; build it there first, or swap in your own agent name / inline spec.client from Install and connect.
Install and connect
baseUrl / base_url at your running TrueForge server; http://localhost:8790 is the Quickstart default. When OIDC login is enabled, pass token (an ID token from your IdP; see 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 page explains the model with a conceptualsupport-bot; here is a real agent you can run. In the 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, so you’ll see their threads in the same stream. It has no approval gate, so it runs end to end without waiting on you; for approvals and questions, see Handle pauses.
turn.done. This version writes each delta straight to stdout. The next section 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. Persistsession.id to resume later.
Open a session
List sessions
Newest-first; filter withagentId / agent_id. TypeScript returns a Page async iterable; Python returns a SyncPager. Both auto-paginate.
Turns
A turn is one request/response cycle: you send a message, and the agent works until it has an answer. If it needs something from you along the way (an approval, an answer, or an MCP sign-in), the turn pauses and waits. You answer on the same turn and it carries on. Turns chain automatically (previousTurnId defaults to "auto"), so you never resend history.
Only one turn is active in a session at a time. Sending a new message cancels a turn that is still running or waiting for an answer, and the new turn picks up from there.
Create and stream a turn
createTurnStream / create_turn_stream returns a stream of turn events. The stream opens with turn.created and closes with turn.done; read the final result from turn.done.state. If the turn pauses, stop reading there and continue with Handle pauses: subscribe, send your answer, then read.
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 / list_turn_events returns them already merged.) Pause handlers and the per-thread index below reuse this pattern.
Also keep the turn id (from turn.created) and the id of the last event you received. You need the turn id to answer a paused turn, and the last event id to resume the stream if the connection drops.
input is one or more user.message items. content is a non-empty string, or an array of text / file parts (files as data URIs). Approvals, answers, and MCP sign-ins are not part of input; you send them to the paused turn, as shown in Handle pauses.
Non-streaming turn
If you don’t need live events, TypeScriptsessions.createTurn (stream: false) and Python sessions.create_turn return immediately with state.status: "running" and run in the background. Poll getTurn / get_turn while the status is running. When it stops, the turn has either finished (done, cancelled, error) or is paused and waiting for you.
List turns
Oldest-first; each turn exposes itsinput and state.
Attach images or files
Auser.message’s content can be an array of parts: text plus one or more files as data URIs (data:<mime>;base64,<payload>).
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 enabled on the agent; the harness uses it to process the document.
Cancel a turn
sessions.cancel(sessionId) / sessions.cancel(session_id=…) stops the session’s active turn, whether it is running or paused waiting for you. 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.
Handle pauses
A turn pauses when the agent needs something from you. You’ll first see an event saying what it needs, then aturn.update with state.status: "paused". The turn isn’t over. Read until that point and keep the id of the last event, then:
- Open
subscribeToTurn/subscribe_to_turnfrom that event id. - Send your answers to the same turn with
createTurnEvents/create_turn_events. - Read the subscription. It carries everything your answer produces, through to
turn.doneor the next pause.
A turn can wait on several things at once (e.g. parallel subagents each hit a gate), so collect every prompt. The turn continues once everything it was waiting for is answered. You can send all the answers in one call, or a few at a time.
For approvals and questions, each pending call in
tool_calls has an id (the tool call you answer, as tool_call_id) and a source_event_id pointing at the model.message that made the call. Look it up in the event index to read the tool’s name and arguments.
The answers you send also show up on the stream as events (user.tool_approval, user.tool_response, user.tool_approval_policy, user.mcp_auth_continue). So the stream always tells you what is still open: a call is waiting until a matching answer with its tool_call_id appears or a session approval covers its tool, and an MCP sign-in is waiting until a user.mcp_auth_continue follows it.
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.Tool approvals
A gated tool (human approval) emitstool.approval_required. Read until the turn pauses and collect the pending calls. Then subscribe from the last event, send one user.tool_approval per call (allow, or deny with a reason), and read that subscription.
Approve a tool until an expiry
For a tool on an MCP server, you can approve every call to it until an expiry instead of one call at a time. Send auser.tool_approval_policy with the MCP server name, the tool name, and expireAt / expire_at — an absolute ISO 8601 time, such as 10 minutes from now. It also approves calls to that tool that are already waiting, so send it instead of a user.tool_approval for those calls.
Where you read the server and tool name depends on how the agent loads tools:
- Preloaded tools arrive as the tool itself.
toolInfo/tool_infohastype: "mcp"withserverName/server_nameandname. - Deferred tools (the default, see Deferred tool loading) arrive as a
call_toolcall whosetoolInfo/tool_infoistype: "truefoundry-system". The real server and tool are in its arguments asmcp_serverandtool_name.
user.tool_approval push with the following. A call that isn’t an MCP tool falls back to a normal one-off approval.
Agent questions
When the agent uses the built-inask_user_question tool, it emits tool.response_required; the pending call’s arguments carry the question and options. Read until the turn pauses, then subscribe, send one user.tool_response per pending call, and read on.
MCP outbound auth
When a tool needs a server’s OAuth, the agent emitsmcp.auth_required, listing each server and its authUrl, and the turn pauses. Send the user there. Once they’ve signed in, subscribe, send user.mcp_auth_continue, and read on. The agent picks up the interrupted work. See In-chat authentication.
Resilience and threads
Resume a stream
If you lose thecreateTurnStream / create_turn_stream connection (e.g. a process restart), persist session.id, turnId / turn_id, and the id of the last event you received. To resume, call getTurn / get_turn:
- Running or paused: reconnect with
subscribeToTurn/subscribe_to_turnandfromEventId/from_event_idset to the last event id. The replay starts at that event, so if you dropped in the middle of a reply, themodel.messagebase arrives again and your event index rebuilds it from its deltas. UseafterEventId/after_event_idinstead when you only want what comes after it. - Finished: rebuild from
listTurnEvents/list_turn_events.
Subagent threads
A turn stream interleaves the root agent and any parallel subagents, exactly what the Quick Start above does. Every event carries athreadId / thread_id:
"main": the root agent.- A unique id: a subagent thread.
thread.createdandthread.donebracket its lifecycle. null: a turn-level event, such asturn.created,turn.update,turn.done,sandbox.created, andmcp.auth_required.
Map<threadId, Map<id, event>> in TypeScript; nested dicts in Python) and apply the same event-index merge inside each thread’s bucket.
A subagent can need your approval or answer too. Its prompt carries the subagent’s thread_id; send that same thread_id back with your answer. Other subagents may keep working while one waits, so a prompt can arrive while the turn is still running; the turn shows paused only once nothing else can move forward. Answer it the same way as any other pause: subscribe from the last event you saw, send, then read.
Replay a turn
sessions.listTurnEvents() / list_turn_events() yields a turn’s events in order (auto-paginates; order: "asc" default, or "desc"). Events are already merged, so you can use each one directly. It works for finished and paused turns, including the answers you sent.
While a turn is running, the reply it is writing right now is not in the list yet. To watch a running turn, stream it with
createTurnStream / create_turn_stream or subscribeToTurn / subscribe_to_turn instead.Schedules
A schedule runs a saved agent on a recurring cadence, unattended. Each run sends the schedule’stask to the agent and is recorded as a session. Manage them through client.schedules; the Schedules guide covers the same feature in the UI.
Create a schedule
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.Runs
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.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).
A new turn’s stream opens with
turn.created and closes with turn.done. A resumed stream starts at the event id you pass. 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 a new turn’s stream. A resumed stream starts at the cursor you pass.
turn.update
The turn paused or started running again. state.status is one of:
paused— the agent is waiting for you. The events just before it say what it needs (see Handle pauses). Carries optionalmetrics(tokens and cost) for the turn so far.running— your answers were applied and the agent is working again.
turn.update — paused for approval
turn.done
Last event on every stream. state.status is one of:
done— carriesoutput(the finalmodel.message, ornullwhen the turn ended without one),completed_at, and optionalmetrics.cancelled— carries areason:client-cancelled,server-execution-timeout,cancelled-for-next-turn, orabandoned.error— carries amessage.
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. A cancelled turn keeps the metrics for the work it did.
turn.done
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:
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:
tool.approval_required
One or more tool calls need human approval before they can run. The turn waits for a user.tool_approval for each call (or a session approval for the tool).
tool.response_required
A client-side tool (e.g. ask_user_question) needs a result from your app. Same shape as tool.approval_required; the turn waits for a user.tool_response for each call.
Subagent thread events
thread.created
A subagent started. Subsequent events with this thread_id belong to it.
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 before the agent can proceed. mcp_servers lists { id, name, auth_url }. Send the user to auth_url; the turn waits for a user.mcp_auth_continue.
sandbox.created
A sandbox was provisioned, carrying its sandbox_id. Emitted once per session — subsequent turns reuse the same sandbox and emit no new event.
User events
user.message is the input you send when you create a turn. The others are answers you send to a paused turn with createTurnEvents / create_turn_events. Once applied, each answer also appears on the turn’s stream and in its event list, with its own id and created_at.
user.message
A user message.
user.mcp_auth_continue
The user finished signing in, so the turn continues the paused work. This event has no fields of its own and omits thread_id. See MCP outbound auth.
user.tool_approval
Decision for a pending tool call. See Tool approvals.
user.tool_approval_policy
Approve an MCP tool until an absolute expiry. This event omits thread_id. See Approve a tool until an expiry.