PromptAgentSession-DataWorks(DataWorks)-阿里云帮助中心

Sends a user prompt to an existing session and returns the Agent response in streaming mode.

Operation description

This API sends a user prompt to a specified session ID and accepts the Agent response in SSE (Server-Sent Events) streaming mode.
The response may include message fragments, thinking procedures, tool calling status updates, and other information.
If the specified session does not exist, a 400 fault is returned through an SSE error frame.
The stopReason field indicates why the Agent stopped the current conversation turn.
Multiple types of content blocks are supported as prompt input, such as text and OSS file download links.
You can optionally provide additional meta information Meta to pass more context to the server.
The returned content conforms to the open-source Agent Client Protocol (ACP) specification. For more information, visit: https://agentclientprotocol.com
Before invoking this API, make sure you fully understand the billing methods and pricing of the Data Agent product: https://www.alibabacloud.com/help/en/dataworks/dataworks-data-agent-agent-billing

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:PromptAgentSession

none

*All Resource

*

None

Request syntax

POST  HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
Jsonrpc	string	No	The JSON-RPC version. Fixed value: 2.0.	2.0
Id	string	No	The ID passed by the requester. The value is returned as-is.	1021418411
Params	object	No	The business parameters.
SessionId	string	No	The target session ID. If the session does not exist, an SSE error frame is returned.	sess_0f12abc34
Prompt	array<object>	No	The array of user message content blocks. For more information, visit: https://agentclientprotocol.com/protocol/content.
	array<object>	No
Type	string	No	The content block type.	Currently supported: text, resource_link.
Text	string	No	The text content.	Effective when Type=text. Example: Sales amount in the last 7 days.
Uri	string	No	The URI of the file.	Effective when Type=resource_link. Example: oss://${bucket}/${ossKey}
Name	string	No	The file name.	Effective when Type=resource_link. Example: xxx.csv.
MimeType	string	No	The MIME type of the file.	Effective when Type=resource_link. Example: text/csv.
Size	integer	No	The size of the file. Unit: bytes.	Effective when Type=resource_link. Example: 1231231
Title	string	No	The title of the file.	Effective when Type=resource_link. Example: SalesOrderDetails.csv.
Description	string	No	The file description.	Effective when Type=resource_link. Example: SalesOrderDetails.csv.
Meta	object	No	The DataWorks extended prompt meta information.
Hide	boolean	No	Specifies whether to hide the prompt from the user. For example, if a user asks "Sales amount in the last 7 days" in a chat dialog, the calling system may use RAG to retrieve relevant business domain knowledge and append it to the agent context before calling the API. If you do not want to display this supplemental information to the user, set this parameter to true.	true or false
Meta	object	No	The extended meta information. Important If the Agent bound to the specified session is named dataworks_ai_assistant_agent (AI Assistant Service), provide the instance ID of the AI Assistant Service in the Context.agent.instanceId field of the extended meta information.
Context	any	No	A Map type. In custom Agent scenarios, some placeholder parameters can be replaced through this value.	{ "key1": "value1", "key2": "value2" }

Response elements

Element	Type	Description	Example
	object
RequestId	string	Id of the request	D5D70885-7CC7-594A-80C7-2EF1B00FFB4B
Timestamp	integer	The timestamp.	1747447032
Jsonrpc	string	The JSON-RPC version. Fixed value: 2.0.	2.0
Id	string	The ID passed by the requester. The value is returned as-is.	631478864897630XXXX
Result	any	The SSE frame result set. The returned content conforms to the open-source Agent Client Protocol (ACP) specification. For more information, visit: https://agentclientprotocol.com/protocol/prompt-turn.	{"stopReason":"end_turn"}
Error	any	The SSE frame error message. The returned content conforms to the open-source Agent Client Protocol (ACP) specification. For more information, visit: https://agentclientprotocol.com/protocol/prompt-turn.	{"code": 400, "errorCode": "0x50000000001", "message": "not exist session", "data": null}
Method	string	The SSE method. The returned content conforms to the open-source Agent Client Protocol (ACP) specification. For more information, visit: https://agentclientprotocol.com/protocol/prompt-turn.	session/update
Params	any	The SSE params. The returned content conforms to the open-source Agent Client Protocol (ACP) specification. For more information, visit: https://agentclientprotocol.com/protocol/prompt-turn.	{"sessionId":"af4f5ef8-e8f5-481c-ad1f-94886c6c0aed","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"hello world"}}}

Examples

Success response

JSON format

{
  "RequestId": "D5D70885-7CC7-594A-80C7-2EF1B00FFB4B",
  "Timestamp": 1747447032,
  "Jsonrpc": "2.0",
  "Id": "631478864897630XXXX",
  "Result": "{\"stopReason\":\"end_turn\"}\n",
  "Error": "{\"code\": 400, \"errorCode\": \"0x50000000001\", \"message\": \"not exist session\", \"data\": null}",
  "Method": "session/update",
  "Params": "{\"sessionId\":\"af4f5ef8-e8f5-481c-ad1f-94886c6c0aed\",\"update\":{\"sessionUpdate\":\"agent_message_chunk\",\"content\":{\"type\":\"text\",\"text\":\"hello world\"}}}"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.