--- title: "Append a message to an agent session" method: POST path: "/agentSession/{id}/messages" tags: ["AgentSession"] --- # Append a message to an agent session `POST /agentSession/{id}/messages` Appends a message to an agent session's messages array ## Path parameters - `id` string, required ## Request body - AppendAgentSessionMessageRequest — Request to append a message to an agent session - `message` union, required - BaseMessage - `id` string, required — The id of the message - `message_index` integer — The index of the message in the session (used for ordering) - `timestamp` integer, required — The timestamp of the message in epoch milliseconds - `metadata` object — The metadata of the message - `parts` MessagePart[], required - union - object - `type` 'text' - `text` string — Text content - `signature` string — Thought signature from the model (used by Gemini 3 for text parts with thinking) - `user_prompted` boolean — True when this text part originated from a user-initiated prompt (user-typed input, a selected suggested prompt, or an auto-sent prompt on the user's behalf). This is content that will be displayed in the UI in a chat bubble with the user profile picture. - object - `type` 'file' - `source` union - … - `title` string — Optional file title/name - `display_name` string — Optional display name - object - `type` 'tool_call' - `id` string — Unique identifier for the tool call - `name` string — Name of the tool/function - `input` union - … - `signature` string — Thought signature from the model (required by Gemini 3 when thinking is enabled) - object - `type` 'thinking' - `thinking` string — The thinking/reasoning text - `signature` string — Signature of the thinking/reasoning - object - `type` 'tool_output' - `tool_name` string — Name of the tool that was called - `tool_call_id` string — ID of the tool call this responds to - `output` union - … - object — Code the model asked the Gemini built-in Python execution sandbox to run. Emitted alongside a matching CodeExecutionResultPart on the same model turn — the sandbox runs synchronously and returns its result in the same response. Only appears when the agent enables the code execution tool and the model chooses to use it. - `type` 'code_execution_call' - `language` string — Programming language identifier from Gemini's Language enum (e.g. PYTHON). LANGUAGE_UNSPECIFIED when the model omitted it. - `code` string — Source code that was executed in the sandbox. - `signature` string — Thought signature (Gemini 3 with thinking enabled). - object — The result of the sandbox executing the immediately preceding CodeExecutionCallPart. Bundled with the call on the same model turn; there is no separate tool-output round-trip. - `type` 'code_execution_result' - `outcome` string — Outcome identifier from Gemini's Outcome enum (OUTCOME_OK, OUTCOME_FAILED, OUTCOME_DEADLINE_EXCEEDED, or OUTCOME_UNSPECIFIED). - `output_text` string — Combined stdout and stderr captured from the sandbox. Named `output_text` (not `output`) to avoid colliding with ToolOutputMessagePart.output in the flattened MessagePart interface — see the comment on this schema. - `role` 'user' | 'model' | 'tool_output' | 'special', required - BaseMessage - `id` string, required — The id of the message - `message_index` integer — The index of the message in the session (used for ordering) - `timestamp` integer, required — The timestamp of the message in epoch milliseconds - `metadata` object — The metadata of the message - `parts` MessagePart[], required - union - object - `type` 'text' - `text` string — Text content - `signature` string — Thought signature from the model (used by Gemini 3 for text parts with thinking) - `user_prompted` boolean — True when this text part originated from a user-initiated prompt (user-typed input, a selected suggested prompt, or an auto-sent prompt on the user's behalf). This is content that will be displayed in the UI in a chat bubble with the user profile picture. - object - `type` 'file' - `source` union - … - `title` string — Optional file title/name - `display_name` string — Optional display name - object - `type` 'tool_call' - `id` string — Unique identifier for the tool call - `name` string — Name of the tool/function - `input` union - … - `signature` string — Thought signature from the model (required by Gemini 3 when thinking is enabled) - object - `type` 'thinking' - `thinking` string — The thinking/reasoning text - `signature` string — Signature of the thinking/reasoning - object - `type` 'tool_output' - `tool_name` string — Name of the tool that was called - `tool_call_id` string — ID of the tool call this responds to - `output` union - … - object — Code the model asked the Gemini built-in Python execution sandbox to run. Emitted alongside a matching CodeExecutionResultPart on the same model turn — the sandbox runs synchronously and returns its result in the same response. Only appears when the agent enables the code execution tool and the model chooses to use it. - `type` 'code_execution_call' - `language` string — Programming language identifier from Gemini's Language enum (e.g. PYTHON). LANGUAGE_UNSPECIFIED when the model omitted it. - `code` string — Source code that was executed in the sandbox. - `signature` string — Thought signature (Gemini 3 with thinking enabled). - object — The result of the sandbox executing the immediately preceding CodeExecutionCallPart. Bundled with the call on the same model turn; there is no separate tool-output round-trip. - `type` 'code_execution_result' - `outcome` string — Outcome identifier from Gemini's Outcome enum (OUTCOME_OK, OUTCOME_FAILED, OUTCOME_DEADLINE_EXCEEDED, or OUTCOME_UNSPECIFIED). - `output_text` string — Combined stdout and stderr captured from the sandbox. Named `output_text` (not `output`) to avoid colliding with ToolOutputMessagePart.output in the flattened MessagePart interface — see the comment on this schema. - `role` 'user' | 'model' | 'tool_output' | 'special', required - BaseMessage - `id` string, required — The id of the message - `message_index` integer — The index of the message in the session (used for ordering) - `timestamp` integer, required — The timestamp of the message in epoch milliseconds - `metadata` object — The metadata of the message - `parts` MessagePart[], required - union - object - `type` 'text' - `text` string — Text content - `signature` string — Thought signature from the model (used by Gemini 3 for text parts with thinking) - `user_prompted` boolean — True when this text part originated from a user-initiated prompt (user-typed input, a selected suggested prompt, or an auto-sent prompt on the user's behalf). This is content that will be displayed in the UI in a chat bubble with the user profile picture. - object - `type` 'file' - `source` union - … - `title` string — Optional file title/name - `display_name` string — Optional display name - object - `type` 'tool_call' - `id` string — Unique identifier for the tool call - `name` string — Name of the tool/function - `input` union - … - `signature` string — Thought signature from the model (required by Gemini 3 when thinking is enabled) - object - `type` 'thinking' - `thinking` string — The thinking/reasoning text - `signature` string — Signature of the thinking/reasoning - object - `type` 'tool_output' - `tool_name` string — Name of the tool that was called - `tool_call_id` string — ID of the tool call this responds to - `output` union - … - object — Code the model asked the Gemini built-in Python execution sandbox to run. Emitted alongside a matching CodeExecutionResultPart on the same model turn — the sandbox runs synchronously and returns its result in the same response. Only appears when the agent enables the code execution tool and the model chooses to use it. - `type` 'code_execution_call' - `language` string — Programming language identifier from Gemini's Language enum (e.g. PYTHON). LANGUAGE_UNSPECIFIED when the model omitted it. - `code` string — Source code that was executed in the sandbox. - `signature` string — Thought signature (Gemini 3 with thinking enabled). - object — The result of the sandbox executing the immediately preceding CodeExecutionCallPart. Bundled with the call on the same model turn; there is no separate tool-output round-trip. - `type` 'code_execution_result' - `outcome` string — Outcome identifier from Gemini's Outcome enum (OUTCOME_OK, OUTCOME_FAILED, OUTCOME_DEADLINE_EXCEEDED, or OUTCOME_UNSPECIFIED). - `output_text` string — Combined stdout and stderr captured from the sandbox. Named `output_text` (not `output`) to avoid colliding with ToolOutputMessagePart.output in the flattened MessagePart interface — see the comment on this schema. - `role` 'user' | 'model' | 'tool_output' | 'special', required - BaseMessage - `id` string, required — The id of the message - `message_index` integer — The index of the message in the session (used for ordering) - `timestamp` integer, required — The timestamp of the message in epoch milliseconds - `metadata` object — The metadata of the message - `parts` MessagePart[], required - union - object - `type` 'text' - `text` string — Text content - `signature` string — Thought signature from the model (used by Gemini 3 for text parts with thinking) - `user_prompted` boolean — True when this text part originated from a user-initiated prompt (user-typed input, a selected suggested prompt, or an auto-sent prompt on the user's behalf). This is content that will be displayed in the UI in a chat bubble with the user profile picture. - object - `type` 'file' - `source` union - … - `title` string — Optional file title/name - `display_name` string — Optional display name - object - `type` 'tool_call' - `id` string — Unique identifier for the tool call - `name` string — Name of the tool/function - `input` union - … - `signature` string — Thought signature from the model (required by Gemini 3 when thinking is enabled) - object - `type` 'thinking' - `thinking` string — The thinking/reasoning text - `signature` string — Signature of the thinking/reasoning - object - `type` 'tool_output' - `tool_name` string — Name of the tool that was called - `tool_call_id` string — ID of the tool call this responds to - `output` union - … - object — Code the model asked the Gemini built-in Python execution sandbox to run. Emitted alongside a matching CodeExecutionResultPart on the same model turn — the sandbox runs synchronously and returns its result in the same response. Only appears when the agent enables the code execution tool and the model chooses to use it. - `type` 'code_execution_call' - `language` string — Programming language identifier from Gemini's Language enum (e.g. PYTHON). LANGUAGE_UNSPECIFIED when the model omitted it. - `code` string — Source code that was executed in the sandbox. - `signature` string — Thought signature (Gemini 3 with thinking enabled). - object — The result of the sandbox executing the immediately preceding CodeExecutionCallPart. Bundled with the call on the same model turn; there is no separate tool-output round-trip. - `type` 'code_execution_result' - `outcome` string — Outcome identifier from Gemini's Outcome enum (OUTCOME_OK, OUTCOME_FAILED, OUTCOME_DEADLINE_EXCEEDED, or OUTCOME_UNSPECIFIED). - `output_text` string — Combined stdout and stderr captured from the sandbox. Named `output_text` (not `output`) to avoid colliding with ToolOutputMessagePart.output in the flattened MessagePart interface — see the comment on this schema. - `role` 'user' | 'model' | 'tool_output' | 'special', required - `related_artifacts` Artifact[] — Artifacts related to this agent session. If set, this will replace the existing artifacts. - union - BaseArtifact - `artifact_type` 'inline' | 'remote', required — The type of artifact - BaseArtifact - `artifact_type` 'inline' | 'remote', required — The type of artifact ## Response `200` The updated agent session - AgentSession - `id` string, required — The id of the agent session - `workspace_id` string, required — The id of the workspace - `created_time` integer, required — The timestamp of the agent session creation in epoch milliseconds - `created_by_id` string, required — The id of the user who created the agent session - `last_updated_time` integer, required — The timestamp of the agent session last update in epoch milliseconds - `last_updated_by_id` string, 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_trial` boolean, required — Whether this agent session is associated with a trial account - `parent_session_id` string — The id of the parent agent session - `initiating_request_id` string — 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. - `startup_params` union - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required - `parent_session_id` string — The id of the parent session to review - `system_prompt` string — The system prompt that defines the review goals and instructions - `agent_subtype` 'test_authoring_analysis' | 'results_analysis_analysis' | 'failure_categorization_analysis' | 'failure_categorization_override_analysis' — Subtype for agent_review agents to distinguish different review purposes - `test_id` string — Optional test ID to give the review agent access to test definition and analysis tools - `test_run_id` string — Optional test run ID to give the review agent access to test run analysis tools - `plan_run_id` string — Optional plan run ID for results-analysis reviews of plan-run RAA sessions - `deployment_event_id` string — Optional deployment event ID for results-analysis reviews of deployment RAA sessions - `batch_id` string — Optional identifier linking reviews from the same backfill or batch run - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required - `application_id` string — The id of the application to analyze - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required - `agent_state` NextStepGenerationState — Agent model state tracked between generation requests - `entireTestPlan` TestCreationOutline — A test outline with tasks and suggested flows and snippets - `test_case` string, required — A clear description of the test case to be performed - `tasks` TestCreationTaskPlan[], required — A list of tasks to be performed - `task` string, required — A clear description of the task to be performed - `suggested_validation` string, required — Description of what to validate when this task is complete - `suggested_flow_options` TestCreationFlowOption[], required — List of recommended flow options for this task - … - `suggested_snippet_options` TestCreationSnippetOption[], required — List of recommended code snippet options for this task - … - `implementation_notes` string — Notes about how to create a good task for the plan, including information from relevant screenshots if available - `screenshots_cited` TestGenerationScreenshotReference[], required — List of screenshots cited in the implementation notes - … - `implementation_notes` string — Notes about how to create a good test from the plan, including when to use variables and important validations - `testInformation` TestCreationPlanningTestInformation — Test configuration and metadata selected during planning - `test_id` string — The ID of an existing test to edit instead of creating a new one - `test_variant_id` string — The variant (version) ID of the test being edited. Distinct from `test_id`, which is the invariant test identity — `test_variant_id` pins a specific snapshot. Set when the caller wants the edit applied against a known version (for example, to dedup auto-triggered edits for the same version). - `source_test_id` string — The invariant ID of an existing test to COPY as the starting point for a brand new test. The source test is only read — it is never modified — and the test that gets created is a new, independent test. Mutually exclusive with `test_id`, which edits an existing test in place rather than copying it. Set this when the user wants to start from an existing test ("make a copy of X and then ...") and leave `test_id` unset. - `name` string — The name of the test - `description` string — The description of the test - `application_id` string — The ID of the application for the test - `environment_id` string — The ID of the environment for the test - `deployment_id` string — The ID of the deployment for the test - `test_case` string — The test case for the test - `url_override` string — The base URL for the test, if there is no application or if the application's base URL should be overridden for this test - `credentials_id` string — The ID of the credentials for the test - `test_type` 'api' | 'browser' | 'performance' | 'mobile' — Type of test - `viewport_width` integer — Browser viewport width in pixels - `viewport_height` integer — Browser viewport height in pixels - `datatable_id` string — The ID of the data table for data-driven tests - `scenario_id` string — The ID of a specific scenario within the data table - `labels` string[] — Labels to apply to the test - `branch_id` string — The ID of the branch to save the test to (the save-to / destination branch) - `source_branch_id` string — The ID of the branch to load the test from as the starting point for edits. Only meaningful when test_id is set (editing an existing test). When unset, the test is loaded from master (it does NOT fall back to branch_id). This is the load-from branch; branch_id remains the save-to (destination) branch. - `plan_id` string — The ID of the plan to add the test to after creation - `device_preset` 'blackberry_playbook' | 'blackberry_z30' | 'galaxy_fold' | 'galaxy_note_3' | 'galaxy_note_ii' | 'galaxy_s5' | 'galaxy_s6' | 'galaxy_s8' | 'galaxy_s21' | 'galaxy_s22' | 'galaxy_s23' | 'galaxy_s_iii' | 'galaxy_tab_s7' | 'ipad' | 'ipad_air_2020' | 'ipad_mini' | 'ipad_mini_4' | 'ipad_pro' | 'ipad_ten_point_two' | 'iphone_11_pro_max' | 'iphone_11' | 'iphone_12' | 'iphone_12_pro_max' | 'iphone_13_mini' | 'iphone_13' | 'iphone_13_pro' | 'iphone_13_pro_max' | 'iphone_14' | 'iphone_14_pro' | 'iphone_14_plus' | 'iphone_14_pro_max' | 'iphone_15' | 'iphone_15_plus' | 'iphone_15_pro' | 'iphone_15_pro_max' | 'iphone_4' | 'iphone_5_se' | 'iphone_6_7_8' | 'iphone_6_7_8_plus' | 'iphone_x' | 'jiophone_2' | 'kindle_fire_hdx' | 'laptop_with_hidpi_screen' | 'laptop_with_mdpi_screen' | 'laptop_with_touch' | 'lg_optimus_l70' | 'microsoft_lumia_550' | 'microsoft_lumia_950' | 'moto_g4' | 'nexus_4' | 'nexus_5' | 'nexus_5x' | 'nexus_6' | 'nexus_6p' | 'nexus_7' | 'nexus_10' | 'nokia_lumia_520' | 'nokia_n9' | 'pixel_2' | 'pixel_2_xl' | 'pixel_6' | 'surface_duo' — Preset device configuration - `device_orientation` 'portrait_primary' | 'portrait_secondary' | 'landscape_primary' | 'landscape_secondary' — Device orientation - `application_id` string — The ID of the application being tested - `environment_id` string — The ID of the environment being tested - `url` string — The URL to start testing from - `agent_session_source` 'user_web' | 'user_mcp' | 'user_cli' | 'auto_tra' | 'user_tra' | 'unknown' — Origin of an agent session — who or what initiated it. `user_web`, `user_mcp`, `user_cli` distinguish the human-driven entry point. `auto_tra` marks sessions automatically started by the Test Recovery Agent (runtime recovery). `user_tra` marks edits the user explicitly accepted from a TRA suggestion. `unknown` is used when no source was provided. - `test_variant_id` string — The variant (version) ID of the test being edited, when this session is an edit of a specific known version. Set in conjunction with `test_information.test_id`. - `resume_cursor` string — Optional 1-based-inclusive index of the last saved step the next instance replays before continuing the LLM loop (e.g. "5" replays steps 1–5; absent or "0" replays nothing). Set by the resume planner on continue via `PATCH /agentSession/{id}/startupParams`; not used at session creation. - `test_id` string — The invariant id of the test this authoring session operates on. Set at session creation for edits (mirrored from `test_information.test_id`) and rolled forward by the cloud TAA continuation flow at each save/pause via `PATCH /agentSession/{id}/startupParams`, so a resuming instance continues the same test rather than authoring a new one. - `branch_id` string — (Optional) The id of the save-to branch — every test and flow version the agent writes lands on it, leaving master untouched. Set once at session creation and mirrored from `test_information.branch_id`; a supplied name is canonicalized to the id, which must resolve inside the session's workspace. An edit session (`test_id` set) that omits it gets a server-created feature branch unless the workspace sets `require_agent_edits_on_branches: false`; creation sessions author on master. Absent on local sessions, which carry the value on `test_information`. A resume reuses it. The branch outlives the session and is closed only by a merge into master (via the branch merge endpoint or `auto_merge`), which is also what flips the session to `merged`. - `source_branch_id` string — (Optional) The id of the load-from branch — the branch the agent reads the starting test version from. Mirrored from `test_information.source_branch_id` at session creation. The agent never saves to it (it saves to `branch_id`); when unset, the version loads from master (it does NOT fall back to `branch_id`). Only meaningful for edit sessions. - `base_version` integer — (Optional) The immutable source-branch version number the edit LOADED FROM — the variant of the `source_branch_id` branch (or master, when unset) at the moment the runtime fetched the starting test. Written once by the runtime at initial load and never rolled forward, so it pins the "Review changes" diff baseline to the version actually edited rather than the source branch's current tip (which can advance while the edit is in flight). Only meaningful for edit sessions; absent on older sessions, where consumers fall back to the source branch's current version tag. - `auto_merge` boolean — When true, the session's `branch_id` is merged into master on a successful session completion (provided the branch still resolves to this workspace and has new versions). Defaults to absent/false — the branch is left open for human review. - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required - `test_run_id` string — The ID of the test run to analyze - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required - `plan_run_id` string — The ID of the plan run to analyze - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required - `deployment_event_id` string — The ID of the deployment event to analyze - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required - `training_session_id` string — Optional training session ID for tracing - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required - `application_id` string — The id of the application the app modeling session builds a knowledge graph for - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required - `application_id` string — The id of the application this coordinator run models - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'app_modeling' | 'app_modeling_run' | 'file_assertion', required - `test_run_id` string — The ID of the test run this file assertion evaluation belongs to. - `messages` AgentSessionMessage[], required — The messages in the agent session - union - BaseMessage - `id` string, required — The id of the message - `message_index` integer — The index of the message in the session (used for ordering) - `timestamp` integer, required — The timestamp of the message in epoch milliseconds - `metadata` object — The metadata of the message - `parts` MessagePart[], required - union - object - … - object - … - object - … - object - … - object - … - object — Code the model asked the Gemini built-in Python execution sandbox to run. Emitted alongside a matching CodeExecutionResultPart on the same model turn — the sandbox runs synchronously and returns its result in the same response. Only appears when the agent enables the code execution tool and the model chooses to use it. - … - object — The result of the sandbox executing the immediately preceding CodeExecutionCallPart. Bundled with the call on the same model turn; there is no separate tool-output round-trip. - … - `role` 'user' | 'model' | 'tool_output' | 'special', required - BaseMessage - `id` string, required — The id of the message - `message_index` integer — The index of the message in the session (used for ordering) - `timestamp` integer, required — The timestamp of the message in epoch milliseconds - `metadata` object — The metadata of the message - `parts` MessagePart[], required - union - object - … - object - … - object - … - object - … - object - … - object — Code the model asked the Gemini built-in Python execution sandbox to run. Emitted alongside a matching CodeExecutionResultPart on the same model turn — the sandbox runs synchronously and returns its result in the same response. Only appears when the agent enables the code execution tool and the model chooses to use it. - … - object — The result of the sandbox executing the immediately preceding CodeExecutionCallPart. Bundled with the call on the same model turn; there is no separate tool-output round-trip. - … - `role` 'user' | 'model' | 'tool_output' | 'special', required - BaseMessage - `id` string, required — The id of the message - `message_index` integer — The index of the message in the session (used for ordering) - `timestamp` integer, required — The timestamp of the message in epoch milliseconds - `metadata` object — The metadata of the message - `parts` MessagePart[], required - union - object - … - object - … - object - … - object - … - object - … - object — Code the model asked the Gemini built-in Python execution sandbox to run. Emitted alongside a matching CodeExecutionResultPart on the same model turn — the sandbox runs synchronously and returns its result in the same response. Only appears when the agent enables the code execution tool and the model chooses to use it. - … - object — The result of the sandbox executing the immediately preceding CodeExecutionCallPart. Bundled with the call on the same model turn; there is no separate tool-output round-trip. - … - `role` 'user' | 'model' | 'tool_output' | 'special', required - BaseMessage - `id` string, required — The id of the message - `message_index` integer — The index of the message in the session (used for ordering) - `timestamp` integer, required — The timestamp of the message in epoch milliseconds - `metadata` object — The metadata of the message - `parts` MessagePart[], required - union - object - … - object - … - object - … - object - … - object - … - object — Code the model asked the Gemini built-in Python execution sandbox to run. Emitted alongside a matching CodeExecutionResultPart on the same model turn — the sandbox runs synchronously and returns its result in the same response. Only appears when the agent enables the code execution tool and the model chooses to use it. - … - object — The result of the sandbox executing the immediately preceding CodeExecutionCallPart. Bundled with the call on the same model turn; there is no separate tool-output round-trip. - … - `role` 'user' | 'model' | 'tool_output' | 'special', required - `instance_ids` string[] — 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. - `related_artifacts` Artifact[] — Artifacts related to this agent session (e.g., generated tests, flows, etc.). Visible to all workspace members via queryAgentSessions — do not store creator-private content here; use `messages` for private content. - union - BaseArtifact - `artifact_type` 'inline' | 'remote', required — The type of artifact - BaseArtifact - `artifact_type` 'inline' | 'remote', required — The type of artifact - `agent_variant` string — 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. ## Other responses - `400` — Invalid or missing parameter - `401` — User not authenticated - `403` — User not authorized - `404` — Entity not found - `default` — Unknown error --- [API](https://skmtc.net/mabl/apis/mabl-api.md) · [All operations](https://skmtc.net/mabl/apis/mabl-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mabl/mabl-api/revisions/d0fc0114da66/schema)