Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

73.3 KB
Raw Blame

Reference

Internal

client.internal.list_permissions(...) -> ListPermissionsResponse

πŸ“ Description

Return granted actions for the requested resources.

πŸ”Œ Usage

from trueforge_sdk import TrueForge, PermissionResourceType

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

client.internal.list_permissions(
    resource_ids=[
        "resource_ids"
    ],
    resource_type=PermissionResourceType.AGENT,
)

βš™οΈ Parameters

resource_ids: typing.List[str] β€” Resource ids of resource_type to evaluate.

resource_type: PermissionResourceType

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Agents

client.agents.list(...) -> ListAgentsResponse

πŸ“ Description

List configured agents for the tenant, ordered by name. Optional agent_name filters by substring.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.agents.list()

βš™οΈ Parameters

limit: typing.Optional[int] β€” Page size. Defaults to 50, max 100.

page_token: typing.Optional[str] β€” Opaque token from a previous response next_page_token.

agent_name: typing.Optional[str] β€” Case-insensitive substring match on agent name.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.agents.create(...) -> GetAgentResponse

πŸ“ Description

Creates an agent and allocates an immutable id. Fails if name is already taken. Name cannot be changed later.

πŸ”Œ Usage

from trueforge_sdk import TrueForge, AgentSpec, Model

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

client.agents.create(
    description="description",
    manifest=AgentSpec(
        model=Model(
            name="name",
        ),
    ),
    name="name",
)

βš™οΈ Parameters

description: str

manifest: AgentSpec

name: ResourceName

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.agents.get(...) -> GetAgentResponse

πŸ“ Description

Fetch a configured agent by immutable id.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.agents.get(
    agent_id="agent_id",
)

βš™οΈ Parameters

agent_id: str β€” Immutable agent identifier.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.agents.update(...) -> GetAgentResponse

πŸ“ Description

Update an existing agent by immutable id.

πŸ”Œ Usage

from trueforge_sdk import TrueForge, AgentSpec, Model

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

client.agents.update(
    agent_id="agent_id",
    manifest=AgentSpec(
        model=Model(
            name="name",
        ),
    ),
)

βš™οΈ Parameters

agent_id: str β€” Immutable agent identifier.

manifest: AgentSpec

description: typing.Optional[str]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.agents.delete(...) -> DeleteAgentResponse

πŸ“ Description

Delete a configured agent by immutable id.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.agents.delete(
    agent_id="agent_id",
)

βš™οΈ Parameters

agent_id: str β€” Immutable agent identifier.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Auth

client.auth.me() -> GetMeResponse

πŸ“ Description

Returns the authenticated caller identity (type, tenant_id, subject, roles) wrapped as { data }. type is oidc-connected when browser OIDC is enabled, otherwise default. When auth is enabled this requires a valid id_token cookie or Authorization: Bearer token (401 otherwise). When auth is disabled, returns the standalone default identity.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.auth.me()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Server

client.server.get_capabilities() -> GetCapabilitiesResponse

πŸ“ Description

Report optional runtime capabilities available for this tenant.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.server.get_capabilities()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

MCP Servers

client.mcp_servers.list() -> ListAvailableMcpServersResponse

πŸ“ Description

Configured MCP servers as a slim name/url list for the composer.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.mcp_servers.list()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.mcp_servers.get(...) -> GetAvailableMcpServerResponse

πŸ“ Description

A single MCP server as the slim chat projection, with live per-user auth_status.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.mcp_servers.get(
    name="name",
)

βš™οΈ Parameters

name: str β€” MCP server name.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.mcp_servers.authorize(...) -> McpAuthStatus

πŸ“ Description

Returns current auth status. When OAuth is required, includes an authorization URL. Optional return_to is the post-consent landing path.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.mcp_servers.authorize(
    name="name",
)

βš™οΈ Parameters

name: str β€” MCP server name.

return_to: typing.Optional[str] β€” Same-origin path to land in the browser after consent.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.mcp_servers.delete_authorization(...) -> GetMcpServerResponse

πŸ“ Description

Disconnects OAuth for the MCP server when applicable and returns the updated server with auth_status. No-op when the server does not use stored OAuth tokens.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.mcp_servers.delete_authorization(
    name="name",
)

βš™οΈ Parameters

name: str β€” MCP server name.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.mcp_servers.list_tools(...) -> ListMcpServerToolsResponse

πŸ“ Description

All tools exposed by the given MCP server (non-paginated), as returned by the MCP tools/list call.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.mcp_servers.list_tools(
    name="name",
)

βš™οΈ Parameters

name: str β€” MCP server name.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Models

client.models.list() -> ListAvailableModelsResponse

πŸ“ Description

Configured models as a slim FQN list for the composer.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.models.list()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

SandboxEnvironments

client.sandbox_environments.list(...) -> ListSandboxEnvironmentsResponse

πŸ“ Description

List available sandbox environments

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.sandbox_environments.list()

βš™οΈ Parameters

limit: typing.Optional[int] β€” Page size. Defaults to 25, max 1000.

page_token: typing.Optional[str] β€” Opaque token from a previous response next_page_token.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.sandbox_environments.create(...) -> GetSandboxEnvironmentResponse

πŸ“ Description

Creates by manifest.name. Fails if the name is already taken. Requires a configured sandbox provider.

πŸ”Œ Usage

from trueforge_sdk import TrueForge, SandboxEnvironmentManifestRequest

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

client.sandbox_environments.create(
    manifest=SandboxEnvironmentManifestRequest(
        name="name",
    ),
)

βš™οΈ Parameters

manifest: SandboxEnvironmentManifestRequest

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.sandbox_environments.create_or_update(...) -> GetSandboxEnvironmentResponse

πŸ“ Description

Create a new sandbox environment or update an existing one.

πŸ”Œ Usage

from trueforge_sdk import TrueForge, SandboxEnvironmentManifestRequest

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

client.sandbox_environments.create_or_update(
    manifest=SandboxEnvironmentManifestRequest(
        name="name",
    ),
)

βš™οΈ Parameters

manifest: SandboxEnvironmentManifestRequest

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.sandbox_environments.get(...) -> GetSandboxEnvironmentResponse

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.sandbox_environments.get(
    name="name",
)

βš™οΈ Parameters

name: str β€” Sandbox environment name.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.sandbox_environments.delete(...) -> DeleteSandboxEnvironmentResponse

πŸ“ Description

Delete a sandbox environment, fails if any agent still references it.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.sandbox_environments.delete(
    name="name",
)

βš™οΈ Parameters

name: str β€” Sandbox environment name.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Schedules

client.schedules.list(...) -> ListSchedulesResponse

πŸ“ Description

List schedules for the tenant, newest first.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.schedules.list()

βš™οΈ Parameters

limit: typing.Optional[int] β€” Page size. Defaults to 25

page_token: typing.Optional[str] β€” Opaque token from a previous response next_page_token.

agent_names: typing.Optional[str] β€” Filter by one or more agent names (comma-separated). When set, at least one name is required.

created_by_me: typing.Optional[bool] β€” When true, only schedules created by the authenticated subject.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.schedules.create(...) -> GetScheduleResponse

πŸ“ Description

Create a schedule for an existing agent (by name) and add its first pending run when active.

πŸ”Œ Usage

from trueforge_sdk import TrueForge, ScheduleManifest

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

client.schedules.create(
    agent_name="agent_name",
    manifest=ScheduleManifest(
        cron="cron",
        task="task",
    ),
    name="name",
)

βš™οΈ Parameters

agent_name: ResourceName

manifest: ScheduleManifest

name: ResourceName

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.schedules.create_run(...) -> CreateScheduleRunResponse

πŸ“ Description

Start a schedule run immediately using the schedule task. Does not replace or advance the cron pending run.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.schedules.create_run(
    schedule_id="schedule_id",
)

βš™οΈ Parameters

schedule_id: str β€” Immutable schedule identifier.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.schedules.get(...) -> GetScheduleResponse

πŸ“ Description

Get a schedule by id.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.schedules.get(
    schedule_id="schedule_id",
)

βš™οΈ Parameters

schedule_id: str β€” Immutable schedule identifier.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.schedules.update(...) -> GetScheduleResponse

πŸ“ Description

Replace name and manifest; replaces or drops the pending run when status/cron/timezone change.

πŸ”Œ Usage

from trueforge_sdk import TrueForge, ScheduleManifest

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

client.schedules.update(
    schedule_id="schedule_id",
    manifest=ScheduleManifest(
        cron="cron",
        task="task",
    ),
    name="name",
)

βš™οΈ Parameters

schedule_id: str β€” Immutable schedule identifier.

manifest: ScheduleManifest

name: ResourceName

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.schedules.delete(...) -> DeleteScheduleResponse

πŸ“ Description

Delete a schedule and its runs. Idempotent.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.schedules.delete(
    schedule_id="schedule_id",
)

βš™οΈ Parameters

schedule_id: str β€” Immutable schedule identifier.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.schedules.list_runs(...) -> ListScheduleRunsResponse

πŸ“ Description

List runs of a schedule, newest scheduled_for first. Available to its creator or a manager of its agent.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.schedules.list_runs(
    schedule_id="schedule_id",
)

βš™οΈ Parameters

schedule_id: str β€” Immutable schedule identifier.

limit: typing.Optional[int] β€” Page size. Defaults to 25

page_token: typing.Optional[str] β€” Opaque token from a previous response next_page_token.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Sessions

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

πŸ“ Description

List the sessions (newest first by default).

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.sessions.list()

βš™οΈ Parameters

limit: typing.Optional[int] β€” Page size. Defaults to 25, max 25.

order: typing.Optional[ListSessionsOrder] β€” Sort sessions by updated_at. Defaults to "desc".

page_token: typing.Optional[str] β€” Opaque keyset cursor from a previous response next_page_token.

start_timestamp: typing.Optional[datetime.datetime] β€” Inclusive lower bound on created_at (ISO-8601 / RFC 3339).

end_timestamp: typing.Optional[datetime.datetime] β€” Inclusive upper bound on created_at (ISO-8601 / RFC 3339).

agent_id: typing.Optional[str] β€” When set, only sessions bound to this agent id are returned.

created_by_me: typing.Optional[bool] β€” When true, only sessions created by the authenticated subject.

metadata: typing.Optional[SessionMetadata] β€” Exact metadata pairs as metadata[key]=value. Sessions must contain all pairs.

source_type: typing.Optional[SessionSourceType] β€” When set, returns only sessions created by this source type.

source_id: typing.Optional[str] β€” When set, returns only sessions from this specific source. Requires source_type.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ“ Description

Create a session with agent as either { name } (named registry binding) or { spec: AgentSpec } (inline). Named sessions snapshot the agent name at create and resolve the live agent on each turn. Responses use { type: "reference", name, id } or { type: "inline", spec }.

πŸ”Œ Usage

from trueforge_sdk import TrueForge, SessionAgentNameRef

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

client.sessions.create(
    agent=SessionAgentNameRef(
        name="name",
    ),
)

βš™οΈ Parameters

agent: CreateSessionAgent

metadata: typing.Optional[SessionMetadata]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ“ Description

Fetch a session by ID. Allowed for the creator, a manager of the bound named agent, or any tenant member when the session is shared.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.sessions.get(
    session_id="session_id",
)

βš™οΈ Parameters

session_id: str β€” Session identifier.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.sessions.delete(...)

πŸ“ Description

Delete a session and all related turns, events, and internal state. Only the session creator may delete it. Idempotent if already gone.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.sessions.delete(
    session_id="session_id",
)

βš™οΈ Parameters

session_id: str β€” Session identifier.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.sessions.update(...) -> GetSessionResponse

πŸ“ Description

Update a session: optional title, metadata, shared, and (inline sessions only) agent as { spec: AgentSpec }. Named sessions reject agent updates. An empty body is a valid no-op that refreshes updated_at. Only the session creator may update it.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.sessions.update(
    session_id="session_id",
)

βš™οΈ Parameters

session_id: str β€” Session identifier.

agent: typing.Optional[SessionAgentSpecBody]

metadata: typing.Optional[SessionMetadata]

shared: typing.Optional[bool] β€” When true, any subject in the tenant may read this session and its turns/events by id.

title: typing.Optional[str] β€” Human-readable session title.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ“ Description

Cancel the running last turn for a session. Only the session creator may cancel.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.sessions.cancel(
    session_id="session_id",
)

βš™οΈ Parameters

session_id: str β€” Session identifier.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ“ Description

List session events as { turn_id, event } across the active turn branch (newest first), including persisted events from a running tip. Each turn contributes turn.created, content events (model.message, tool.call, …), and turn.done when terminal; streaming deltas are not included. Use page_token to paginate backward toward older events while retaining the original branch anchor. Allowed for the creator, a manager of the bound named agent, or any tenant member when the session is shared.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.sessions.list_events(
    session_id="session_id",
)

βš™οΈ Parameters

session_id: str β€” Session identifier.

page_token: typing.Optional[str] β€” Pagination cursor from pagination.next_page_token. It retains the branch anchor turn and returns older events toward the session start.

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.

limit: typing.Optional[int] β€” Page size. Defaults to 100, max 100.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ“ Description

List turns for a session (newest first by default), token-paginated. Allowed for the creator, a manager of the bound named agent, or any tenant member when the session is shared.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.sessions.list_turns(
    session_id="session_id",
)

βš™οΈ Parameters

session_id: str β€” Session identifier.

limit: typing.Optional[int] β€” Page size. Defaults to 25, max 25.

page_token: typing.Optional[str] β€” Opaque token from a previous response next_page_token.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.sessions.create_turn_stream(...) -> typing.Iterator[bytes]

πŸ“ Description

Create a turn within a session and execute it. Only the session creator may create turns. When stream is true (default), respond with a Server-Sent Events stream of turn events. When stream is false, return the turn immediately with state.status: "running" while execution continues in the background; use get turn or subscribe to observe completion. Use previous_turn_id to chain to the session's last turn (defaults to auto); use none for a new root.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.sessions.create_turn_stream(
    session_id="session_id",
)

βš™οΈ Parameters

session_id: str β€” Session identifier.

stream: typing.Literal β€” When true (default), stream turn events as SSE. When false, return the running turn immediately.

input: typing.Optional[typing.List[TurnInputItem]] β€” Turn input items: user messages and/or approval/tool-response resumes. Do not mix user messages with approval or tool-response items.

previous_turn_id: typing.Optional[PreviousTurnIdInput]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.sessions.create_turn(...) -> GetTurnResponse

πŸ“ Description

Create a turn within a session and execute it. Only the session creator may create turns. When stream is true (default), respond with a Server-Sent Events stream of turn events. When stream is false, return the turn immediately with state.status: "running" while execution continues in the background; use get turn or subscribe to observe completion. Use previous_turn_id to chain to the session's last turn (defaults to auto); use none for a new root.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.sessions.create_turn_stream(
    session_id="session_id",
)

βš™οΈ Parameters

session_id: str β€” Session identifier.

stream: typing.Literal β€” When true (default), stream turn events as SSE. When false, return the running turn immediately.

input: typing.Optional[typing.List[TurnInputItem]] β€” Turn input items: user messages and/or approval/tool-response resumes. Do not mix user messages with approval or tool-response items.

previous_turn_id: typing.Optional[PreviousTurnIdInput]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ“ Description

Fetch a single turn by ID. Allowed for the creator, a manager of the bound named agent, or any tenant member when the session is shared.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.sessions.get_turn(
    session_id="session_id",
    turn_id="turn_id",
)

βš™οΈ Parameters

session_id: str β€” Session identifier.

turn_id: str β€” Turn identifier.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ“ Description

Download a file from the sandbox this turn ran in. Paths come from the assistant's sandbox_artifacts block. Only the session creator may download.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.sessions.download_sandbox_file(
    session_id="session_id",
    turn_id="turn_id",
    path="x",
)

βš™οΈ Parameters

session_id: str β€” Session identifier.

turn_id: str β€” Turn identifier.

path: str β€” Absolute or sandbox-working-directory-relative file path, as listed in the assistant's sandbox_artifacts block.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.sessions.list_turn_events(...) -> ListTurnEventsResponse

πŸ“ Description

Paginated persisted events for a turn (insertion order by default). Allowed for the creator, a manager of the bound named agent, or any tenant member when the session is shared.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.sessions.list_turn_events(
    session_id="session_id",
    turn_id="turn_id",
)

βš™οΈ Parameters

session_id: str β€” Session identifier.

turn_id: str β€” Turn identifier.

limit: typing.Optional[int] β€” Page size. Defaults to 100, max 100.

page_token: typing.Optional[str] β€” Opaque token from a previous response next_page_token.

order: typing.Optional[ListTurnEventsOrder] β€” Sort events by insertion order. Defaults to "asc".

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.sessions.create_turn_event(...) -> CreateTurnEventResponse

πŸ“ Description

Create events for a turn. Only the session creator may create them.

πŸ”Œ Usage

from trueforge_sdk import TrueForge, UserMcpAuthContinueInputEvent

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

client.sessions.create_turn_event(
    session_id="session_id",
    turn_id="turn_id",
    events=[
        UserMcpAuthContinueInputEvent(
            type="user.mcp_auth_continue",
        )
    ],
)

βš™οΈ Parameters

session_id: str β€” Session identifier.

turn_id: str β€” Turn identifier.

events: typing.List[TurnInboundEventItem] β€” One or more user events.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

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

πŸ“ Description

Subscribe to the live SSE stream for a turn. Only the session creator may subscribe. Pass after_sequence_number to resume after a disconnect (exclusive β€” events after this sequence number are replayed).

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.sessions.subscribe_to_turn(
    session_id="session_id",
    turn_id="turn_id",
)

βš™οΈ Parameters

session_id: str β€” Session identifier.

turn_id: str β€” Turn identifier.

after_sequence_number: typing.Optional[int] β€” Exclusive resume cursor: replay only events with a sequence number greater than this value. Omit to start from the beginning of the live buffer.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Skills

client.skills.list() -> ListAvailableSkillsResponse

πŸ“ Description

Configured skills as a slim name/description list for the composer.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.skills.list()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.skills.list_versions(...) -> ListSkillVersionsResponse

πŸ“ Description

Versions for one skill.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.skills.list_versions(
    name="name",
)

βš™οΈ Parameters

name: str β€” Skill name.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Catalogs McpServers

client.catalogs.mcp_servers.list() -> GetMcpServerCatalogResponse

πŸ“ Description

Shipped MCP server presets (discovery-only). Copy into PUT /settings/mcp-servers to configure.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.catalogs.mcp_servers.list()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Catalogs ModelProviders

client.catalogs.model_providers.list() -> GetModelProviderCatalogResponse

πŸ“ Description

Shipped model-provider presets (discovery-only). Copy into PUT /settings/model-providers to configure. Includes a custom sentinel with supported_reasoning_efforts.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.catalogs.model_providers.list()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Catalogs SandboxProviders

client.catalogs.sandbox_providers.list() -> GetSandboxProviderCatalogResponse

πŸ“ Description

Shipped sandbox-provider presets (discovery-only). Copy into PUT /settings/sandbox-providers to configure.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.catalogs.sandbox_providers.list()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Catalogs Skills

client.catalogs.skills.list() -> GetSkillCatalogResponse

πŸ“ Description

Shipped skill presets (discovery-only). Copy into PUT /settings/skills to configure.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.catalogs.skills.list()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Catalogs WebSearchProviders

client.catalogs.web_search_providers.list() -> GetWebSearchProviderCatalogResponse

πŸ“ Description

Shipped web-search provider presets.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.catalogs.web_search_providers.list()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Internal Metrics

client.internal.metrics.list_charts() -> GetSessionMetricsChartResponse

πŸ“ Description

List available session metric charts.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.internal.metrics.list_charts()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.internal.metrics.get_chart_data(...) -> GetSessionMetricsChartDataResponse

πŸ“ Description

Return one chart for the caller's sessions on a named agent over an inclusive creation-time window. Uses hourly buckets for windows up to 24 hours and daily UTC buckets otherwise.

πŸ”Œ Usage

from trueforge_sdk import TrueForge, SessionMetricsChartName
import datetime

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

client.internal.metrics.get_chart_data(
    agent_id="agent_id",
    start_timestamp=datetime.datetime.fromisoformat("2024-01-15T09:30:00+00:00"),
    end_timestamp=datetime.datetime.fromisoformat("2024-01-15T09:30:00+00:00"),
    chart_name=SessionMetricsChartName.SESSIONS_OVER_TIME,
)

βš™οΈ Parameters

agent_id: str β€” Named agent identifier.

start_timestamp: datetime.datetime β€” Inclusive lower bound on session created_at.

end_timestamp: datetime.datetime β€” Inclusive upper bound on session created_at.

chart_name: SessionMetricsChartName β€” Session metrics chart to return.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.internal.metrics.get_meters(...) -> GetSessionMetricsMeterResponse

πŸ“ Description

Aggregate the caller's session meters for a named agent over an inclusive creation-time window.

πŸ”Œ Usage

from trueforge_sdk import TrueForge
import datetime

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

client.internal.metrics.get_meters(
    agent_id="agent_id",
    start_timestamp=datetime.datetime.fromisoformat("2024-01-15T09:30:00+00:00"),
    end_timestamp=datetime.datetime.fromisoformat("2024-01-15T09:30:00+00:00"),
)

βš™οΈ Parameters

agent_id: str β€” Named agent identifier.

start_timestamp: datetime.datetime β€” Inclusive lower bound on session created_at.

end_timestamp: datetime.datetime β€” Inclusive upper bound on session created_at.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Internal SandboxEnvironments

client.internal.sandbox_environments.list_pending() -> ListPendingSandboxEnvironmentVersionsResponse

πŸ“ Description

Returns pending environment versions for the build controller.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.internal.sandbox_environments.list_pending()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.internal.sandbox_environments.progress(...)

πŸ“ Description

Registers or polls the snapshot build and updates version status.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.internal.sandbox_environments.progress(
    environment_version_id="environment_version_id",
)

βš™οΈ Parameters

environment_version_id: str β€” Version row id to progress.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Internal Schedules

client.internal.schedules.execute_run(...)

πŸ“ Description

Execute a persisted schedule run using its saved schedule and agent.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.internal.schedules.execute_run(
    schedule_run_id="schedule_run_id",
)

βš™οΈ Parameters

schedule_run_id: str β€” Immutable schedule run identifier.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Internal Sessions

client.internal.sessions.get_or_create_by_external_id(...) -> GetSessionResponse

πŸ“ Description

Idempotent get-or-create: returns the existing session for this external_id, or creates one

πŸ”Œ Usage

from trueforge_sdk import TrueForge, SessionAgentNameRef

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

client.internal.sessions.get_or_create_by_external_id(
    agent=SessionAgentNameRef(
        name="name",
    ),
    external_id="external_id",
)

βš™οΈ Parameters

agent: CreateSessionAgent

external_id: str β€” Caller-supplied id unique within the tenant.

source: typing.Optional[SessionSourceSchedule]

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Internal Agents

client.internal.agents.get_code_snippets(...) -> GetAgentCodeSnippetsResponse

πŸ“ Description

TrueForge SDK samples (TypeScript and Python, stream and non-stream) for a session and turn against this agent.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.internal.agents.get_code_snippets(
    agent_id="agent_id",
)

βš™οΈ Parameters

agent_id: str β€” Immutable agent identifier.

base_url: typing.Optional[str] β€” Public SDK base URL from the browser. When omitted, derived from the request origin and PUBLIC_BASE_URL.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Settings McpServers

client.settings.mcp_servers.list() -> ListMcpServersResponse

πŸ“ Description

Configured MCP servers with auth_status. Header secrets are redacted.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.settings.mcp_servers.list()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.settings.mcp_servers.create(...) -> GetMcpServerResponse

πŸ“ Description

Creates an MCP server by name. Fails if name is already taken. Runs DCR registration when auth.type is dcr. Header secrets: real value required; redacted with no stored value returns 400.

πŸ”Œ Usage

from trueforge_sdk import TrueForge, RemoteMcpServerManifest

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

client.settings.mcp_servers.create(
    manifest=RemoteMcpServerManifest(
        description="description",
        name="name",
        type="remote",
        url="url",
    ),
)

βš™οΈ Parameters

manifest: McpServerManifest

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.settings.mcp_servers.create_or_update(...) -> GetMcpServerResponse

πŸ“ Description

Create or replace by name. Header secrets: real value sets/rotates; redacted keeps existing (400 if none).

πŸ”Œ Usage

from trueforge_sdk import TrueForge, RemoteMcpServerManifest

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

client.settings.mcp_servers.create_or_update(
    manifest=RemoteMcpServerManifest(
        description="description",
        name="name",
        type="remote",
        url="url",
    ),
)

βš™οΈ Parameters

manifest: McpServerManifest

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.settings.mcp_servers.get(...) -> GetMcpServerResponse

πŸ“ Description

A single MCP server by name, with nested live auth_status (settings / admin projection). Header auth values are redacted.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.settings.mcp_servers.get(
    name="name",
)

βš™οΈ Parameters

name: str β€” MCP server name.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.settings.mcp_servers.delete(...) -> DeleteMcpServerResponse

πŸ“ Description

Deletes an MCP server by name, along with every stored OAuth token for it. Rejected while any agent still lists the server.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.settings.mcp_servers.delete(
    name="name",
)

βš™οΈ Parameters

name: str β€” MCP server name.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Settings ModelProviders

client.settings.model_providers.list() -> ListModelProvidersResponse

πŸ“ Description

All configured providers with nested manifests.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.settings.model_providers.list()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.settings.model_providers.create(...) -> GetModelProviderResponse

πŸ“ Description

Creates a provider (models included). Fails if name is already taken. Well-known types use type as name (one each); custom is named by the caller. auth.api_key: real value required; redacted with no stored secret returns 400.

πŸ”Œ Usage

from trueforge_sdk import TrueForge, AlibabaModelProvider, ModelProviderAuth, ConfiguredModel, ModelProperties

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

client.settings.model_providers.create(
    manifest=AlibabaModelProvider(
        auth=ModelProviderAuth(
            api_key="api_key",
        ),
        models=[
            ConfiguredModel(
                model_id="model_id",
                name="name",
                properties=ModelProperties(),
            )
        ],
        type="alibaba",
    ),
)

βš™οΈ Parameters

manifest: ModelProviderManifest

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.settings.model_providers.create_or_update(...) -> GetModelProviderResponse

πŸ“ Description

Create or replace a provider (models included). Well-known types use type as name (one each); custom is named by the caller. auth.api_key: real value sets/rotates; redacted keeps existing (400 if none).

πŸ”Œ Usage

from trueforge_sdk import TrueForge, AlibabaModelProvider, ModelProviderAuth, ConfiguredModel, ModelProperties

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

client.settings.model_providers.create_or_update(
    manifest=AlibabaModelProvider(
        auth=ModelProviderAuth(
            api_key="api_key",
        ),
        models=[
            ConfiguredModel(
                model_id="model_id",
                name="name",
                properties=ModelProperties(),
            )
        ],
        type="alibaba",
    ),
)

βš™οΈ Parameters

manifest: ModelProviderManifest

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.settings.model_providers.delete(...) -> DeleteModelProviderResponse

πŸ“ Description

Deletes a provider and every model it declares. Rejected while any agent still uses one of them.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.settings.model_providers.delete(
    name="name",
)

βš™οΈ Parameters

name: str β€” Model provider name.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Settings SandboxProviders

client.settings.sandbox_providers.get() -> GetSandboxProviderResponse

πŸ“ Description

The single configured sandbox provider for this tenant. auth.api_key is redacted.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.settings.sandbox_providers.get()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.settings.sandbox_providers.create_or_update(...) -> GetSandboxProviderResponse

πŸ“ Description

Upserts the single sandbox provider for this tenant: creates it or replaces its entire configuration. auth.api_key: real value sets/rotates; redacted keeps existing (400 if none).

πŸ”Œ Usage

from trueforge_sdk import TrueForge, SandboxProviderManifest, DaytonaSandboxProviderAuth

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

client.settings.sandbox_providers.create_or_update(
    manifest=SandboxProviderManifest(
        auth=DaytonaSandboxProviderAuth(
            api_key="api_key",
        ),
        auto_archive_interval_in_minutes=1,
        auto_delete_interval_in_minutes=1,
        auto_stop_interval_in_minutes=1,
        exec_timeout_ms=1,
        type="daytona",
    ),
)

βš™οΈ Parameters

manifest: SandboxProviderManifest

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Settings Skills

client.settings.skills.list() -> ListSkillsResponse

πŸ“ Description

All configured skills with nested manifests (settings / admin projection).

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.settings.skills.list()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.settings.skills.create(...) -> GetSkillResponse

πŸ“ Description

Creates a skill keyed by name. Fails if name is already taken.

πŸ”Œ Usage

from trueforge_sdk import TrueForge, GitSkill

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

client.settings.skills.create(
    manifest=GitSkill(
        description="description",
        name="name",
        ref="ref",
        type="git",
        url="url",
    ),
)

βš™οΈ Parameters

manifest: SkillManifest

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.settings.skills.create_or_update(...) -> GetSkillResponse

πŸ“ Description

Full upsert keyed by name: creates the skill or replaces its entire manifest.

πŸ”Œ Usage

from trueforge_sdk import TrueForge, GitSkill

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

client.settings.skills.create_or_update(
    manifest=GitSkill(
        description="description",
        name="name",
        ref="ref",
        type="git",
        url="url",
    ),
)

βš™οΈ Parameters

manifest: SkillManifest

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.settings.skills.delete(...) -> DeleteSkillResponse

πŸ“ Description

Deletes a skill by name. Rejected while any agent still lists the skill.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.settings.skills.delete(
    name="name",
)

βš™οΈ Parameters

name: str β€” Skill name.

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

Settings WebSearchProviders

client.settings.web_search_providers.get() -> GetWebSearchProviderResponse

πŸ“ Description

The configured provider for this tenant. auth.api_key is redacted when present.

πŸ”Œ Usage

from trueforge_sdk import TrueForge

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

client.settings.web_search_providers.get()

βš™οΈ Parameters

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.

client.settings.web_search_providers.create_or_update(...) -> GetWebSearchProviderResponse

πŸ“ Description

Upserts the single web search provider for this tenant. auth.api_key: real value sets/rotates; redacted keeps existing (400 if none).

πŸ”Œ Usage

from trueforge_sdk import TrueForge, WebSearchProviderManifest, ParallelWebSearchProviderAuth

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

client.settings.web_search_providers.create_or_update(
    manifest=WebSearchProviderManifest(
        auth=ParallelWebSearchProviderAuth(
            api_key="api_key",
        ),
        type="parallel",
    ),
)

βš™οΈ Parameters

manifest: WebSearchProviderManifest

request_options: typing.Optional[RequestOptions] β€” Request-specific configuration.