Help Center/ PanguLargeModels/ API Reference/ API/ Agent APIs/ Calling a Workflow
Updated on 2025-11-03 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.

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

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

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

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 Token-based Authentication.

Constraints

N/A

Range

N/A

Default Value

N/A

Content-Type

Yes

String

Definition

MIME type of the request body.

Constraints

N/A

Range

N/A

Default Value

application/json

stream

No

Boolean

Definition

Whether to enable streaming calling.

  • true: enabled
  • false: disabled

Constraints

N/A

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

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

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

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

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

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

Range

N/A

Default Value

N/A

status

Map<String, Object>

Definition

Status, including the status code and description.

Constraints

N/A

Range

N/A

Default Value

N/A

start_time

Long

Definition

Start time.

Constraints

N/A

Range

N/A

Default Value

N/A

end_time

Long

Definition

End time.

Constraints

N/A

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

Range

N/A

Default Value

N/A

content

String

Definition

Conversation content

Constraints

N/A

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

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

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

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

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

Range

N/A

Default Value

N/A

end_time

Long

Definition

Workflow end time.

Constraints

N/A

Range

N/A

Default Value

N/A

outputs

Map<String, Object>

Definition

Final output of the workflow. Multiple parameters are supported.

Constraints

N/A

Range

N/A

Default Value

N/A

status

Map<String, Object>

Definition

Status, including the status code and description.

Constraints

N/A

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

Range

N/A

Default Value

N/A

index

Integer

Definition

Index of a message block

Constraints

N/A

Range

N/A

Default Value

N/A

node_id

String

Definition

Node ID

Constraints

N/A

Range

N/A

Default Value

N/A

node_type

String

Definition

Node type that supports the output of message events

Constraints

N/A

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

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

Range

N/A

Default Value

N/A

message

String

Definition

Workflow execution error message

Constraints

N/A

Range

N/A

Default Value

N/A

node_id

String

Definition

Node ID

Constraints

N/A

Range

N/A

Default Value

N/A

node_type

String

Definition

Type of the node that sends the error event

Constraints

N/A

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

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