LoadAgentSession

Updated at:
Copy as MD

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_turn may 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

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

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.

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.

NameTypeRequiredDescriptionExample
Params.sessionIdstringYesThe ID of the session to be loaded.0123456789abcdef0123456789abcdef
Params._metaanyNoThe resume parameters. Omit this parameter for standard loads.{"isReload":true,"beginLogOffset":12,"eventEpoch":"epoch-example","promptId":"prompt-example"}
Params._meta.isReloadbooleanNoSet this parameter to true when resuming a read operation.true
Params._meta.beginLogOffsetinteger<int64>NoThe last actually received Params._meta.offset.12
Params._meta.eventEpochstringNoThe Params._meta.eventEpoch saved along with the cursor.epoch-example
Params._meta.promptIdstringNoThe 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 Jsonrpc field in the frame. The value is 2.0.

2.0

Id

string

The Id field in the frame, used to associate the request. Notification frames may not contain this field.

request-001

Method

string

The Method field in the frame, used to distinguish notification categories.

session/update

Params

any

The Params field in the frame. It is the notification payload and is actually an object.

{"sessionId":"0123456789abcdef0123456789abcdef","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"Hello"}}}

Result

any

The Result field in the frame. It is the normal result and is actually an object.

{"stopReason":"end_turn"}

Error

any

The Error field in the frame. It is an in-stream error and is actually an object.

{"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

NameTypeDescriptionExample
Params.sessionIdstringThe session ID.0123456789abcdef0123456789abcdef
Params.updateanyThe event content when Method=session/update.{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"Check whether the list is empty first."}}
Params.update.sessionUpdatestringagent_message_chunk indicates the agent text increment. user_message_chunk indicates the historical user text.agent_message_chunk
Params.update.contentanyThe text content block.{"type":"text","text":"Check whether the list is empty first."}
Params.update.content.typestringThe value of the text content block is text.text
Params.update.content.textstringThe text body or increment fragment.Check whether the list is empty first.
Result.stopReasonstringThe 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.codeintegerThe JSON-RPC numeric error code.-32603
Error.errorCodestringOptional. The error category, such as CLI_TURN_FAILED, CLI_STREAM_FAILED, or CLI_RELOAD_REQUIRED.CLI_STREAM_FAILED
Error.messagestringThe 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.

NameTypeDescriptionExample
Params._meta.offsetintegerThe received cursor, passed to Params._meta.beginLogOffset.12
Params._meta.eventEpochstringThe event epoch, saved in pairs with the cursor, and passed to Params._meta.eventEpoch.epoch-example
Params._meta.promptIdstringThe turn ID, passed to Params._meta.promptId. It is not the Id in the request.prompt-example
Params._meta.waitForResponsebooleantrue 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.

NameTypeDescriptionExample
Params.kindstringWhen Method=_qwen/notify, permission_request indicates an approval or Q&A.permission_request
Params.data.sessionIdstringThe Params.sessionId passed to Reply.0123456789abcdef0123456789abcdef
Params.data.requestIdstringThe Params.permissionRequestId passed to Reply.permission-example
Params.data.options[].optionIdstringThe ID of the selectable approval action, passed to Params.outcome.optionId of Reply.allow_once
Params.data.toolCallanyThe 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.sessionUpdatestring_qwen.permission_resolved indicates that the interaction is resolved._qwen.permission_resolved
Params.update.requestIdstringThe 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.