Sign in
latestOpenAPI 3.0.32026-08-227451,2751.8 MB

d0fc0114da66

AgentSession

Update an agent session

Partial update of an agent session. Currently supports writing status to drive a local-client lifecycle. A status write requires an instance_type of local — cloud-managed sessions (and legacy sessions with no instance_type) are driven by the cloudInstance endpoints instead — and is refused once the session holds a terminal session-level status. A request with no status only touches audit metadata and is always allowed. Uses If-Match for optimistic locking against concurrent updates.

patch/agentSession/{id}

Path parameters

idstring required

The ID of the agent session

Headers

If-Matchstring

If-Match header for optimistic locking. Required when latest_instance_status is non-null to prevent concurrent clients from overwriting each other.

Request body

status'running' | 'needs_attention' | 'completed' | 'failed' | 'terminated'

AgentInstanceStatus values that local clients (e.g. mabl CLI) can write via updateAgentSession. Subset of AgentInstanceStatus that excludes cloud-orchestration values (queued, terminating, rate_limited, skipped) which are managed by the cloud instance lifecycle, not by local clients.

Response

The updated agent session

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.