CreateAgentSession
Creates a text session for a specified agent and obtains the session ID required for subsequent calls.
Operation description
Before calling this operation, obtain the name of an agent accessible to the current identity. After the session is created, save JsonRpcResponse.result.sessionId and use it as Params.sessionId for subsequent operations such as PromptAgentSession and LoadAgentSession.
You can set the approval mode during creation. If omitted, the mode defaults to default. The availability of yolo depends on the target agent. If it is not supported, an error is returned. This mode does not change the caller's permissions or replace business Q&A. To retry the same creation request, reuse the same clientToken and the same business parameters.
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:CreateAgentSession |
create |
*All Resource
|
None | None |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| Jsonrpc |
string |
No |
The JSON-RPC protocol version. Set the value to |
2.0 |
| Id |
string |
No |
The correlation identifier for this call. It is echoed in the response and does not provide idempotency guarantees. |
request-001 |
| Params |
any |
Yes |
The business parameter object. For nested fields, see the supplementary description of request parameters. |
{"clientToken":"create-review-001","_meta":{"agent":{"agentName":"review-agent-demo"},"initialConfigOptions":{"approvalMode":"default"}}} |
The call method is POST, and the business parameters are located in formData. The examples show only the business parameters. Action, Version, signature, and identity information are handled by the POP client. The region is determined by the client configuration. Structure fields are serialized once as required by the SDK.
| Name | Type | Required | Description | Example |
Params._meta | any | Yes | The session creation configuration. | {"agent":{"agentName":"review-agent-demo"},"initialConfigOptions":{"approvalMode":"default"}} |
Params._meta.agent | any | Yes | The agent specified for the session. | {"agentName":"review-agent-demo"} |
Params._meta.agent.agentName | string | Yes | The name of an existing agent accessible to the current identity. The name must be 1 to 64 characters in length. | review-agent-demo |
Params.clientToken | string | No | The idempotency token for the creation request. The token must be 1 to 128 characters in length. An explicit empty string is invalid. Provide this parameter during the initial creation and keep it unchanged during retries. | create-review-001 |
Params._meta.initialConfigOptions | any | No | The initial configuration of the session. | {"approvalMode":"default"} |
Params._meta.initialConfigOptions.approvalMode | string | No | The initial approval mode. Valid values: default: follows the approval policy. yolo: automatically approves supported operation approvals. If omitted, the value defaults to default. | default |
If the creation result is unknown, use the original clientToken and original business parameters to verify the result. Do not automatically change the token to initiate a new creation. The request Id is associated with only a single call and cannot replace clientToken.
Request example
{
"Jsonrpc": "2.0",
"Id": "request-001",
"Params": {
"clientToken": "create-review-001",
"_meta": {
"agent": {
"agentName": "review-agent-demo"
},
"initialConfigOptions": {
"approvalMode": "default"
}
}
}
}
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| RequestId |
string |
The server-side request ID. It is used to troubleshoot this call. |
0A1B2C3D-4E5F-6789-ABCD-EF0123456789 |
| JsonRpcResponse |
any |
The response object. The business result is located in |
{"jsonrpc":"2.0","id":"request-001","result":{"sessionId":"0123456789abcdef0123456789abcdef","attached":false}} |
| Success |
boolean |
Indicates whether the operation is successful. Determine the final execution state based on the description of this operation. |
true |
Optional fields may not be returned. Refer to the actual response.
| Name | Type | Description | Example |
JsonRpcResponse.jsonrpc | string | The JSON-RPC protocol version. | 2.0 |
JsonRpcResponse.id | string | The call identifier corresponding to the request Id. | request-001 |
JsonRpcResponse.result | any | The session creation result. | {"sessionId":"0123456789abcdef0123456789abcdef"} |
JsonRpcResponse.result.sessionId | string | The session ID. Use this value for subsequent session operations. | 0123456789abcdef0123456789abcdef |
JsonRpcResponse.result.attached | boolean | Indicates whether an existing session is reused. A value of true indicates that an existing session is reused. A value of false indicates that a new session is created. | false |
When an existing session is reused, the original configuration is retained. The initial approval mode in the request is not guaranteed to be reapplied. To read the current model, call GetAgentSessionModel.
Sample success response
{
"RequestId": "0A1B2C3D-4E5F-6789-ABCD-EF0123456789",
"Success": true,
"JsonRpcResponse": {
"jsonrpc": "2.0",
"id": "request-001",
"result": {
"sessionId": "0123456789abcdef0123456789abcdef",
"attached": false
}
}
}
Examples
Success response
JSON format
{
"RequestId": "0A1B2C3D-4E5F-6789-ABCD-EF0123456789",
"JsonRpcResponse": "{\"jsonrpc\":\"2.0\",\"id\":\"request-001\",\"result\":{\"sessionId\":\"0123456789abcdef0123456789abcdef\",\"attached\":false}}",
"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. | |
| 503 | ServiceUnavailable | The service is not ready or temporarily unavailable. | |
| 409 | AgentSession.CreateResultUnknown | The creation result is unknown. Retry with the same ClientToken to query the result. |
See Error CodesError Codes for a complete list.
Release notes
See Release NotesRelease Notes for a complete list.