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

Prefer the high-level AgentSessionClient for application code — same prepare_turn / prepareTurn → execute model as Use an agent. Use the low-level TrueFoundryGateway client when you need raw Fern types or direct SSE control. High-level streaming yields { sequence_number, event } (Python) / { sequenceNumber, event } (TypeScript). Low-level create_turn / createTurn yields raw TurnStreamingEvent values. Turn input JSON shapes are the same in every language.

Python
TypeScript

High-level (`AgentSessionClient`)

import os
from truefoundry_gateway_sdk.agents import AgentSessionClient
from truefoundry_gateway_sdk.types import UserMessage

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=[UserMessage(content="Hello")])
for data in turn.execute(stream=True):
    print(data.sequence_number, data.event)

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.

create_session

client.create_session(agent_name=...) -> AgentSession

Create a conversation AgentSession for a saved agent.

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

list_sessions

client.list_sessions(agent_name=..., limit=10, order=None, page_token=None, start_timestamp=None, end_timestamp=None)
  -> SyncPager[AgentSession, ListSessionsResponse]

List AgentSession objects 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_session

client.get_session(session_id) -> AgentSession

Fetch an existing session by ID.

Param	Type	Required	Description
`session_id`	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.get_session(session_id)`.
`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.
`prepare_turn(...)`	method	Stage a turn locally and return a `PreparedTurn` with no network call. See `prepare_turn`.
`list_turns(...)`	method	Return a pager of turns in this session (default order: newest-first).
`get_turn(turn_id)`	method	Fetch a single `Turn` by ID.
`list_events(...)`	method	Paginated snapshot of stored session events across turns.
`cancel()`	method	Cancel the currently running turn for this session. Idempotent.

prepare_turn

session.prepare_turn(input=None, previous_turn_id="auto") -> 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 create_turn and stream SSE as TurnStreamData (sequence_number, event).
execute(stream=False, poll_interval_ms=...) — POST create_turn, then poll until the turn reaches a terminal state. Default / minimum poll interval is 3000 ms.

After execute() starts the turn, call stream(), refresh(), wait_for_completion(), list_events(), 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`.
`previous_turn_id`	`string` \| `"auto"` \| `"none"`	No	Turn chaining point. Defaults to `"auto"`, letting the server chain to the latest turn. Pass `"none"` to start an unchained turn, or a specific turn ID.

PreparedTurn

Output of prepare_turn(). Not yet started — no HTTP until execute(). Identity fields are None until started.

Member	Type	Description
`id`	string \| None	Turn ID. `None` until `execute()` starts the turn.
`session`	`AgentSession`	The session this turn belongs to.
`previous_turn_id`	string \| None	Turn ID this turn chains from. `None` until started.
`created_by_subject`	`Subject` \| None	Subject that created this turn. `None` until started.
`created_at`	string \| None	ISO-8601 timestamp of turn creation. `None` until started.
`input`	`TurnInputItem[]` \| None	The Turn input passed to `prepare_turn()`, if any.
`state`	`TurnState` \| None	Cached lifecycle state. `None` until started; use `refresh()` to refresh.
`execute(stream=True)`	method	Start the turn and stream SSE data until terminal. Returns `Iterator[TurnStreamData]`. Each item has `sequence_number` and `event`.
`execute(stream=False, poll_interval_ms=...)`	method	Start the turn without streaming and block until terminal. Returns `TurnState`.
`stream(after_sequence_number=...)`	method	Reconnect to a running turn’s live SSE stream after `execute()` has started it. Raises if the turn has not been started.
`refresh()`	method	Refetch lifecycle state from the server and return `self`. Raises if the turn has not been started.
`wait_for_completion(poll_interval_ms=...)`	method	Block until the turn reaches a terminal state. Raises if the turn has not been started.
`list_events(...)`	method	Return a paginated snapshot of stored events. 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 list_turns(), get_turn(), 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.
`session_id`	string	The session ID 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`). Updated in place by `stream()` and `refresh()`.
`stream(after_sequence_number=...)`	method	Subscribe to the turn’s live SSE stream. Closes when the turn reaches a terminal state.
`refresh()`	method	Refetch state from the server and return `self`.
`wait_for_completion(poll_interval_ms=...)`	method	Block until terminal. Returns immediately if already terminal.
`list_events(...)`	method	Paginated snapshot of stored events. Pass `order="asc"` to replay forward.
`cancel()`	method	Request cancellation. Idempotent on terminal turns.

Low-level (`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"],
)

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")
  -> 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"` \| `"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)
  -> 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"`.

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).

High-level (`AgentSessionClient`)

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

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

const session = await client.createSession({ agentName: "support-bot" });
const turn = session.prepareTurn({
  input: [{ type: "user.message", content: "Hello" }],
});
for await (const data of turn.execute({ stream: true })) {
  console.log(data.sequenceNumber, data.event);
}

Import event types and helpers (isEventDelta, mergeEventDelta) from truefoundry-gateway-sdk/agents.

createSession

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

Create a conversation AgentSession for a saved agent.

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

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 \| 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.
`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.
`listEvents(...)`	method	Paginated snapshot of stored session events across turns.
`cancel()`	method	Cancel the currently running turn for this session. 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, 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"` \| `"none"`	No	Turn chaining point. Defaults to `"auto"`. Pass `"none"` to start an unchained turn, or a specific turn ID.

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 \| 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`). 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.

Low-level (`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<Stream<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
`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. 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.

​Turn input

​UserMessage

​UserMessageContentItem

​UserToolApprovalEvent

​UserToolResponseEvent

​Reference

​High-level (AgentSessionClient)

​create_session

​list_sessions

​get_session

​AgentSession

​prepare_turn

​PreparedTurn

​Turn

​Low-level (TrueFoundryGateway)

​create

​list

​get

​cancel

​Session

​create_turn

​list_turns

​get_turn

​Turn

​subscribe_to_turn

​list_turn_events

​list_events

​High-level (AgentSessionClient)

​createSession

​listSessions

​getSession

​AgentSession

​prepareTurn

​PreparedTurn

​Turn

​Low-level (TrueFoundryGateway)

​create

​list

​get

​cancel

​Session

​createTurn

​listTurns

​getTurn

​Turn

​subscribeToTurn

​listTurnEvents

​listEvents

Turn input

UserMessage

UserMessageContentItem

UserToolApprovalEvent

UserToolResponseEvent

Reference

High-level (`AgentSessionClient`)

create_session

list_sessions

get_session

AgentSession

prepare_turn

PreparedTurn

Turn

Low-level (`TrueFoundryGateway`)

create

list

get

cancel

Session

create_turn

list_turns

get_turn

Turn

subscribe_to_turn

list_turn_events

list_events

High-level (`AgentSessionClient`)

createSession

listSessions

getSession

AgentSession

prepareTurn

PreparedTurn

Turn

Low-level (`TrueFoundryGateway`)

create

list

get

cancel

Session

createTurn

listTurns

getTurn

Turn

subscribeToTurn

listTurnEvents

listEvents