Skip to content

reference.md

Latest commit

 

History

History
1327 lines (916 loc) · 19.3 KB

reference.md

File metadata and controls

1327 lines (916 loc) · 19.3 KB
Raw

Reference

Private Agents

client.private.agents.download_sandbox_file(...) -> typing.Iterator[bytes]

📝 Description

Download a file produced by an agent inside a sandbox.

🔌 Usage

from truefoundry_gateway_sdk import TrueFoundryGateway

client = TrueFoundryGateway(
    api_key="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.private.agents.download_sandbox_file(
    sandbox_id="sandboxId",
    path="x",
)

⚙️ Parameters

sandbox_id: str — The sandbox containing the file.

path: str — Absolute path of the file inside the sandbox.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Private Agents Sessions

client.private.agents.sessions.list(...) -> ListSessionsResponse

📝 Description

List sessions for an agent (newest first by default), keyset-paginated. Pass page_token to fetch the next page, keeping the other query params constant.

🔌 Usage

from truefoundry_gateway_sdk import TrueFoundryGateway, ListSessionsOrder

client = TrueFoundryGateway(
    api_key="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.private.agents.sessions.list(
    agent_name="agent_name",
    limit=1,
    order=ListSessionsOrder.ASC,
    page_token="page_token",
    start_timestamp="start_timestamp",
    end_timestamp="end_timestamp",
)

⚙️ Parameters

agent_name: str — Agent whose sessions to list. Must exist in the tenant.

limit: typing.Optional[int] — Page size. Defaults to 10, max 100.

order: typing.Optional[ListSessionsOrder] — Sort sessions by creation time. Defaults to "desc".

page_token: typing.Optional[str] — Opaque token from a previous response next_page_token.

start_timestamp: typing.Optional[str] — Inclusive lower bound on created_at (ISO-8601). Defaults upstream to 30 min before end_timestamp.

end_timestamp: typing.Optional[str] — Inclusive upper bound on created_at (ISO-8601). Defaults upstream to now.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.private.agents.sessions.create(...) -> GetSessionResponse

📝 Description

Create a session for an existing named agent.

🔌 Usage

from truefoundry_gateway_sdk import TrueFoundryGateway

client = TrueFoundryGateway(
    api_key="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.private.agents.sessions.create(
    agent_name="agent_name",
)

⚙️ Parameters

agent_name: str — Name of an existing agent in the tenant.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

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

📝 Description

Get a session by id. Visible to the session owner or a manager of the session agent.

🔌 Usage

from truefoundry_gateway_sdk import TrueFoundryGateway

client = TrueFoundryGateway(
    api_key="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.private.agents.sessions.get(
    session_id="sessionId",
)

⚙️ Parameters

session_id: str — Session identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

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

📝 Description

Cancel the running last turn for a session.

🔌 Usage

from truefoundry_gateway_sdk import TrueFoundryGateway

client = TrueFoundryGateway(
    api_key="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.private.agents.sessions.cancel(
    session_id="01arz3ndektsv4rrffq69g5fav.g",
)

⚙️ Parameters

session_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.private.agents.sessions.list_events(...) -> ListSessionEventsResponse

📝 Description

List session events as { turn_id, event } across a turn hierarchy (newest first). Each turn contributes turn.created, content events (model.message, tool.call, …), and turn.done; streaming deltas are not included. last_turn_id (initial load only) sets the newest turn in the window plus its ancestors; omit to use the session last turn. If that turn is still running, it is excluded — listing anchors on its parent so persisted events are returned without overlapping the live stream; subscribe to the running turn for live events. An empty data array is returned when the anchor is a running first turn with no parent. Use page_token to paginate backward toward older events; chains longer than the stored ancestor window are walked via spill to the session root.

🔌 Usage

from truefoundry_gateway_sdk import TrueFoundryGateway

client = TrueFoundryGateway(
    api_key="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.private.agents.sessions.list_events(
    session_id="01arz3ndektsv4rrffq69g5fav.g",
    page_token="page_token",
    last_turn_id="last_turn_id",
    limit=1,
)

⚙️ Parameters

session_id: str

page_token: typing.Optional[str] — Pagination cursor from pagination.next_page_token. Returns older events before the cursor (toward session start). Decoded JSON: { turn_id, sequence_number }.

last_turn_id: typing.Optional[str] — Newest turn in the listing window (initial load only; ignored when page_token is set). Lists that turn and its ancestors, newest events first. Omit to use the session last turn. If the resolved turn is still running, its events are excluded and listing starts from its parent instead — subscribe to the running turn for live events. Returns empty data when the anchor is a running first turn with no parent.

limit: typing.Optional[int] — Max events per response. Default 100, max 100.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.private.agents.sessions.list_turns(...) -> ListTurnsResponse

📝 Description

List turns for a session (newest first). Pagination walks the ancestor chain from the session last turn, or from the turn in page_token when continuing.

🔌 Usage

from truefoundry_gateway_sdk import TrueFoundryGateway

client = TrueFoundryGateway(
    api_key="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.private.agents.sessions.list_turns(
    session_id="01arz3ndektsv4rrffq69g5fav.g",
    page_token="page_token",
    limit=1,
)

⚙️ Parameters

session_id: str

page_token: typing.Optional[str]

limit: typing.Optional[int] — Page size. Defaults to 10, max 25.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.private.agents.sessions.create_turn(...) -> typing.Iterator[bytes]

📝 Description

Start or continue a turn within a session. Responds with a Server-Sent Events stream. Use previous_turn_id to chain to the session's last turn (defaults to auto).

🔌 Usage

from truefoundry_gateway_sdk import TrueFoundryGateway

client = TrueFoundryGateway(
    api_key="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.private.agents.sessions.create_turn(
    session_id="01arz3ndektsv4rrffq69g5fav.g",
)

⚙️ Parameters

session_id: str

input: typing.Optional[typing.List[TurnInputItem]]

previous_turn_id: typing.Optional[PreviousTurnIdInput]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.private.agents.sessions.get_turn(...) -> GetTurnResponse

📝 Description

Get a single turn by ID from Redis.

🔌 Usage

from truefoundry_gateway_sdk import TrueFoundryGateway

client = TrueFoundryGateway(
    api_key="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.private.agents.sessions.get_turn(
    session_id="01arz3ndektsv4rrffq69g5fav.g",
    turn_id="01arz3ndektsv4rrffq69g5fav.g.ab12cd",
)

⚙️ Parameters

session_id: str

turn_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.private.agents.sessions.subscribe_to_turn(...) -> typing.Iterator[bytes]

📝 Description

Subscribe to the live SSE stream for a turn. Pass after_sequence_number to resume after disconnect or server timeout, or send Last-Event-Id when after_sequence_number is omitted.

🔌 Usage

from truefoundry_gateway_sdk import TrueFoundryGateway

client = TrueFoundryGateway(
    api_key="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.private.agents.sessions.subscribe_to_turn(
    session_id="01arz3ndektsv4rrffq69g5fav.g",
    turn_id="01arz3ndektsv4rrffq69g5fav.g.ab12cd",
)

⚙️ Parameters

session_id: str

turn_id: str

after_sequence_number: typing.Optional[int]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.private.agents.sessions.list_turn_events(...) -> ListEventsResponse

📝 Description

Paginated list of content turn events from the Redis events stream (model.message, tool.call, …). turn.created and turn.done are stored in the stream but excluded from this endpoint — use session list_events for lifecycle. Only available after the turn has reached a terminal state; use subscribe for running turns.

🔌 Usage

from truefoundry_gateway_sdk import TrueFoundryGateway, ListEventsOrder

client = TrueFoundryGateway(
    api_key="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.private.agents.sessions.list_turn_events(
    session_id="01arz3ndektsv4rrffq69g5fav.g",
    turn_id="01arz3ndektsv4rrffq69g5fav.g.ab12cd",
    page_token="page_token",
    limit=1,
    order=ListEventsOrder.ASC,
)

⚙️ Parameters

session_id: str

turn_id: str

page_token: typing.Optional[str]

limit: typing.Optional[int] — Page size. Defaults to 25, max 25.

order: typing.Optional[ListEventsOrder] — Sort events by creation time. Defaults to "asc".

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Private Agents Private DraftSessions

client.private.agents.private.draft_sessions.list(...) -> ListDraftSessionsResponse

📝 Description

List the caller-owned draft sessions (newest first by default), keyset-paginated. Optionally filter by agent_name. Pass page_token to fetch the next page, keeping the other query params constant.

🔌 Usage

from truefoundry_gateway_sdk import TrueFoundryGateway, ListDraftSessionsOrder

client = TrueFoundryGateway(
    api_key="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.private.agents.private.draft_sessions.list(
    agent_name="agent_name",
    limit=1,
    order=ListDraftSessionsOrder.ASC,
    page_token="page_token",
    start_timestamp="start_timestamp",
    end_timestamp="end_timestamp",
)

⚙️ Parameters

agent_name: typing.Optional[str] — Filter to drafts linked to this saved agent. Omit to list all of the caller-owned drafts.

limit: typing.Optional[int] — Page size. Defaults to 10, max 100.

order: typing.Optional[ListDraftSessionsOrder] — Sort draft sessions by creation time. Defaults to "desc".

page_token: typing.Optional[str] — Opaque token from a previous response next_page_token.

start_timestamp: typing.Optional[str] — Inclusive lower bound on created_at. Defaults upstream to 30 min before end_timestamp.

end_timestamp: typing.Optional[str] — Inclusive upper bound on created_at. Defaults upstream to now.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.private.agents.private.draft_sessions.create(...) -> GetDraftSessionResponse

📝 Description

Create a draft session holding an inline agent spec, optionally linked to a saved agent. Owner is the token subject.

🔌 Usage

from truefoundry_gateway_sdk import TrueFoundryGateway, AgentSpec, Model

client = TrueFoundryGateway(
    api_key="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.private.agents.private.draft_sessions.create(
    agent_spec=AgentSpec(
        model=Model(
            name="name",
        ),
    ),
)

⚙️ Parameters

agent_spec: AgentSpec

agent_name: typing.Optional[str] — Optionally link the draft to an existing saved agent in the tenant. Omit for a standalone draft.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.private.agents.private.draft_sessions.get(...) -> GetDraftSessionResponse

📝 Description

Get a draft session by id. Owner-only.

🔌 Usage

from truefoundry_gateway_sdk import TrueFoundryGateway

client = TrueFoundryGateway(
    api_key="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.private.agents.private.draft_sessions.get(
    draft_session_id="draftSessionId",
)

⚙️ Parameters

draft_session_id: str — Draft session identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.private.agents.private.draft_sessions.update(...) -> GetDraftSessionResponse

📝 Description

Update a draft session's inline spec. Owner-only. An empty body is a valid no-op that refreshes updated_at.

🔌 Usage

from truefoundry_gateway_sdk import TrueFoundryGateway

client = TrueFoundryGateway(
    api_key="<token>",
    base_url="https://yourhost.com/path/to/api",
)

client.private.agents.private.draft_sessions.update(
    draft_session_id="draftSessionId",
)

⚙️ Parameters

draft_session_id: str — Draft session identifier.

agent_spec: typing.Optional[AgentSpec]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.