PromptAgentSession - PromptAgentSession-阿里云帮助中心

Sends a prompt to an existing session and streams the agent response.

Operation description

Request

This API sends a user prompt to a specified session ID and streams the agent's response over SSE (Server-Sent Events).
The response may include message chunks, thought process, and tool calling status updates.
If the specified session does not exist, the API returns a 400 error in an SSE error frame.
The stopReason field indicates why the agent ended the turn.
You can use multiple types of content blocks in the prompt, such as text and OSS file download links.
You can provide additional metadata in the Meta parameter to pass more context to the server.
The response content conforms to the open-source Agent Client Protocol (ACP) specification. For more information, see https://agentclientprotocol.com
**Review the billing methods and pricing for Data Agent before you use this API**: https://help.aliyun.com/zh/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

No authorization for this operation. If you encounter issues with this operation, contact technical support.

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 in by the caller. The value is returned as-is in the response.	1021418411
Params	object	No	The business parameters.
SessionId	string	No	The ID of the target session. If the session does not exist, an SSE error frame is returned.	sess_0f12abc34
Prompt	array	No	The array of user message content blocks. For more information, see https://agentclientprotocol.com/protocol/content
	array	No
Type	string	No	The content block type.	Valid values: text and resource_link.
Text	string	No	The text content.	This parameter takes effect when Type is set to text. Example: Sales amount in the last 7 days.
Uri	string	No	The URI of the file.	This parameter takes effect when Type is set to resource_link. Example: oss://${bucket}/${ossKey}.
Name	string	No	The file name.	This parameter takes effect when Type is set to resource_link. Example: xxx.csv.
MimeType	string	No	The MIME type of the file.	This parameter takes effect when Type is set to resource_link. Example: text/csv.
Size	integer	No	The size of the file. Unit: bytes.	This parameter takes effect when Type is set to resource_link. Example: 1231231.
Title	string	No	The title of the file.	This parameter takes effect when Type is set to resource_link. Example: Sales_Order_Details.csv.
Description	string	No	The description of the file.	This parameter takes effect when Type is set to resource_link. Example: Sales_Order_Details.csv.
Meta	object	No	The prompt metadata extended by DataWorks.
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 metadata.
Context	any	No	A Map-type value. In custom agent scenarios, you can use this parameter to replace placeholder parameters.	{ "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 in by the caller. The value is returned as-is in the response.	631478864897630XXXX
Result	any	The SSE frame result set. The response content conforms to the open-source Agent Client Protocol (ACP) specification. For more information, see https://agentclientprotocol.com/protocol/prompt-turn	{"stopReason":"end_turn"}
Error	any	The error information returned in the SSE frame. The response content conforms to the open-source Agent Client Protocol (ACP) specification. For more information, see https://agentclientprotocol.com/protocol/prompt-turn	{"code": 400, "errorCode": "0x50000000001", "message": "not exist session", "data": null}
Method	string	The SSE method. The response content conforms to the open-source Agent Client Protocol (ACP) specification. For more information, see https://agentclientprotocol.com/protocol/prompt-turn	session/update
Params	any	The SSE params. The response content conforms to the open-source Agent Client Protocol (ACP) specification. For more information, see 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.