Sign in
latestOpenAPI 3.0.32026-08-227451,2751.8 MB

d0fc0114da66

AgentSession

Create a new cloud instance for a session

Creates a new cloud instance under an agent session and publishes a message to the agent-tasks queue. For test_authoring sessions the spawn is refused when a live instance already owns the session, or when the session has reached a terminal session-level status — a spawn stamps the new instance's status onto the session, so neither may be overwritten. Other agent types keep the multi-instance contract.

post/agentSession/{agent_session_id}/cloudInstance

Path parameters

agent_session_idstring required

The ID of the agent session

Request body

impersonate_user_idstring

The ID of the user that the cloud instance should impersonate when running

platform'none' | 'web'

The platform the agent operates on

snapshotstring

Optional. A specific snapshot Docker image tag — the commit SHA of a published agent build — to launch this agent type from instead of its standard deployed image. Used to exercise a pre-release/preview build within a session. Leave unset to use the agent type's normal deployed image.

api_imagestring

Optional. A mabl API deploy-preview tag (e.g. dp-my-branch) that routes the launched cloud agent's own API calls through https://<tag>.api-preview.mabl.com instead of the standard API. Used to exercise API changes end-to-end within an authoring session. Non-prod, cloud-mode only. Leave unset to use the standard API.

resume_attempt_idstring

Optional. The resume attempt id (the resume cycle's user_message_id). When present, the create transaction atomically binds this attempt's resume_payload_<cycle> artifact to the new instance (spawn_resolution='spawned' plus spawned_instance_id) in the same commit that creates the instance and flips the session status. Test-authoring resume spawns only; ignored otherwise.

Response

The created cloud instance

idstring required

The id of the cloud instance

workspace_idstring required

The id of the workspace

agent_session_idstring required

The id of the agent session this instance belongs to

agent_type'test_authoring' | 'test_creation_planning' | 'test_planning' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'test_recovery' | 'runtime_recovery_summary_agent' | 'plan_run_analysis' | 'deployment_analysis' | 'workspace_results_analysis' | 'results_auto_analysis' | 'app_modeling' | 'app_modeling_run' | 'file_assertion' required
status'queued' | 'running' | 'needs_attention' | 'completed' | 'failed' | 'terminated' | 'terminating' | 'rate_limited' | 'skipped' | 'merged' | 'accepted' | 'closed' | 'resuming' | 'none' required

The status of the latest agent instance driving a session. The same enum is used for cloud and local instances. Cloud-only values (queued, terminating, rate_limited, skipped) are set by the cloud instance lifecycle (start/terminate/end). Common values (running, needs_attention, completed, failed, terminated) are written by either cloud or local clients. merged is a session-level state applied after a completed authoring task's branch is merged into master (via the branch merge endpoint or the session's auto_merge setting); the underlying cloud instance stays completed. accepted and closed are session-level review outcomes for a finished authoring task, set only through their own endpoints; the underlying cloud instance keeps its own status. accepted records that the user kept the authored test. closed records that the user discarded it — the authored test and its steps are deleted while the session's conversation is retained. Both are terminal in the same sense as merged — neither is resumable, and no lifecycle transition leaves them. resuming is a transient, server-set-only state on the session (no instance holds it) — the cloud TAA continuation flow flips a resumable session to resuming while it plans the answer, then to queued when the new instance spawns (or back to a resumable status on re-clarification, or failed on error). It is the concurrency guard, so a second answer to a resuming session is rejected. The session's instance_type field indicates which kind of instance owns the session. Use none in query parameters to match sessions without any status.

platform'none' | 'web'

The platform the agent operates on

termination_reason'execution_timeout' | 'stop_requested' | 'infra_shutdown' | 'dispatch_failed' | 'unknown'

The reason for terminating a cloud instance. 'infra_shutdown' covers any shutdown signal from the runtime environment (K8s pod eviction, Cloud Run instance cycling, etc.) — kept generic so it applies regardless of where the agent runs. 'dispatch_failed' means the instance never started — its start message failed to publish, or expired in the queue before any runner claimed it.

queued_timeinteger

The timestamp when the cloud instance entered the queued status in epoch milliseconds

started_timeinteger

The timestamp when the cloud instance started running in epoch milliseconds

termination_timeinteger

The timestamp when the cloud instance entered the terminating status in epoch milliseconds

end_timeinteger

The timestamp when the cloud instance entered a terminal status (completed, failed, or terminated) in epoch milliseconds

created_timeinteger required

The timestamp of the cloud instance creation in epoch milliseconds

created_by_idstring required

The id of the user who created the cloud instance

last_updated_timeinteger required

The timestamp of the cloud instance last update in epoch milliseconds

last_updated_by_idstring required

The id of the user who last updated the cloud instance