Enables web search and contextual conversation using the Qwen web search agent's agent_id and agent_version.
Request syntax
Request parameters
- Note: If you provide dynamic parameters in the request, they override the corresponding status values in the application configuration.
Parameter | Type | Required | Description |
|---|---|---|---|
stream | bool | Yes | Must be set to |
input | object | Yes | Input fields. |
input.request_id | str | No | A user-defined request ID. |
input.messages | array[object] | Yes | A list of conversation messages. |
input.messages.[].role | str | Yes | The role of the message sender. Valid values: |
input.messages.[].content | str | Yes | The content of the message. |
parameters | object | Yes | Configuration parameters. |
parameters.agent_options | object | Yes | Agent-specific parameters. |
parameters.agent_options.agent_id | string | Yes | The application ID. |
parameters.agent_options.agent_version | string | Yes | The application version. |
parameters.agent_options.session_knowledge | string | No | Specifies the session-level knowledge to use. |
parameters.agent_options.system_prompt | string | No | Specifies the system prompt. |
parameters.agent_options.agent_policy | string | No | The execution policy.
|
parameters.agent_options.forced_search | bool | No | Specifies whether to force a search.
|
parameters.agent_options.enable_citation | bool | No | Specifies whether to include citations in the response. |
parameters.agent_options.enable_text_image_mixed | bool | No | Specifies whether to enable text-image mixed generation. |
parameters.agent_options.enable_lemma | bool | No | Specifies whether to include encyclopedia entries in the response. |
parameters.agent_options.related_video | bool | No | Specifies whether to include related videos in the response. |
parameters.agent_options.enable_rec_question | bool | No | Specifies whether to include related questions in the response. |
parameters.agent_options.show_step_info | bool | No | Specifies whether to include tool call status information in the response. The default value is |
parameters.agent_options.location | object | No | Location information for the request. |
parameters.agent_options.location.address | string | No | The specific address. |
parameters.agent_options.location.province | string | No | The province. |
parameters.agent_options.location.city | string | No | The city. |
parameters.agent_options.location.district | string | No | The district or county. |
parameters.agent_options.location.longitude | string | No | The longitude, accurate to 6 decimal places. |
parameters.agent_options.location.latitude | string | No | The latitude, accurate to 6 decimal places. |
Response parameters
Parameter | Type | Required | Description |
|---|---|---|---|
request_id | str | Yes | The request ID from the DashScope platform. |
code | str | Yes | The status code. |
message | str | Yes | The status message. |
output | object | Yes | The output object. |
output.request_id | str | No | A custom request ID defined by your application. |
output.choices | array[object] | Yes | A list of completion choices generated by the model. |
output.choices.[].finish_reason | str | Yes | The finish reason. A value of |
output.choices.[].message | object | Yes | The message object. |
output.choices.[].message.role | str | Yes | The role of the message author. Valid values: |
output.choices.[].message.content | str | array[object] | Yes | The text generated by the model, or the output from a tool. |
output.choices.[].message.reasoning_content | str | No | The model's thought process or reasoning steps. |
output.choices.[].message.tool_calls | array[object] | No | The tool calls requested by the model. |
output.choices.[].message.tool_calls[0].arguments | dict[str,object] | No | The arguments to pass to the tool function. |
output.choices.[].message.tool_calls[0].name | str | No | The name of the tool to call. |
output.choices.[].message.additional_kwargs.extra_json | Any | No | Additional structured data associated with a tool call. |
output.choices.[].message.extra | dict | No | Contains details about the current execution step. |
output.choices.[].message.extra.group | str | No | The execution phase. |
output.choices.[].message.extra.step_change | str | No | The step change event. |
output.choices.[].message.extra.step | str | No | The current step. |
output.choices.[].message.response_metadata | dict | No | Details about the model invocation for the request. |
output.usage | object | No | Usage statistics. |
output.usage.input_tokens | int | No | The number of input tokens. |
output.usage.output_tokens | int | No | The number of output tokens. |
output.usage.total_tokens | int | No | The total number of tokens. |
Execution stage enumeration
Execution stage ( | Description | Description |
|---|---|---|
planning | planning | Associated with the |
generating | generating | Associated with the |
Current step ( | Description |
|---|---|
planning | planning |
generating | generating |
tool_calling | tool calling |
tool_calling_{tool_name} | A tool call is in progress. The specific tool is identified by its name. |
- Due to model limitations, the
step_changevalue may be absent. Use the persistentstepflag whenever possible. - For an empty packet, the
step,step_change, andgroupfields may be absent. - The
planandgenerationprocesses each consist of a*_startevent and a*_endevent. - A
tool_callconsists of three events:tool_call_start,tool_calling, andtool_return. tool_call_startindicates the beginning of a tool call. The system emits thetool_callingevent after gathering the complete tool call parameters; this event contains the parameters.tool_returncontains the structured result from the tool.
Value of | Step change event ( | Event name | Description |
|---|---|---|---|
| plan_start | planning start | The |
| (empty) | planning | Indicates the system is reasoning or performing tool calls. |
| plan_end | planning end | When the |
| generation_start | generation start | Similar to the |
| (empty) | generating | Indicates the system is generating output. |
| generation_end | generation end | Similar to the |
| tool_call_start | tool call start | Indicates the start of a tool call. |
| tool_calling | tool calling | Contains the specific parameters and name for the tool call. The |
| tool_return | tool return | The response contains the tool return information, and the |
Step value and tool name mapping
When a tool is called, the ["extra"]["step"] field contains a value, such as tool_calling_xx, that identifies the tool used. The following tables map each step value to its corresponding tool name.
Text QA
Step value | Tool name |
tool_calling_search | web search |
tool_calling_visit | web page reading |
tool_calling_video_search | video search |
tool_calling_lemma_search | Baidu entry |
tool_calling_query_suggesting | follow-up query |
Multimodal QA
In addition to the text QA tools, this mode adds text-to-image search and reverse image search.
Step value | Tool name |
tool_calling_image_search | text-to-image search |
tool_calling_image_to_image_search | reverse image search |
Local service POI tools
Step value | Tool name |
tool_calling_poi_search | keyword search |
tool_calling_around_search | nearby search |
Tool call status
Parameters
The status of a tool call is in the ["extra"]["step_change"] field of the message. Detailed information about the call is in the ["extra"]["step_info"] field. The following table maps tool call statuses to their corresponding status information.
Tool call status | Description | Status information ( |
tool_call_start | Start tool call | Starting to call the [tool_name] tool. |
tool_calling | Calling tool | Calling the [tool_name] tool. |
tool_return | Tool call completed | Call to the [tool_name] tool completed: [result_details]. |
Rich media message protocol
When rich media is enabled, the model interleaves text with images by embedding them in the message body with the HTML <img> tag, as shown in the example below:
data-type: Specifies the data type. A value ofimageindicates image data.src: The URL of the image.data-url: The URL of the image's source content page.data-title: The image title.width/height: The image's width and height.
additional_kwargs field contains the following two fields:
-
data_type: For a rich media message containing an image, this value is set toimage. -
data_json: A JSON array of all images related to the content. Only one of these images is displayed in the message body.-
In
data_json, each image object contains the following fields:idx: The image ID.url: The source URL of the image's content page.title: The image title.published: The publication date of the source content.image_info["url"]: The URL of the image file.image_info["width"]: The image width.image_info["height"]: The image height.
-
In
Render local life POI cards
When local life is enabled, the model returns location-based Point of Interest (POI) search results. If rich text and image display is also enabled, the POI search results include images. Images in the message body use the standard HTML image format, as shown in the following example:
data-type: The data type. A value ofpoiindicates a map card.src: The URL of the first image for the card.data-url: The Amap URL that corresponds to the card.data-title: The card title.width/height: The width and height of the image.
additional_kwargs field includes the following fields:
data_type: For map card images, the value ispoi.data_json: A JSON object of all related map cards. Although the message body displays only one card, this field contains all relevant cards.
data_json, each map card uses the following fields:
Field | Type | Description |
|---|---|---|
name | string | The place name. |
id | string | The unique identifier for the place. |
distance | string | The distance from the center point, in meters. This field is returned only for nearby searches. |
location | string | The longitude and latitude of the POI. |
type | string | The POI category. |
typecode | string | The category code of the POI. |
pname | string | The province where the POI is located. |
cityname | string | The city where the POI is located. |
adname | string | The district where the POI is located. |
address | string | The detailed address of the POI. |
photos | array | Contains information about the POI images. |
photos[].title | string | A description of the POI image. |
photos[].url | string | The download URL for the POI image. |
business | object | If available, contains the business information for the POI. |
business
Field | Type | Description |
|---|---|---|
business_area | string | The business area where the POI is located. |
opentime_today | string | Today's business hours for the POI, such as 08:30-17:30, 08:30-09:00, 12:00-13:30, or 09:00-13:00. |
opentime_week | string | A text description of the POI's weekly business hours. For example: "Monday to Friday: 08:30-17:30 (extended service hours: 08:30-09:00; 12:00-13:30); Saturday extended service hours: 09:00-13:00 (excluding legal holidays)". |
tel | string | The contact number for the POI. |
tag | string | Highlights of the POI. This field is currently returned only for dining POIs. |
rating | string | The rating of the POI. This field is currently returned only for POIs in the dining, hotel, attraction, and cinema categories. |
cost | string | The average spend at the POI. This field is currently returned only for POIs in the dining, hotel, attraction, and cinema categories. |
parking_type | string | The parking type (underground, ground-level, or roadside). This field is currently returned only for parking lot POIs. |
Multimodal image Q&A
The Web Search Agent multimodal API lets you include images in your conversations. Provide an image URL with your question, and the Agent will interpret the image, call the necessary tools, and generate a response.
Request parameters
Parameter | Type | Required | Description |
|---|---|---|---|
input | object | Yes | The request's input object. |
input.messages | array | Yes | The list of messages in the conversation. |
input.messages[].role | string | Yes | The message sender's role. The value must be |
input.messages[].content | array | Yes | An array of content parts, which can be text or images. |
input.messages[].content[].type | string | No | The type of the content part. For images, set this to 1. URL format (Recommended): https://example.com/image.jpg 2. Base64 format: |
input.messages[].content[].image_url | object | Conditional | An object containing the image URL. Required if |
Examples
Sample requests
- Text request
- Multimodal request