Sign in
latestOpenAPI 3.0.32026-08-227451,2751.8 MB

d0fc0114da66

AgentSession

Begin resuming an agent session (flip it to the transient `resuming` status)

Atomically transitions a resumable test-authoring session to the transient resuming status, BEFORE the resume planner runs. This is the concurrency guard for the cloud TAA continuation flow: two concurrent answers to the same needs_attention session cannot both run a planner or spawn competing cloud instances, because only one wins the flip to resuming and the loser gets a 409. Granted only when the session's latest_instance_status is resumable (needs_attention, failed, or completed), or it is already resuming but stale (last updated longer ago than the server-side TTL — a crashed attempt, safe to steal). A live (non-stale) resuming session returns 409. The session leaves resuming when the resume spawns a new instance (→ queued) or via a status_update on the messages endpoint (re-clarification / error restore); a crashed attempt is reclaimed by the next answer's TTL steal. Only test_authoring sessions accept this call.

post/agentSession/{id}/beginResume

Path parameters

idstring required

The ID of the agent session

Response

The agent session, now in the resuming status

idstring required

The id of the agent session

workspace_idstring required

The id of the workspace

created_timeinteger required

The timestamp of the agent session creation in epoch milliseconds

created_by_idstring required

The id of the user who created the agent session

last_updated_timeinteger required

The timestamp of the agent session last update in epoch milliseconds

last_updated_by_idstring required

The id of the user who last updated the agent session

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
is_trialboolean required

Whether this agent session is associated with a trial account

parent_session_idstring

The id of the parent agent session

initiating_request_idstring

A unique identifier for the request that initiated this agent session. If set, this must be globally unique and requests to create a new agent session with the same initiating_request_id will fail.

instance_idsstring[]

IDs of all cloud instances created for this session (in chronological order). Empty for local-client-driven sessions.

instance_type'cloud' | 'local'

Indicates what kind of agent instance is driving a session. cloud means a server-managed cloud instance owns the lifecycle (created via the cloudInstance endpoints). local means a local client (e.g. mabl CLI) is driving the session via updateAgentSession.

latest_instance_status'queued' | 'running' | 'needs_attention' | 'completed' | 'failed' | 'terminated' | 'terminating' | 'rate_limited' | 'skipped' | 'merged' | 'accepted' | 'closed' | 'resuming' | 'none'

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.

latest_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.

agent_variantstring

The authoring-agent arm assigned to this session at creation time (values: generic or flexible). Records which test-authoring agent variant the runtime should use for the session. Only set for test_authoring sessions; unset for other agent types.