SetAgentSessionModel
Sets the model used by a session and optionally configures the thinking level.
Operation description
Pass the
sessionIdreturned by CreateAgentSession and theModels[].Idreturned by ListModels asParams.sessionIdandParams.modelId, respectively. The visibility of a model in the model catalog does not mean that the target session supports the model. The final validation is performed by the target session.modelIdis required. When you only modify the model, you can omitthinkingLevel. For more information about how to configure the thinking level, see the supplementary description of request parameters.This operation only modifies the target session and does not modify the global default model of the agent or account. The session may deny configuration modifications during execution, and switching during runtime is not guaranteed to be supported.
The model and thinking level settings are applied step by step. If the call fails, the model may have already been changed, and an overall rollback is not guaranteed. You should call GetAgentSessionModel to query the current configuration before deciding on subsequent operations. After a successful call, you can read the actual effective values from the returned result.
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:SetAgentSessionModel |
update |
*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 request identifier, which is echoed in the response. It is used to associate this call and does not have idempotent semantics. |
request-001 |
| Params |
any |
Yes |
The defined business parameter structure. For more information about the core nested fields, see the supplementary description. |
{"sessionId":"0123456789abcdef0123456789abcdef","modelId":"text-model-example"} |
The call method is POST, and the business parameters are located in formData. The region is determined by the client configuration. The examples only show the business parameters. Action, Version, identity, and signature are handled by the POP client, and Params is serialized once as required by the client.
| Name | Type | Required | Description | Example |
Params.sessionId | string | Yes | The session ID returned by CreateAgentSession. | 0123456789abcdef0123456789abcdef |
Params.modelId | string | Yes | The identifier of the target model. Use the Models[].Id returned by ListModels and ensure that the target session supports the model. | text-model-example |
Params.thinkingLevel | string | No | Optional advanced configuration: the target thinking level. Current definitions include off, default, low, medium, high, xhigh, and max. The specific available values are determined by the target model and session. | off |
When configuring the thinking level, refer to the model catalog and the level options returned by GetAgentSessionModel. Omitting thinkingLevel means that no explicit settings for this option are applied this time, which does not mean turning off thinking, nor does it guarantee that the level remains unchanged after switching models. off means turning off thinking. default means restoring the default configurations, and the returned value may be the specific level that actually takes effect. Specify only the values supported by the target model and session.
Request examples
The following example only sets the model. To configure the thinking level, add thinkingLevel to Params.
{
"Jsonrpc": "2.0",
"Id": "request-001",
"Params": {
"sessionId": "0123456789abcdef0123456789abcdef",
"modelId": "text-model-example"
}
}
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| RequestId |
string |
The ID of the current request, which is used for troubleshooting. |
0A1B2C3D-4E5F-6789-ABCD-EF0123456789 |
| JsonRpcResponse |
any |
The defined JSON-RPC response structure. For more information about the core nested fields, see the supplementary description. |
{"jsonrpc":"2.0","id":"request-001","result":{"modelId":"text-model-example","thinkingLevel":"off","thinkingLevels":["off","low","medium","high"]}} |
| Success |
boolean |
Indicates whether the setting is successful. The value is true if the setting is successful. Read the actual model and thinking level from the business result. |
true |
The Models[].Id in the model catalog is used to submit the selection, and the modelId returned by the session indicates the actual effective configuration. The two may be different. When you call the API, you should save the settings result and verify it against the modelId returned by the subsequent GetAgentSessionModel call. Do not determine a failed state solely based on the inequality between the catalog ID and the session ID string, and do not concatenate or remove the provider suffix yourself.
The model configuration is located in JsonRpcResponse.result.
| Name | Type | Description | Example |
JsonRpcResponse.jsonrpc | string | The JSON-RPC version. The current value is 2.0. | 2.0 |
JsonRpcResponse.id | string | The Id echoed in the request. | request-001 |
JsonRpcResponse.result | any | The model configuration structure returned after the setting is applied. | {"modelId":"text-model-example"} |
JsonRpcResponse.result.modelId | string | The identifier of the model that currently takes effect. | text-model-example |
JsonRpcResponse.result.thinkingLevel | string | Optional advanced configuration: the thinking level that currently takes effect. The client should tolerate the absence of this field. | off |
JsonRpcResponse.result.thinkingLevels | array<string> | Optional advanced configuration: the thinking level options provided by the current session. An empty array or the absence of this field does not indicate that all levels are supported. | ["off","low","medium","high"] |
Sample success responses
The model identifier in the example is for illustration purposes only. Use the actual queried model identifier when making the call.
{
"RequestId": "0A1B2C3D-4E5F-6789-ABCD-EF0123456789",
"Success": true,
"JsonRpcResponse": {
"jsonrpc": "2.0",
"id": "request-001",
"result": {
"modelId": "text-model-example",
"thinkingLevel": "off",
"thinkingLevels": [
"off",
"low",
"medium",
"high"
]
}
}
}
Examples
Success response
JSON format
{
"RequestId": "0A1B2C3D-4E5F-6789-ABCD-EF0123456789",
"JsonRpcResponse": "{\"jsonrpc\":\"2.0\",\"id\":\"request-001\",\"result\":{\"modelId\":\"text-model-example\",\"thinkingLevel\":\"off\",\"thinkingLevels\":[\"off\",\"low\",\"medium\",\"high\"]}}",
"Success": true
}
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. | |
| 409 | AgentSession.SessionBusy | A turn is already running in the agent session. |
See Error CodesError Codes for a complete list.
Release notes
See Release NotesRelease Notes for a complete list.