> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Runtime API reference
> SDK methods for sessions and turns — TrueFoundryGateway, createTurn / createTurnStream, subscribeToTurn, listTurnEvents — plus turn input types.
For a guided walkthrough, see [SDK overview](/docs/agent-platform/agent-harness/sdk/overview).
## Turn input
Each Turn's `input` is a list of one of these types. Resuming a Turn paused by [`mcp.auth_required`](/docs/agent-platform/agent-harness/sdk/turn-events-reference#mcpauthrequiredevent) 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.
```json lines theme={"dark"}
{ "type": "user.message", "content": "I would like to file a support ticket." }
```
```json lines theme={"dark"}
{
"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](#usermessagecontentitem) (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:;base64,`. MIME type is parsed from the URI. |
***
### UserToolApprovalEvent
Sent to resume a turn paused by [`tool.approval_required`](/docs/agent-platform/agent-harness/sdk/turn-events-reference#toolapprovalrequiredevent). One item per pending tool call.
```json lines theme={"dark"}
{
"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`](/docs/agent-platform/agent-harness/sdk/turn-events-reference#toolresponserequiredevent). One item per pending tool call.
```json lines theme={"dark"}
{
"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](/docs/agent-platform/agent-harness/sdk/use-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](#turn-input) JSON shapes are the same in every language.
### `TrueFoundryGateway`
```python theme={"dark"}
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
```text lines theme={"dark"}
client.agents.sessions.create(agent_name=...) -> GetSessionResponse
```
Create a conversation [Session](#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
```text lines theme={"dark"}
client.agents.sessions.list(agent_name=..., limit=10, order=None, page_token=None, start_timestamp=None, end_timestamp=None)
-> SyncPager[Session, ListSessionsResponse]
```
List [Sessions](#session) 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
```text lines theme={"dark"}
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
```text lines theme={"dark"}
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`](#create) and [`get`](#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`](#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
```text lines theme={"dark"}
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`](#get_turn) or [`create_turn_stream`](#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](#turn-input). Omit to resume after [`mcp.auth_required`](/docs/agent-platform/agent-harness/sdk/turn-events-reference#mcpauthrequiredevent). |
| `previous_turn_id` | `string` \| `"auto"` \| `"none"` | No | Turn chaining point. Defaults to `"auto"`, letting the server chain to the latest turn. |
***
create\_turn\_stream
```text lines theme={"dark"}
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`](/docs/agent-platform/agent-harness/sdk/turn-events-reference#turncreatedevent); the stream closes with [`turn.done`](/docs/agent-platform/agent-harness/sdk/turn-events-reference#turndoneevent).
| 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](#turn-input). Omit to resume after [`mcp.auth_required`](/docs/agent-platform/agent-harness/sdk/turn-events-reference#mcpauthrequiredevent). |
| `previous_turn_id` | `string` \| `"auto"` \| `"none"` | No | Turn chaining point. Defaults to `"auto"`, letting the server chain to the latest turn. |
***
list\_turns
```text lines theme={"dark"}
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
```text lines theme={"dark"}
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`](#list_turns) and [`get_turn`](#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](#turn-input) that triggered this turn, if any. |
| `state` | `TurnState` | Cached lifecycle state (`running`, `done`, `cancelled`, or `error`). Refetch with [`get_turn`](#get_turn). |
***
subscribe\_to\_turn
```text lines theme={"dark"}
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`](#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
```text lines theme={"dark"}
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
```text lines theme={"dark"}
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`
```typescript theme={"dark"}
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
```text lines theme={"dark"}
client.agents.sessions.create({ agentName }) -> Promise
```
Create a conversation [Session](#session-1) 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
```text lines theme={"dark"}
client.agents.sessions.list({ agentName, limit?, order?, pageToken?, startTimestamp?, endTimestamp? })
-> Promise>
```
List [Sessions](#session-1) 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
```text lines theme={"dark"}
client.agents.sessions.get(sessionId) -> Promise
```
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
```text lines theme={"dark"}
client.agents.sessions.cancel(sessionId) -> Promise
```
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`](#create-1) and [`get`](#get-1) in `.data`.
| Member | Type | Description |
| ------------------ | -------------- | -------------------------------------------------------------------------- |
| `id` | string | Unique session identifier. Persist it to resume later via [`get`](#get-1). |
| `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
```text lines theme={"dark"}
client.agents.sessions.createTurn(sessionId, { input?, previousTurnId? })
-> Promise
```
Start or continue a turn within a session. Returns the turn object immediately (no SSE). The turn may still be `running` — use [`getTurn`](#getturn) or [`createTurnStream`](#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](#turn-input). Omit to resume after [`mcp.auth_required`](/docs/agent-platform/agent-harness/sdk/turn-events-reference#mcpauthrequiredevent). |
| `previousTurnId` | `string` \| `"auto"` \| `"none"` | No | Turn chaining point. Defaults to `"auto"`. |
***
#### createTurnStream
```text lines theme={"dark"}
client.agents.sessions.createTurnStream(sessionId, { input?, previousTurnId? })
-> Promise>
```
Start or continue a turn within a session. Responds with a Server-Sent Events stream (`Stream`). 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`](/docs/agent-platform/agent-harness/sdk/turn-events-reference#turncreatedevent); the stream closes with [`turn.done`](/docs/agent-platform/agent-harness/sdk/turn-events-reference#turndoneevent).
| Param | Type | Required | Description |
| ---------------- | -------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sessionId` | string | Yes | Session to run the turn in. |
| `input` | `TurnInputItem[]` | No | Input items for this turn. See [Turn input](#turn-input). Omit to resume after [`mcp.auth_required`](/docs/agent-platform/agent-harness/sdk/turn-events-reference#mcpauthrequiredevent). |
| `previousTurnId` | `string` \| `"auto"` \| `"none"` | No | Turn chaining point. Defaults to `"auto"`. |
***
#### listTurns
```text lines theme={"dark"}
client.agents.sessions.listTurns(sessionId, { pageToken?, limit? })
-> Promise>
```
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
```text lines theme={"dark"}
client.agents.sessions.getTurn(sessionId, turnId) -> Promise
```
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`](#listturns) and [`getTurn`](#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](#turn-input) that triggered this turn, if any. |
| `state` | `TurnState` | Cached lifecycle state (`running`, `done`, `cancelled`, or `error`). Refetch with [`getTurn`](#getturn). |
***
#### subscribeToTurn
```text lines theme={"dark"}
client.agents.sessions.subscribeToTurn(sessionId, turnId, { afterSequenceNumber? })
-> Promise>
```
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`](#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
```text lines theme={"dark"}
client.agents.sessions.listTurnEvents(sessionId, turnId, { pageToken?, limit?, order? })
-> Promise>
```
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
```text lines theme={"dark"}
client.agents.sessions.listEvents(sessionId, { pageToken?, lastTurnId?, limit? })
-> Promise>
```
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](/docs/agent-platform/agent-harness/sdk/create-agent).