Help Center/ PanguLargeModels/ API Reference/ API/ Agent APIs/ Calling a Workflow

Updated on 2025-07-28 GMT+08:00

View PDF

Calling a Workflow

Function

This API allows you to call the API of a created workflow and input a question to obtain the workflow execution result.

URI

POST /v1/{project_id}/workflows/{workflow_id}/conversations/{conversation_id}

For details about how to obtain the URI, see Request URI.

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain a project ID, see Obtaining the Project ID.
workflow_id	Yes	String	Workflow ID. For details about how to obtain the workflow ID, perform the following steps: On the Agent App Dev page, choose Workstation > Workflow in the navigation pane on the left. Locate the target workflow, click , and select Replication ID.
conversation_id	Yes	String	Conversation ID, which uniquely identifies a conversation. The conversation ID can be set to any value in the standard UUID format.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. Used to obtain the permission required to call APIs. The token is the value of X-Subject-Token in the response header in Authentication.
Content-Type	Yes	String	MIME type of the request body. The value is application/json.
stream	No	Boolean	Whether to enable streaming calling. true: Enable false: Disable

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
inputs	Yes	Map<String, Object>	User's question, which is used as the input to the workflow and corresponds to the WORKFLOW_STARTED parameter of the workflow. The default field query is entered by the user.
plugin_configs	No	List<PluginConfig>	Plug-in configurations. When a user-defined plug-in node is configured in a workflow, authentication information may be required. For details about the structure, see Table 4.

**Table 4** PluginConfig parameters
Parameter	Mandatory	Type	Description
plugin_id	Yes	String	Plug-in ID. To obtain the ID, perform the following steps: On the Agent App Dev page, choose Workstation > Plugin in the navigation pane. Locate the target plug-in, click , and select Replication ID.
config	Yes	Map<String, String>	Plug-in configurations. When the workflow is associated with a plug-in node and the plug-in requires user-level authentication, you need to configure the authentication information. For example, you can set config to {"key2": "value"} for the following plug-in. In other cases, this parameter does not need to be set. Specify an empty array for plugin_configs.

Response Parameters

Non-streaming (with stream set to false in the header)

Status code: 200

**Table 5** Data units output in non-streaming mode
Parameter	Type	Description
outputs	Map<String, Object>	Final output of the workflow. Multiple parameters are supported. NOTE: The following is an example of outputs: The responseContent parameter is available by default. The value is the Specify reply content of the workflow's end node. You can customize parameters in the Output params module of the workflow's end node. Customized parameters are displayed in the user_fields parameter. "outputs":{"user_fields":{"aaa":"1","vvv":[{"role":"user","content":"1"}]},"responseContent":" Hello! \uD83D\uDE0A You entered 1. Is there anything I can help you with? If you have any specific questions or requirements, feel free to let me know!"}
messages	List<Message>	Replies of the workflow assistant, such as the messages returned in the questioner node. For details, see Table 6.
status	Map<String, Object>	Status, including the status code and description.
start_time	Long	Start time.
end_time	Long	End time.

**Table 6** Message
Parameter	Type	Description
role	String	Conversation role, which can be user or assistant
content	String	Conversation content

Streaming (with stream set to true or not specified in the header)

Status code: 200

**Table 7** Data units output in streaming mode
Parameter	Type	Description
data	String	If stream is set to true, workflow execution messages will be returned in streaming mode. The generated text is returned incrementally. Each data field contains a part of the generated text until all data fields are returned.

**Table 8** Data units output in streaming mode
Parameter	Type	Description
event	String	Data unit type. The options are as follows: workflow_started: workflow start event, indicating that the workflow starts running. workflow_finished: workflow end event, indicating that the workflow ends. message: message event, indicating the message returned in streaming mode during workflow execution. error: error event, indicating the workflow execution error information. end: end event, indicating the request ends.
data	Object	Message block content, which varies depending on the event value.

**Table 9** Data unit of the workflow_started event
Parameter	Type	Description
start_time	Long	Workflow start time.

**Table 10** Data unit of the workflow_finished event
Parameter	Type	Description
start_time	Long	Workflow start time.
end_time	Long	Workflow end time.
outputs	Map<String, Object>	Final output of the workflow. Multiple parameters are supported. NOTE: The following is an example of outputs: The responseContent parameter is available by default. The value is the Specify reply content of the workflow's end node. You can customize parameters in the Output params module of the workflow's end node. Customized parameters are displayed in the user_fields parameter. "outputs":{"user_fields":{"aaa":"1","vvv":[{"role":"user","content":"1"}]},"responseContent":" Hello! \uD83D\uDE0A You entered 1. Is there anything I can help you with? If you have any specific questions or requirements, feel free to let me know!"}
status	Map<String, Object>	Status, including the status code and description.

**Table 11** Data unit of the message event
Parameter	Type	Description
text	String	Message block of the workflow output
index	Integer	Index of a message block
node_id	String	Node ID
node_type	String	Node type
node_name	String	Node name

**Table 12** Data unit of the error event
Parameter	Type	Description
code	String	Workflow execution error code
message	String	Workflow execution error message
node_id	String	Node ID
node_type	String	Node type
node_name	String	Node name

Example Request

POST https://{endpoint}/v1/{project_id}/agent-run/workflows/{workflow_id}/conversations/{conversation_id}

Request Header:   
Content-Type: application/json   
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...  
stream: true
Request Body:
{ 
  "inputs": {
    "query": "Hello"
  },
  "plugin_configs": [
    {
      "plugin_id": "xxxxxxxxx",
      "config": {
        "key": "value"
      }
    }
  ]
}

Example Response

Non-streaming (with stream set to false in the header)

Messages returned in the input node

{
    "conversation_id": "2c90493f-803d-431d-a197-57543d414317",
    "messages": [
        {
            "role": "assistant",
"content": "{\"inputs\": [{\"actualType\": \"string\", \"sourceType\": \"null\", \"description\": \"name\", \"name\": \"name\", \"type\": \"string\", \"required\": true}]}"
            "nodeId": "node_1745928389632",
            "nodeType": "Input",
"nodeName": " Input"
        }

    ],
    "status": {
        "code": 3,
        "desc": "waiting"
    },
    "start_time": 1734336269313,
    "end_time": 1734336270908
}

Messages returned in the questioner node

{
    "conversation_id": "f9a5540f-0c92-4f28-bd6e-f96ce04f5cc81",
    "messages": [
        {
            "role": "assistant",
"content": "Please provide your name and age.",
            "nodeId": "node_1745929628452",
            "nodeType": "Questioner",
"nodeName": "Questioner"
        }
    ],
    "status": {
        "code": 3,
        "desc": "waiting"
    },
    "start_time": 1745929778250,
    "end_time": 1745929779951
}

Messages returned in the end node

{
    "conversation_id": "2c90493f-803d-431d-a197-57543d414317",
    "outputs": {
        "responseContent": "Hello. How can I help you?"
    },
    "messages": [],
    "status": {
        "code": 1,
        "desc": "succeeded"
    },
    "start_time": 1734337068533,
    "end_time": 1734337082545
}

Streaming (with stream set to true or not specified in the header)

Messages returned in the input node

data:{"event":"workflow_started","data":{"start_time":1745929087614}}

data:{"event":"message","data":{"text":"{\"inputs\":[{\"actualType\": \"string\", \"sourceType\": \"null\", \"description\": \"name\", \"name\": \"name\", \"type\": \"string\", \"required\": true}]}","index":0,"node_id":"node_1745928389632","node_type":"Input","node_name":"Input"}}

data:{"event":"message","data":{"text":"","node_id":"node_1745928389632","node_type":"Input","node_name":" Input","is_finished":true}}

data:{"event":"end"}

Messages returned in the questioner node

data:{"event":"workflow_started","data":{"start_time":1745929709955}}

data:{"event":"message","data":{"text":"Please provide your name and age.","index":0,"node_id":"node_1745929628452","node_type":"Questioner","node_name":"Questioner"}}

data:{"event":"message","data":{"text":"","node_id":"node_1745929628452","node_type":"Questioner","node_name":" Questioner","is_finished":true}}

data:{"event":"end"}

Messages returned in the end node

data:{"event":"workflow_started","data":{"start_time":1745929897770}}

data:{"event":"message","data":{"text":"","index":0,"node_id":"node_end","node_type":"End","node_name":" End"}}

data:{"event":"message","data":{"text":"Hello","index":1,"node_id":"node_end","node_type":"End","node_name":"End"}}

data:{"event":"message","data":{"text":"!","index":2,"node_id":"node_end","node_type":"End","node_name":"End"}}

data:{"event":"message","data":{"text":"What can I do for you?","index":3,"node_id":"node_end","node_type":"End","node_name":"End"}}

data:{"event":"message","data":{"text":"","node_id":"node_end","node_type":"End","node_name":" end","is_finished":true}}

data:{"event":"workflow_finished","data":{"status":{"code":1,"desc":"succeeded"},"outputs":{"responseContent":""Hello! Is there anything I can help you with?","start_time":1745929897770,"end_time":1745929898600}}

data:{"event":"end"}