Runtime API reference - TrueFoundry Docs

For a guided walkthrough, see SDK overview.

Turn input

Each Turn’s input is a list of one of these types. Resuming a Turn paused by mcp.auth_required needs no input - omit input or pass [].

User messages (UserMessage) cannot be mixed with tool approvals or client-side tool responses in the same input list. UserToolApprovalEvent and UserToolResponseEvent may be mixed together.

UserMessage

Start a new conversation or send the next user message. content is either a plain string or a list of content parts, letting you attach files alongside text.

{ "type": "user.message", "content": "I would like to file a support ticket." }

{
    "type": "user.message",
    "content": [
        { "type": "text", "text": "Please review this document." },
        {
            "type": "file",
            "name": "report.pdf",
            "data": "data:application/pdf;base64,JVBERi0xLjQK..."
        }
    ]
}

Field	Type	Required	Description
`type`	`"user.message"`	Yes
`content`	string \| `UserMessageContentItem[]`	Yes	The message text, or a list of content parts (text and files).

UserMessageContentItem

A content part is one of: Text

Field	Type	Required	Description
`type`	`"text"`	Yes
`text`	string	Yes	The message text.

File

Field	Type	Required	Description
`type`	`"file"`	Yes
`name`	string	Yes	Name of the uploaded file.
`data`	string	Yes	Data URI: `data:<mime>;base64,<payload>`. MIME type is parsed from the URI.

UserToolApprovalEvent

Sent to resume a turn paused by tool.approval_required. One item per pending tool call.

{
    "type": "user.tool_approval",
    "thread_id": "main",
    "tool_call_id": "call_restart_billing",
    "approval": { "status": "allow" }
}

Field	Type	Required	Description
`type`	`"user.tool_approval"`	Yes
`thread_id`	string	Yes	`thread_id` from the `tool.approval_required` event.
`tool_call_id`	string	Yes	ID of the tool call being approved or denied.
`approval`	`ApprovalAllow` \| `ApprovalDeny`	Yes	Use `{"status": "allow"}` to permit the call, or `{"status": "deny", "reason": "..."}` to block it. `reason` is optional.

UserToolResponseEvent

Sent to resume a turn paused by tool.response_required. One item per pending tool call.

{
    "type": "user.tool_response",
    "thread_id": "main",
    "tool_call_id": "call_a1b2",
    "content": "tfy-prod-us (production)"
}

Field	Type	Required	Description
`type`	`"user.tool_response"`	Yes
`thread_id`	string	Yes	`thread_id` from the `tool.response_required` event.
`tool_call_id`	string	Yes	ID of the tool call whose result is being supplied.
`content`	string	Yes	The result to return to the agent.

Reference

The signatures below document the low-level generated client (TrueFoundryGateway → client.agents.sessions.*). For application code, prefer the high-level AgentSessionClient / AgentSessionClient wrapper from truefoundry_gateway_sdk.agents (Python) or truefoundry-gateway-sdk/agents (TypeScript) — same prepare_turn / execute / Turn model as the examples in Use an agent.

Python reference

import os
from truefoundry_gateway_sdk.agents import AgentSessionClient

client = AgentSessionClient(
    base_url=os.environ["TFY_GATEWAY_URL"],
    api_key=os.environ["TFY_API_KEY"],
)
session = client.create_session(agent_name="support-bot")
turn = session.prepare_turn(input=[...])
for data in turn.execute(stream=True):
    print(data.event)

Method	Description
`create_session(agent_name)`	Create a session
`list_sessions(agent_name, ...)`	List sessions (newest-first pager)
`get_session(session_id)`	Fetch session by id
`session.prepare_turn(input=..., previous_turn_id=...)`	Stage a turn (no HTTP yet)
`turn.execute(stream=True\|False)`	Start turn; stream events or wait for terminal state
`turn.refresh()`	Refetch lifecycle state from the server
`turn.wait_for_completion(poll_interval_ms=...)`	Block until the turn reaches a terminal state
`turn.stream(after_sequence_number=...)`	Reconnect to a running turn’s SSE
`turn.list_events(order=...)`	Merged event log for a completed turn
`turn.cancel()`	Cancel a running turn
`session.list_turns()`	List turns in the session
`session.get_turn(turn_id)`	Fetch a single turn by id
`session.cancel()`	Cancel the running turn

Import is_event_delta, merge_event_delta, and event types from truefoundry_gateway_sdk.agents. Import UserMessage and content-part types from truefoundry_gateway_sdk.types.

Low-level reference (`TrueFoundryGateway`)

import os
from truefoundry_gateway_sdk import TrueFoundryGateway

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

create

client.agents.sessions.create(agent_name=...) -> GetSessionResponse

Create a conversation Session for a saved agent. The returned response wraps the session in .data.

Param	Type	Required	Description
`agent_name`	string	Yes	Name of the saved agent to invoke.

list

client.agents.sessions.list(agent_name=..., limit=10, order=None, page_token=None, start_timestamp=None, end_timestamp=None)
  -> SyncPager[Session, ListSessionsResponse]

List Sessions for a saved agent, newest-first by default. The pager auto-paginates when iterated.

Param	Type	Required	Description
`agent_name`	string	Yes	Filter to sessions for a specific named agent.
`limit`	int	No	Number of sessions fetched per page (not a total cap).
`order`	`"asc"` \| `"desc"`	No	Sort order by creation time. Defaults to `"desc"`.
`page_token`	string	No	Pagination token from a previous page. Usually omitted — iteration handles paging.
`start_timestamp`	string	No	ISO-8601 lower bound on session creation time.
`end_timestamp`	string	No	ISO-8601 upper bound on session creation time.

get

client.agents.sessions.get(session_id) -> GetSessionResponse

Fetch an existing session by ID. The returned response wraps the session in .data.

Param	Type	Required	Description
`session_id`	string	Yes	Session ID to retrieve.

cancel

client.agents.sessions.cancel(session_id) -> CancelSessionResponse

Cancel the running turn for a session. Idempotent.

Param	Type	Required	Description
`session_id`	string	Yes	Session to cancel.

Session

The conversation context for a saved agent, returned by create and get in .data. Turns created within a session are chained automatically, so each turn sees the history of earlier ones. Key members:

Member	Type	Description
`id`	string	Unique session identifier. Persist it to resume later via `get`.
`agent_name`	string	Name of the saved agent this session belongs to.
`title`	string \| None	Optional human-readable title for the session.
`created_by_subject`	`Subject`	Subject (user / service account) that created this session.
`created_at`	string	ISO-8601 timestamp of session creation.
`updated_at`	string	ISO-8601 timestamp of the last session update.

create_turn

client.agents.sessions.create_turn(session_id, input=None, previous_turn_id="auto")
  -> Iterator[TurnStreamingEvent]

Start or continue a turn within a session. Responds with a Server-Sent Events stream. The first event is turn.created; the stream closes with turn.done.

Param	Type	Required	Description
`session_id`	string	Yes	Session to run the turn in.
`input`	`TurnInputItem[]`	No	Input items for this turn. See Turn input. Omit to resume after `mcp.auth_required`.
`previous_turn_id`	`string` \| `"auto"`	No	Turn chaining point. Defaults to `"auto"`, letting the server chain to the latest turn.

list_turns

client.agents.sessions.list_turns(session_id, page_token=None, limit=10)
  -> SyncPager[Turn, ListTurnsResponse]

List turns in a session, newest-first. The pager auto-paginates when iterated.

Param	Type	Required	Description
`session_id`	string	Yes	Session to list turns for.
`page_token`	string	No	Pagination token from a previous page.
`limit`	int	No	Number of turns fetched per page (not a total cap).

get_turn

client.agents.sessions.get_turn(session_id, turn_id) -> GetTurnResponse

Fetch a single turn by ID. The returned response wraps the turn in .data.

Param	Type	Required	Description
`session_id`	string	Yes	Session the turn belongs to.
`turn_id`	string	Yes	Turn ID to retrieve.

Turn

A single request/response cycle within a session, returned by list_turns and get_turn in .data. Transitions: running → done | cancelled | error.

Member	Type	Description
`id`	string	Unique turn identifier (UUIDv7).
`session_id`	string	The session this turn belongs to.
`previous_turn_id`	string \| None	Turn ID this turn chains from, or `None` for the first turn.
`created_by_subject`	`Subject`	Subject (user / service account) that created this turn.
`created_at`	string	ISO-8601 timestamp of turn creation.
`input`	`TurnInputItem[]` \| None	The Turn input that triggered this turn, if any.
`state`	`TurnState`	Cached lifecycle state (`running`, `done`, `cancelled`, or `error`). Refetch with `get_turn`.

subscribe_to_turn

client.agents.sessions.subscribe_to_turn(session_id, turn_id, after_sequence_number=None)
  -> Iterator[TurnStreamingEvent]

Reconnect to a running turn’s live SSE stream. Pass after_sequence_number to resume after a known point. Closes when the turn reaches a terminal state. Use list_turn_events for completed turns.

Param	Type	Required	Description
`session_id`	string	Yes	Session the turn belongs to.
`turn_id`	string	Yes	Turn to subscribe to.
`after_sequence_number`	int	No	Resume after this sequence number.

list_turn_events

client.agents.sessions.list_turn_events(session_id, turn_id, page_token=None, limit=25, order=None)
  -> SyncPager[TurnEvent, ListEventsResponse]

Return a paginated snapshot of stored events for a completed turn. Pass order="asc" to replay forward. The pager auto-paginates when iterated.

Param	Type	Required	Description
`session_id`	string	Yes	Session the turn belongs to.
`turn_id`	string	Yes	Turn whose events to list.
`page_token`	string	No	Pagination token from a previous page.
`limit`	int	No	Number of events fetched per page (not a total cap).
`order`	`"asc"` \| `"desc"`	No	Sort order by sequence number. Defaults to `"asc"`.

TypeScript reference

Import the high-level client from truefoundry-gateway-sdk/agents. Method names below use camelCase; Turn input JSON shapes are the same in every language.

import { AgentSessionClient } from "truefoundry-gateway-sdk/agents";

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

createSession

client.createSession({ agentName, title? }) -> Promise<AgentSession>

Create a conversation AgentSession for a saved agent.

Param	Type	Required	Description
`agentName`	string	Yes	Name of the saved agent to invoke.
`title`	string	No	Optional human-readable title for the session.

listSessions

client.listSessions({ agentName, startTimestamp?, endTimestamp?, limit?, order?, pageToken? })
  -> Promise<Page<AgentSession>>

List AgentSession objects for a saved agent, newest-first. The returned Page is async-iterable and auto-paginates.

Param	Type	Required	Description
`agentName`	string	Yes	Filter to sessions for a specific named agent.
`startTimestamp`	string	No	ISO-8601 lower bound on session creation time.
`endTimestamp`	string	No	ISO-8601 upper bound on session creation time.
`limit`	number	No	Number of sessions fetched per page (not a total cap).
`order`	`"asc"` \| `"desc"`	No	Sort order by creation time. Defaults to `"desc"`.
`pageToken`	string	No	Pagination token from a previous page. Usually omitted — iteration handles paging.

getSession

client.getSession({ sessionId }) -> Promise<AgentSession>

Fetch an existing session by ID.

Param	Type	Required	Description
`sessionId`	string	Yes	Session ID to retrieve.

AgentSession

The conversation context for a saved agent. Turns created within a session are chained automatically. Key members:

Member	Type	Description
`id`	string	Unique session identifier. Persist it to resume later via `client.getSession({ sessionId })`.
`agentName`	string	Name of the saved agent this session belongs to.
`title`	string \| undefined	Optional human-readable title for the session.
`createdBySubject`	`Subject`	Subject (user / service account) that created this session.
`createdAt`	string	ISO-8601 timestamp of session creation.
`updatedAt`	string	ISO-8601 timestamp of the last session update.
`prepareTurn(...)`	method	Stage a turn locally and return a `PreparedTurn` with no network call. Start it with `execute({ stream: true })` (stream events) or `execute({ stream: false })` (wait for terminal state). See `prepareTurn`.
`listTurns(...)`	method	Return a `Page<Turn>` of turns in this session (default order: newest-first). Async-iterate the page to walk every turn.
`getTurn({ turnId })`	method	Fetch a single `Turn` by ID.
`cancel()`	method	Cancel the session and any currently running turn. Idempotent.

prepareTurn

session.prepareTurn({ input?, previousTurnId? }) -> PreparedTurn

Stage a turn in the session. Makes no network call and returns a PreparedTurn with no id yet. The turn is created server-side on the first execute() call:

execute({ stream: true }) — POST createTurn and stream the SSE response as { sequenceNumber, event } data objects.
execute({ stream: false, pollIntervalMs? }) — POST createTurn without streaming, then poll until the turn reaches a terminal state.

After execute() starts the turn, call stream(), refresh(), waitForCompletion(), listEvents(), or cancel() on the same object. Calling those methods before execute() raises.

Param	Type	Required	Description
`input`	`TurnInputItem[]`	No	Input items for this turn. See Turn input. Omit to resume after `mcp.auth_required`.
`previousTurnId`	`string` \| `"auto"`	No	Turn chaining point. Defaults to `"auto"`.

PreparedTurn

Output of prepareTurn(). Not yet started — no HTTP until execute(). Identity fields delegate to the inner Turn once started (undefined until then).

Member	Type	Description
`id`	string \| undefined	Turn ID. Undefined until `execute()` starts the turn.
`session`	`AgentSession`	The session this turn belongs to.
`previousTurnId`	string \| undefined	Turn ID this turn chains from. Undefined until started.
`createdBySubject`	`Subject` \| undefined	Subject that created this turn. Undefined until started.
`createdAt`	string \| undefined	ISO-8601 timestamp of turn creation. Undefined until started.
`input`	`TurnInputItem[]` \| undefined	The Turn input passed to `prepareTurn()`, if any.
`state`	`TurnState` \| undefined	Cached lifecycle state. Undefined until started; use `refresh()` to refresh.
`execute({ stream: true })`	method	Start the turn and stream SSE data until terminal. Returns `AsyncIterable<TurnStreamData>`. Each item has `{ sequenceNumber, event }`.
`execute({ stream: false, pollIntervalMs? })`	method	Start the turn without streaming and block until terminal. Returns `Promise<TurnState>`. Default poll interval is 3000 ms (minimum 3000 ms).
`stream({ afterSequenceNumber? })`	method	Reconnect to a running turn’s live SSE stream after `execute()` has started it. Yields the same `{ sequenceNumber, event }` shape. Raises if the turn has not been started.
`refresh()`	method	Refetch lifecycle state from the server and return `this`. Raises if the turn has not been started.
`waitForCompletion({ pollIntervalMs? })`	method	Block until the turn reaches a terminal state. Raises if the turn has not been started.
`listEvents(...)`	method	Return a paginated snapshot of stored events. Async-iterate the returned `Page`. Raises if the turn has not been started.
`cancel()`	method	Request cancellation. Raises if the turn has not been started.

Turn

A started turn returned by listTurns(), getTurn(), or after PreparedTurn.execute(). Same methods as PreparedTurn except there is no execute() — the turn already exists server-side.

Member	Type	Description
`id`	string	Unique turn identifier (UUIDv7).
`session`	`AgentSession`	The session this turn belongs to.
`previousTurnId`	string \| undefined	Turn ID this turn chains from, or undefined for the first turn.
`createdBySubject`	`Subject`	Subject (user / service account) that created this turn.
`createdAt`	string	ISO-8601 timestamp of turn creation.
`input`	`TurnInputItem[]` \| undefined	The Turn input that triggered this turn, if any.
`state`	`TurnState`	Cached lifecycle state (`running`, `done`, `cancelled`, or `error`). Updated in place by `stream()` and `refresh()`.
`stream({ afterSequenceNumber? })`	method	Subscribe to the turn’s live SSE stream. Resumes after `afterSequenceNumber` (default `0`). Closes when the turn reaches a terminal state.
`refresh()`	method	Refetch state from the server and return `this`.
`waitForCompletion({ pollIntervalMs? })`	method	Block until terminal. Returns immediately if already terminal.
`listEvents(...)`	method	Paginated snapshot of stored events. Pass `order: "asc"` to replay forward.
`cancel()`	method	Request cancellation. Idempotent on terminal turns.

To define or configure the agent itself, see Create an agent.

​Turn input

​UserMessage

​UserMessageContentItem

​UserToolApprovalEvent

​UserToolResponseEvent

​Reference

​Python reference

​Low-level reference (TrueFoundryGateway)

​create

​list

​get

​cancel

​Session

​create_turn

​list_turns

​get_turn

​Turn

​subscribe_to_turn

​list_turn_events

​TypeScript reference

​createSession

​listSessions

​getSession

​AgentSession

​prepareTurn

​PreparedTurn

​Turn

Turn input

UserMessage

UserMessageContentItem

UserToolApprovalEvent

UserToolResponseEvent

Reference

Python reference

Low-level reference (`TrueFoundryGateway`)

create

list

get

cancel

Session

create_turn

list_turns

get_turn

Turn

subscribe_to_turn

list_turn_events

TypeScript reference

createSession

listSessions

getSession

AgentSession

prepareTurn

PreparedTurn

Turn