Sign in
AgentSession

Update an agent session

Partial update of an agent session. Currently supports writing status to drive a local-client lifecycle (running, needs_attention, completed, failed, terminated). Sets instance_type to local if not already set. Rejects with 409 if instance_type is already cloud — cloud-managed sessions are updated via the cloudInstance endpoints (start/end/terminate). 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' | '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. 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.

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.

Changes