LoadAgentSession
Loads session history, receives subsequent output, or resumes Server-Sent Events (SSE) from a saved read position.
Operation description
A standard load requires only the session ID. It returns the configuration, history, and output to be continuously received. The response is SSE, not a standard JSON message list.
When resuming from a stream interruption, pass back the actually received cursor, event epoch, and turn ID. History and incremental data may be returned simultaneously. Existing pages should be rebuilt or deduplicated based on the confirmed cursor. Do not directly append all returned data.
During the load process, you may receive pending approvals or questions again. Use the interaction notification that is still valid for this session to call ReplyAgentSession.
For an idle session,
stopReason=end_turnmay only indicate the end of the current load. It cannot be used to determine the success of a previously interrupted turn. You must associate it with the actual desired state of the target turn. If it cannot be determined, keep the result for verification.
Try it now
Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
ada:LoadAgentSession |
get |
*All Resource
|
None | None |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| Jsonrpc |
string |
No |
The JSON-RPC version. Set this parameter to |
2.0 |
| Id |
string |
No |
The client call identifier used to associate the current response. It does not provide idempotency guarantees. |
request-001 |
| Params |
any |
Yes |
The business parameter structure. For core nested fields, see the supplementary description. |
{"sessionId":"0123456789abcdef0123456789abcdef"} |
The call method is POST, and the business parameters are located in formData. The region is determined by the client configuration. Action, Version, identity, and signature are handled by the POP client. The examples show only the business parameters. Params is serialized once as required by the SDK.
Streaming calls must use a POP client that supports SSE and V3 signatures (ACS3-HMAC-SHA256). Legacy signatures may return UnsupportedSignatureVersion. Simply setting Accept: text/event-stream cannot replace a signature upgrade.
| Name | Type | Required | Description | Example |
Params.sessionId | string | Yes | The ID of the session to be loaded. | 0123456789abcdef0123456789abcdef |
Params._meta | any | No | The resume parameters. Omit this parameter for standard loads. | {"isReload":true,"beginLogOffset":12,"eventEpoch":"epoch-example","promptId":"prompt-example"} |
Params._meta.isReload | boolean | No | Set this parameter to true when resuming a read operation. | true |
Params._meta.beginLogOffset | integer<int64> | No | The last actually received Params._meta.offset. | 12 |
Params._meta.eventEpoch | string | No | The Params._meta.eventEpoch saved along with the cursor. | epoch-example |
Params._meta.promptId | string | No | The Params._meta.promptId to be resumed, used to supplement the turns completed during the stream interruption. | prompt-example |
You can omit the resume fields for standard loads. When performing a breakpoint resume, you must pass back the obtained beginLogOffset, eventEpoch, and promptId together. Do not fabricate missing values. If valid resume markers cannot be obtained, reload the history. Do not infer that a turn has been completed on your own.
Request examples
Standard load:
{
"Jsonrpc": "2.0",
"Id": "request-001",
"Params": {
"sessionId": "0123456789abcdef0123456789abcdef"
}
}
Breakpoint resume:
{
"Jsonrpc": "2.0",
"Id": "request-001",
"Params": {
"sessionId": "0123456789abcdef0123456789abcdef",
"_meta": {
"isReload": true,
"beginLogOffset": 12,
"eventEpoch": "epoch-example",
"promptId": "prompt-example"
}
}
}
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| RequestId |
string |
The request diagnostic identifier. It is not guaranteed to be included in every frame. You should also retain the diagnostic information in the response headers. |
0A1B2C3D-4E5F-6789-ABCD-EF0123456789 |
| Jsonrpc |
string |
The |
2.0 |
| Id |
string |
The |
request-001 |
| Method |
string |
The |
session/update |
| Params |
any |
The |
{"sessionId":"0123456789abcdef0123456789abcdef","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"Hello"}}} |
| Result |
any |
The |
{"stopReason":"end_turn"} |
| Error |
any |
The |
{"code":-32603,"errorCode":"CLI_STREAM_FAILED","message":"The response stream was interrupted."} |
The response type is text/event-stream. The data content of each SSE message is JSON, using field names such as Jsonrpc, Id, Method, Params, Result, and Error. The internal keys of the any type in Params, Result, and Error retain their original case.
The names in the following table correspond to the JSON fields within the data of the SSE message. Identify the notification or result type first, and then read the corresponding fields. Other events can be displayed as needed. Do not use unknown events, heartbeats, or connection closures as the basis for execution success.
Text and results
| Name | Type | Description | Example |
Params.sessionId | string | The session ID. | 0123456789abcdef0123456789abcdef |
Params.update | any | The event content when Method=session/update. | {"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"Check whether the list is empty first."}} |
Params.update.sessionUpdate | string | agent_message_chunk indicates the agent text increment. user_message_chunk indicates the historical user text. | agent_message_chunk |
Params.update.content | any | The text content block. | {"type":"text","text":"Check whether the list is empty first."} |
Params.update.content.type | string | The value of the text content block is text. | text |
Params.update.content.text | string | The text body or increment fragment. | Check whether the list is empty first. |
Result.stopReason | string | The stop reason, such as end_turn or cancelled. Other values are retained as actually returned and are not all treated as success. | end_turn |
Error.code | integer | The JSON-RPC numeric error code. | -32603 |
Error.errorCode | string | Optional. The error category, such as CLI_TURN_FAILED, CLI_STREAM_FAILED, or CLI_RELOAD_REQUIRED. | CLI_STREAM_FAILED |
Error.message | string | The error description. | The response stream was interrupted. |
Resume information
Resume markers are read from Params._meta in the notification. offset, eventEpoch, and promptId should be saved as a group, using the last complete set of markers. Do not overwrite existing values when subsequent frames lack markers. Result or error frames are not guaranteed to carry resume markers. Do not require the top-level _meta to exist.
We recommend that you provide a unique Id for each call. The result or error of the original Prompt stream is associated with the Prompt request through the returned Id. The resume stream that specifies Params._meta.promptId is associated through the Id of the current Load, and the target turn is determined by the resume request. Result.stopReason=end_turn for a standard Load only indicates the end of the load. It cannot prove the success of a previous turn.
| Name | Type | Description | Example |
Params._meta.offset | integer | The received cursor, passed to Params._meta.beginLogOffset. | 12 |
Params._meta.eventEpoch | string | The event epoch, saved in pairs with the cursor, and passed to Params._meta.eventEpoch. | epoch-example |
Params._meta.promptId | string | The turn ID, passed to Params._meta.promptId. It is not the Id in the request. | prompt-example |
Params._meta.waitForResponse | boolean | true indicates waiting or a heartbeat. It does not indicate the end of execution. | true |
Pending interactions
This operation uses the same approval and Q&A payloads as PromptAgentSession. The following are the fields required for passing values across operations. For the complete nested structure of questions, answer keys, and operation contexts, see Supplementary description of response parameters for PromptAgentSession.
| Name | Type | Description | Example |
Params.kind | string | When Method=_qwen/notify, permission_request indicates an approval or Q&A. | permission_request |
Params.data.sessionId | string | The Params.sessionId passed to Reply. | 0123456789abcdef0123456789abcdef |
Params.data.requestId | string | The Params.permissionRequestId passed to Reply. | permission-example |
Params.data.options[].optionId | string | The ID of the selectable approval action, passed to Params.outcome.optionId of Reply. | allow_once |
Params.data.toolCall | any | The operation context or Q&A question. The structure is the same as that of Prompt. Do not automatically approve based only on the action ID. | {"title":"Confirm execution scope"} |
Params.update.sessionUpdate | string | _qwen.permission_resolved indicates that the interaction is resolved. | _qwen.permission_resolved |
Params.update.requestId | string | The interaction ID in the interaction resolution notification. | permission-example |
Historical messages may not have cursors. Do not discard them all, and do not identify them as new messages solely based on the missing cursor. When eventEpoch does not match, InvalidParameter may be returned before SSE is established, pointing to Meta.EventEpoch and prompting a reload. CLI_RELOAD_REQUIRED may also be returned within the stream. In this case, clear the old resume markers, reload, and rebuild the current view.
Normal response examples
The following example only indicates that the current idle session load is complete. It does not prove the successful execution of a previous turn.
data: {"Jsonrpc":"2.0","Id":"request-001","Result":{"stopReason":"end_turn"}}
JSON example in the end frame. The complete response is still SSE:
{
"Jsonrpc": "2.0",
"Id": "request-001",
"Result": {
"stopReason": "end_turn"
}
}
When an Error is received, record the error category and distinguish between read failures and execution failures. A simple EOF, timeout, or HTTP 200 cannot replace the desired state judgment.
Examples
Success response
JSON format
{
"RequestId": "0A1B2C3D-4E5F-6789-ABCD-EF0123456789",
"Jsonrpc": "2.0",
"Id": "request-001",
"Method": "session/update",
"Params": "{\"sessionId\":\"0123456789abcdef0123456789abcdef\",\"update\":{\"sessionUpdate\":\"agent_message_chunk\",\"content\":{\"type\":\"text\",\"text\":\"Hello\"}}}",
"Result": "{\"stopReason\":\"end_turn\"}",
"Error": "{\"code\":-32603,\"errorCode\":\"CLI_STREAM_FAILED\",\"message\":\"The response stream was interrupted.\"}"
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 400 | InvalidParameter | The specified parameter is invalid. | |
| 401 | Unauthenticated | Authentication required. | |
| 500 | InternalError | Internal server error. | |
| 403 | Forbidden | You are not authorized to perform this operation. | |
| 404 | AgentSession.SessionNotFound | The specified agent session does not exist. | |
| 503 | ServiceUnavailable | The service is not ready or temporarily unavailable. |
See Error CodesError Codes for a complete list.
Release notes
See Release NotesRelease Notes for a complete list.