AGagentsky

Start a plugin session [write]

Changed on

RFC-0155 §3. The session starts with only the plugin's skills (not the workspace's default skills) and its remote MCP servers, and its calls to connected apps are limited to the apps the plugin declared: any other app is refused (capability_denied, reason plugin_scope). agent defaults to the workspace's Sky. Answers the created session.

post/plugins/{name}/sessions

Request

  • Base URL
    https://api.agentsky.dev/v1
  • URL
    https://api.agentsky.dev/v1/plugins/{name}/sessions
  • Auth
    HTTP bearer

Path parameters

namestring required

Request body

messagestring required
agentstring
titlestring

Response

Created

idstring

sess_… identifier

agentIdstring nullable

The agent id (agent_…)

titlestring nullable
status'provisioning' | 'idle' | 'running' | 'terminated'

provisioning = the sandbox is booting or installing the environment's packages (a turn sent meanwhile waits for it); running = a turn is in flight; terminated = archived or the last runtime was destroyed. Use archived for the durable archive receipt

provisioningStage'creating_computer' | 'starting_agent' | 'null' nullable

Which part of its boot the session's computer is in, as the platform observed it: creating_computer until the sandbox provider reports the computer exists, then starting_agent until the agent in it answers. A provider that does not report the computer's creation stays at creating_computer. Null once the computer is up and whenever it is not booting.

archivedboolean

True only after this Session's archive mark was durably written; false for an active Session whose runtime was destroyed

agentTypestring
llmstring

The model this session runs on (PATCH to change; the agent's model is unchanged)

harnessVersionstring

Harness release the session runs: the one its serving pod booted, the restored checkpoint's for a native-fork handoff, the agent's pin for ACP harnesses, otherwise the current release

reasoningEffortstring nullable

The model-compatible effort resolved from the session pin, then agent pin. Constrained models use an allowed fallback; no-setting models return null. Unpinned unconstrained models return null for the harness default.

subscriptionApiFallbackboolean

Opt-in to paid API continuation after all subscription accounts exhaust, preserving the same supported explicit model and wallet/budget gates

modelBilling'platform' | 'account'

Who pays for model calls: platform wallet or the user's connected subscription

idleTimeoutSecondsinteger nullable

Seconds the session's machine stays awake after a turn ends before it is paused; null = the platform default of 60. Set it when people use apps on the session's exposed ports after the agent finishes

browserProfilestring

Resolved browser: the session's choice, then the agent's default, then mine. mine is the browser of the person whose turn it is; fresh is signed out; user:<user id> is the sites that person shared with whoever runs the turn. Applied before the next browser turn when browser profiles are enabled.

browserLoginsSavedAtstring date-time nullable

Most recent browser login save-back time, or null when this session has not saved changed logins.

defaultboolean

Is this the agent's default session

metadataobject
parentSessionIdstring nullable

The session this one came from: a helper names the session that hired it, a handoff child names the session it continued; null for a root. Every session a task's root produced, with its role, is GET /tasks/{id}?by=session on any member's id.

parentRelation'helper' | 'handoff' | 'null' nullable

How this session relates to parentSessionId: helper was hired by it (actl hire or the orchestration API), handoff continued its conversation on another agent; null for a root.

createdAtstring

ISO 8601

Changes