Runtime API reference

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

Use an agent uses TrueFoundryGateway (client.agents.sessions.*). create_turn_stream / createTurnStream returns a Stream of TurnStreamingEvent. Iterate the stream for event bodies; use Python .with_metadata() / TypeScript .withMetadata() to also read the SSE id (sequence number for resume). create_turn / createTurn returns the turn object immediately (no events). Turn input JSON shapes are the same in every language.

Python
TypeScript

`TrueFoundryGateway`

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"],
)

Access methods via client.agents.sessions.*.

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")
  -> GetTurnResponse

Start or continue a turn within a session. Returns the turn object immediately (no SSE). The turn may still be running — use get_turn or create_turn_stream when you need terminal state or events.

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"` \| `"none"`	No	Turn chaining point. Defaults to `"auto"`, letting the server chain to the latest turn.

create_turn_stream

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

Start or continue a turn within a session. Responds with a Server-Sent Events stream (Stream[TurnStreamingEvent]). Iterating yields typed event bodies; .with_metadata() yields StreamEvent items with .id (SSE id) and .data (typed body) for resume. 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"` \| `"none"`	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)
  -> Stream[TurnStreamingEvent]

Reconnect to a running turn’s live SSE stream. Pass after_sequence_number to resume after a known point. Use .with_metadata() to read the SSE id while reconnecting. 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"`.

list_events

client.agents.sessions.list_events(session_id, page_token=None, last_turn_id=None, limit=100)
  -> SyncPager[SessionEventItem, ListSessionEventsResponse]

Return a paginated snapshot of stored events across turns in a session.

Param	Type	Required	Description
`session_id`	string	Yes	Session whose events to list.
`page_token`	string	No	Pagination token from a previous page.
`last_turn_id`	string	No	Resume listing after this turn ID.
`limit`	int	No	Number of events fetched per page (not a total cap).

`TrueFoundryGateway`

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

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

Access methods via client.agents.sessions.*. Request types use camelCase; wire JSON uses snake_case.

create

client.agents.sessions.create({ agentName }) -> Promise<GetSessionResponse>

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

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

list

client.agents.sessions.list({ agentName, limit?, order?, pageToken?, startTimestamp?, endTimestamp? })
  -> Promise<Page<Session>>

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

Param	Type	Required	Description
`agentName`	string	Yes	Filter to sessions for a specific named agent.
`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.
`startTimestamp`	string	No	ISO-8601 lower bound on session creation time.
`endTimestamp`	string	No	ISO-8601 upper bound on session creation time.

get

client.agents.sessions.get(sessionId) -> Promise<GetSessionResponse>

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

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

cancel

client.agents.sessions.cancel(sessionId) -> Promise<CancelSessionResponse>

Cancel the running turn for a session. Idempotent.

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

Session

The conversation context for a saved agent, returned by create and get in .data.

Member	Type	Description
`id`	string	Unique session identifier. Persist it to resume later via `get`.
`agentName`	string	Name of the saved agent this session belongs to.
`title`	string \| null	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.

createTurn

client.agents.sessions.createTurn(sessionId, { input?, previousTurnId? })
  -> Promise<GetTurnResponse>

Start or continue a turn within a session. Returns the turn object immediately (no SSE). The turn may still be running — use getTurn or createTurnStream when you need terminal state or events.

Param	Type	Required	Description
`sessionId`	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`.
`previousTurnId`	`string` \| `"auto"` \| `"none"`	No	Turn chaining point. Defaults to `"auto"`.

createTurnStream

client.agents.sessions.createTurnStream(sessionId, { input?, previousTurnId? })
  -> Promise<Stream<TurnStreamingEvent>>

Start or continue a turn within a session. Responds with a Server-Sent Events stream (Stream<TurnStreamingEvent>). Iterating yields typed event bodies; .withMetadata() yields ServerSentEvent items with .id (SSE id) and .data (typed body) for resume. The first event is turn.created; the stream closes with turn.done.

Param	Type	Required	Description
`sessionId`	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`.
`previousTurnId`	`string` \| `"auto"` \| `"none"`	No	Turn chaining point. Defaults to `"auto"`.

listTurns

client.agents.sessions.listTurns(sessionId, { pageToken?, limit? })
  -> Promise<Page<Turn>>

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

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

getTurn

client.agents.sessions.getTurn(sessionId, turnId) -> Promise<GetTurnResponse>

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

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

Turn

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

Member	Type	Description
`id`	string	Unique turn identifier (UUIDv7).
`sessionId`	string	The session this turn belongs to.
`previousTurnId`	string \| null	Turn ID this turn chains from, or `null` 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`). Refetch with `getTurn`.

subscribeToTurn

client.agents.sessions.subscribeToTurn(sessionId, turnId, { afterSequenceNumber? })
  -> Promise<Stream<TurnStreamingEvent>>

Reconnect to a running turn’s live SSE stream. Pass afterSequenceNumber to resume after a known point. Use .withMetadata() to read the SSE id while reconnecting. Closes when the turn reaches a terminal state. Use listTurnEvents for completed turns.

Param	Type	Required	Description
`sessionId`	string	Yes	Session the turn belongs to.
`turnId`	string	Yes	Turn to subscribe to.
`afterSequenceNumber`	number	No	Resume after this sequence number.

listTurnEvents

client.agents.sessions.listTurnEvents(sessionId, turnId, { pageToken?, limit?, order? })
  -> Promise<Page<TurnEvent>>

Return a paginated snapshot of stored events for a completed turn. Pass order: "asc" to replay forward.

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

listEvents

client.agents.sessions.listEvents(sessionId, { pageToken?, lastTurnId?, limit? })
  -> Promise<Page<SessionEventItem>>

Return a paginated snapshot of stored events across turns in a session.

Param	Type	Required	Description
`sessionId`	string	Yes	Session whose events to list.
`pageToken`	string	No	Pagination token from a previous page.
`lastTurnId`	string	No	Resume listing after this turn ID.
`limit`	number	No	Number of events fetched per page (not a total cap).

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

Agent Harness

Agent Governance

Turn input

UserMessage

UserMessageContentItem

UserToolApprovalEvent

UserToolResponseEvent

Reference

`TrueFoundryGateway`

create

list

get

cancel

Session

create_turn

create_turn_stream

list_turns

get_turn

Turn

subscribe_to_turn

list_turn_events

list_events

`TrueFoundryGateway`

create

list

get

cancel

Session

createTurn

createTurnStream

listTurns

getTurn

Turn

subscribeToTurn

listTurnEvents

listEvents

​Turn input

​UserMessage

​UserMessageContentItem

​UserToolApprovalEvent

​UserToolResponseEvent

​Reference

​TrueFoundryGateway

​create

​list

​get

​cancel

​Session

​create_turn

​create_turn_stream

​list_turns

​get_turn

​Turn

​subscribe_to_turn

​list_turn_events

​list_events

​TrueFoundryGateway

​create

​list

​get

​cancel

​Session

​createTurn

​createTurnStream

​listTurns

​getTurn

​Turn

​subscribeToTurn

​listTurnEvents

​listEvents

Turn input

UserMessage

UserMessageContentItem

UserToolApprovalEvent

UserToolResponseEvent

Reference

`TrueFoundryGateway`

create

list

get

cancel

Session

create_turn

create_turn_stream

list_turns

get_turn

Turn

subscribe_to_turn

list_turn_events

list_events

`TrueFoundryGateway`

create

list

get

cancel

Session

createTurn

createTurnStream

listTurns

getTurn

Turn

subscribeToTurn

listTurnEvents

listEvents