Help Center/ PanguLargeModels/ API Reference/ API/ Agent APIs/ Calling a Workflow
Updated on 2026-02-13 GMT+08:00
View PDF
Share

Calling a Workflow

Function

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

Authorization Information

An account has required permissions to call all APIs by default. To call this API as an IAM user, the IAM user must be granted the required permissions. For details, see Permissions and Supported Actions.

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

Definition:

Project ID. For details about how to obtain a project ID, see Obtaining the Project ID.

Constraints:

N/A

Value range:

N/A

Default value:

N/A

workflow_id

Yes

String

Definition:

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.

Constraints:

N/A

Value range:

N/A

Default value:

N/A

conversation_id

Yes

String

Definition:

Conversation ID, which uniquely identifies a conversation. The conversation ID can be set to any value in the standard UUID format.

Constraints:

N/A

Value range:

N/A

Default value:

N/A

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Definition:

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 Figure 4.

Constraints:

N/A

Value range:

N/A

Default value:

N/A

Content-Type

Yes

String

Definition:

MIME type of the body in the request.

Constraints:

N/A

Value range:

N/A

Default value:

application/json

stream

No

Boolean

Definition:

Whether to enable streaming calling.

  • true: enabled.
  • false: disabled.

Constraints:

N/A

Value range:

N/A

Default value:

N/A
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

inputs

Yes

Map<String, Object>

Definition:

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.

Constraints:

N/A

Value range:

N/A

Default value:

N/A

plugin_configs

No

List<PluginConfig>

Definition:

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.

Constraints:

N/A

Value range:

N/A

Default value:

N/A
Table 4 PluginConfig parameters

Parameter

Mandatory

Type

Description

plugin_id

Yes

String

Definition:

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.

Constraints:

N/A

Value range:

N/A

Default value:

N/A

config

Yes

Map<String, String>

Definition:

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.

Constraints:

N/A

Value range:

N/A

Default value:

N/A

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>

Definition:

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!"}

Constraints:

N/A

Value range:

N/A

Default value:

N/A

messages

List<Message>

Definition:

Replies of the workflow assistant, such as the messages returned in the questioner node. For details, see Table 6.

Constraints:

N/A

Value range:

N/A

Default value:

N/A

status

Map<String, Object>

Definition:

Status, including the status code and description.

Constraints:

N/A

Value range:

N/A

Default value:

N/A

start_time

Long

Definition:

Start time.

Constraints:

N/A

Value range:

N/A

Default value:

N/A

end_time

Long

Definition:

End time.

Constraints:

N/A

Value range:

N/A

Default value:

N/A
Table 6 Message

Parameter

Type

Description

role

String

Definition:

Conversation role, which can be user or assistant

Constraints:

N/A

Value range:

N/A

Default value:

N/A

content

String

Definition:

Conversation content

Constraints:

N/A

Value range:

N/A

Default value:

N/A

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

Definition:

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.

Constraints:

N/A

Value range:

N/A

Default value:

N/A
Table 8 Data units output in streaming mode

Parameter

Type

Description

event

String

Definition:

Data unit type.

Constraints:

N/A

Value range:

  • 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.

Default value:

N/A

data

Object

Definition:

Message block content, which varies depending on the event value.

Constraints:

N/A

Value range:

N/A

Default value:

N/A
Table 9 Data unit of the workflow_started event

Parameter

Type

Description

start_time

Long

Definition:

Workflow start time.

Constraints:

N/A

Value range:

N/A

Default value:

N/A
Table 10 Data unit of the workflow_finished event

Parameter

Type

Description

start_time

Long

Definition:

Workflow start time.

Constraints:

N/A

Value range:

N/A

Default value:

N/A

end_time

Long

Definition:

Workflow end time.

Constraints:

N/A

Value range:

N/A

Default value:

N/A

outputs

Map<String, Object>

Definition:

Final output of the workflow. Multiple parameters are supported.

Constraints:

N/A

Value range:

N/A

Default value:

N/A

status

Map<String, Object>

Definition:

Status, including the status code and description.

Constraints:

N/A

Value range:

N/A

Default value:

N/A
Table 11 Data unit of the message event

Parameter

Type

Description

text

String

Definition:

Message block of the workflow output

Constraints:

N/A

Value range:

N/A

Default value:

N/A

index

Integer

Definition:

Index of a message block

Constraints:

N/A

Value range:

N/A

Default value:

N/A

node_id

String

Definition:

Node ID

Constraints:

N/A

Value range:

N/A

Default value:

N/A

node_type

String

Definition:

Node type that supports the output of message events

Constraints:

N/A

Value range:

Message: message node.

End: end node.

Questioner: questioner node.

Input: input node.

Default value:

N/A

node_name

String

Definition:

Node name

Constraints:

N/A

Value range:

N/A

Default value:

N/A
Table 12 Data unit of the error event

Parameter

Type

Description

code

String

Definition:

Workflow execution error code

Constraints:

N/A

Value range:

N/A

Default value:

N/A

message

String

Definition:

Workflow execution error message

Constraints:

N/A

Value range:

N/A

Default value:

N/A

node_id

String

Definition:

Node ID

Constraints:

N/A

Value range:

N/A

Default value:

N/A

node_type

String

Definition:

Type of the node that sends the error event

Constraints:

N/A

Value range:

Start: start node.

End: end node.

LLM: large model node.

Workflow: workflow node.

Agent: agent node.

Branch: branch node.

IntentDetection: IntentDetection node.

Code: code node.

Loop: loop node.

Plugin: plugin node.

Mcp: MCP Service node.

Message: message node.

Questioner: questioner node.

Input: input node.

SetVariable: Variable Assignment node.

Aggregation: Aggregation node.

KnowledgeRepo: Knowledge Repo node.

Unknown: unknown node.

Default value:

N/A

node_name

String

Definition:

Node name

Constraints:

N/A

Value range:

N/A

Default value:

N/A

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"}

Status Codes

For details, see Status Codes.

Error Codes

For details, see Error Codes.

Parent topic: Agent APIs