Sign in
latestOpenAPI 3.0.32026-08-227451,2751.8 MB

d0fc0114da66

AgentSession

Update an agent session's startup params

Partial update of the resumable subset of an agent session's startup_params field, used by the cloud Test Authoring Agent (TAA) continuation flow to roll the session's "latest used / next to be used" authoring context forward. All fields are optional; only fields present in the body are written. Creation-attribution fields on the underlying startup_params (agent_session_source, test_variant_id) and the polymorphic discriminator (type) are preserved unchanged across every call — this endpoint is NOT a full partial-update of the startup_params JSON object. Only sessions whose agent_type is test_authoring accept this update; other agent types receive a 409. Uses If-Match for optimistic locking against concurrent updates.

patch/agentSession/{id}/startupParams

Path parameters

idstring required

The ID of the agent session

Headers

If-Matchstring

If-Match header for optimistic locking. Required when other clients may be writing to this session concurrently.

Request body

resume_cursorstring

1-based-inclusive index of the last saved step to replay before the resumed instance continues (absent or "0" replays nothing). Set by the resume planner on continue.

test_idstring

The invariant id of the test the session operates on. Set by the resume flow at pause (and at each save) so the next instance continues the same test.

urlstring

The URL the next instance should boot against (the pausing pod's most recent URL).

application_idstring

Refined application id if the pausing pod resolved a previously-unknown application.

environment_idstring

Refined environment id if the pausing pod resolved a previously-unknown environment.

branch_idstring

The id of the branch the agent operates on. Lifecycle is documented on TestAuthoringSessionStartupParams.branch_id.

base_versioninteger

The source-branch version the edit actually LOADED FROM, reported by the runtime once at initial load (see TestAuthoringSessionStartupParams.base_version). This is the server-computed entity_version the load returned, not a value the caller derives. Write-once and validated: it is stored only when the session has no base_version yet and the supplied version is >= 0 (versions are zero-indexed, so 0 is a valid initial-version baseline; a negative sentinel is dropped). A later pause/save that re-sends it (or a newer value) is ignored, so the baseline can never drift off the loaded version.

auto_mergeboolean

Whether the session's branch should be auto-merged into master on clean completion.

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.