CreateAgentSession - DataWorks - Alibaba Cloud Documentation Center

Creates a new agent session and returns the session ID.

Operation description

This operation creates a new agent session.
Use _meta.agent.agentName to specify the agent name to bind. This parameter is required.
- dataworks_data_agent: DataWorks built-in agent — Data Agent. Provides intelligent data development AI capabilities that cover the entire process of data integration, development, O&M, governance, and analytics.
- dataworks_chatbi_agent: DataWorks built-in agent — ChatBI. Uses natural language processing and intelligent analytics to automate the entire process from requirement parsing, data extraction, and automatic code generation to visualization report output through conversational interaction.
Use _meta.config.sessionSource to pass through a session source identifier for subsequent retrieval by source.
Use _meta.config.sessionTags[].sessionTagCode to pass in session tags.

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.

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

dataworks:CreateAgentSession

create

*All Resource

*

None

Request syntax

POST  HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
Jsonrpc	string	No	The JSON-RPC version. Set the value to 2.0.	2.0
Id	string	No	The request ID specified by the caller. The value is returned as-is.	4758330557805415712
Params	object	No	The business parameters.
Meta	object	No	The extended metadata that contains agent binding, session source, and tag information.
Agent	object	No	The agent configuration for the session. Valid values are the results returned by the ListAgents operation.
AgentName	string	No	The agent name to bind to the session. This parameter is required.	dataworks_data_agent
Config	object	No	The session parameter settings, such as filtering parameter settings based on session source and session tags.
SessionSource	string	No	The identifier for the session source. This allows you to search for sessions by their source. For example, if you use an agent on multiple pages, such as Page A and Page B, you can use this parameter to filter and display only the sessions created on Page A. The identifier can be up to 128 characters and can contain letters, digits, hyphens (-), and underscores (_).	openapi_sdk
SessionTags	array<object>	No	A list of session tags. You can use these tags to search and filter sessions.
	object	No
SessionTagCode	string	No	The session tag. You can use session tags to filter sessions. For example, if your application calls the API with a fixed RAM sub-account but maintains its own user account system, you can pass a user's account ID as a tag. This allows you to filter the session list by your internal account IDs. The tag can be up to 128 characters and can contain letters, digits, hyphens (-), and underscores (_).	chatbi
InitialConfigOptions	object	No	The advanced parameter settings for the agent execution environment.
ExecutionLane	string	No		chat，cli
Mode	string	No		yolo
Skills	string	No		skill-name-1,skill-name2,skill-name-3
ResourceGroupId	string	No		Serverless_res_group_123123123_564657857

Response elements

Element	Type	Description	Example
	object	The response parameters (result).
RequestId	string	Id of the request	8A9D5E6C-5817-5837-9715-6E3967EC6123
JsonRpcResponse	object	The JSON-RPC response.
Jsonrpc	string	The JSON-RPC version. Set the value to 2.0.	2.0
Id	string	The request ID specified by the caller. The value is returned as-is.	1
Result	object	The business data. The value is null if an error occurs.
SessionId	string	The ID of the created session.	sess_0f12abc34

Examples

Success response

JSON format

{
  "RequestId": "8A9D5E6C-5817-5837-9715-6E3967EC6123",
  "JsonRpcResponse": {
    "Jsonrpc": "2.0",
    "Id": "1",
    "Result": {
      "SessionId": "sess_0f12abc34"
    }
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.