Sign in
AgentSession

Upsert messages in an agent session

Upserts messages in an agent session by ID. New messages are inserted, existing messages (matched by ID) are updated. This allows overwriting previously persisted messages.

put/agentSession/{id}/messages

Path parameters

idstring required

The ID of the agent session

Request body

status_update'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.

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