The open-source agent harness - the runtime layer that turns an LLM into a working agent.
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 ofresource_typeto 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_namefilters 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 responsenext_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
nameis 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 }.typeisoidc-connectedwhen browser OIDC is enabled, otherwisedefault. When auth is enabled this requires a validid_tokencookie orAuthorization: Bearertoken (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/listcall.
-
π 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 responsenext_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 responsenext_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_forfirst. 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 responsenext_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 byupdated_at. Defaults to "desc".
-
page_token:
typing.Optional[str]β Opaque keyset cursor from a previous responsenext_page_token.
-
start_timestamp:
typing.Optional[datetime.datetime]β Inclusive lower bound oncreated_at(ISO-8601 / RFC 3339).
-
end_timestamp:
typing.Optional[datetime.datetime]β Inclusive upper bound oncreated_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
agentas 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)agentas{ spec: AgentSpec }. Named sessions reject agent updates. An empty body is a valid no-op that refreshesupdated_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. Usepage_tokento 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 frompagination.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 whenpage_tokenis 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 responsenext_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
streamis true (default), respond with a Server-Sent Events stream of turn events. Whenstreamis false, return the turn immediately withstate.status: "running"while execution continues in the background; use get turn or subscribe to observe completion. Useprevious_turn_idto chain to the session's last turn (defaults toauto); usenonefor 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
streamis true (default), respond with a Server-Sent Events stream of turn events. Whenstreamis false, return the turn immediately withstate.status: "running"while execution continues in the background; use get turn or subscribe to observe completion. Useprevious_turn_idto chain to the session's last turn (defaults toauto); usenonefor 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_artifactsblock. 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'ssandbox_artifactsblock.
-
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 responsenext_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_numberto 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
customsentinel withsupported_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 sessioncreated_at.
-
end_timestamp:
datetime.datetimeβ Inclusive upper bound on sessioncreated_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 sessioncreated_at.
-
end_timestamp:
datetime.datetimeβ Inclusive upper bound on sessioncreated_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 ifnameis already taken. Runs DCR registration whenauth.typeisdcr. 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
nameis already taken. Well-known types usetypeasname(one each);customis 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
typeasname(one each);customis 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_keyis 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 ifnameis 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_keyis 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.
-
-