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

Calling an Application

Function

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

URI

POST /v1/{project_id}/agents/{agent_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.

agent_id

Yes

String

Agent ID. For details about how to obtain the agent ID, perform the following steps:

On the Agent App Dev page, choose Workstation > Application in the navigation pane. Locate the target agent, 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

Yes

Boolean

Whether to enable streaming calling. This function is enabled by default.

  • true: Enable
  • false: Disable
NOTE:

Currently, the agent supports only streaming calling. Therefore, set this parameter to true.

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

query

Yes

String

User's question, used as the input to the agent.

Response Parameters

Streaming (with stream set to true in the header)

Status code: 200

Table 4 Data units output in streaming mode

Parameter

Type

Description

data

String

  • If stream is set to true, agent 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 5 Data units output in streaming mode

Parameter

Type

Description

event

String

Data unit type. The options are as follows:

  • start: start node, indicating that the model is called to start a conversation.
  • message: message node, indicating the message returned by the model.
  • plugin_start: plug-in request node, indicating the request for calling a plug-in.
  • plugin_end: plug-in response node, indicating the response to calling a plug-in.
  • statistic_data: execution data node, including the time consumed by the current call.
  • summary_response: message summary node, including the full response information of the current call.
  • done: end node, indicating that the streaming call ends.

content

Object

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

createdTime

long

Timestamp for returning the message block, for example, 1733817348963.

latency

Object

Time consumed, including the following elements:

  • plugin: time consumed for calling the plug-in
  • model: time consumed for calling the model
  • overall: total consumed time

plugin

Object

Plug-in request, including the following elements:

  • name: plug-in name
  • arguments: input parameters of the plug-in

Example Request

Streaming (with stream set to true in the header)

POST https://{endpoint}/v1/{project_id}/agent-run/agents/{agent_id}/conversations/{conversation_id}

Request Header:   
Content-Type: application/json   
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...  
stream: true    

Request Body:
{ 
  "query": "Query the status of meeting room A12 from 09:00 to 10:00."
}

Example Response

data:{"event":"start","createdTime":1735558575017}

data:{"event":"message","content":":OK","createdTime":1735558576300}

data:{"event":"message","content":",","createdTime":1735558576301}

data:{"event":"message","content":"I will","createdTime":1735558576301}

data:{"event":"message","content":"call the","createdTime":1735558576302}

data:{"event":"message","content":"query","createdTime":1735558576302}

data:{"event":"message","content":"_","createdTime":1735558576302}

data:{"event":"message","content":"meeting","createdTime":1735558576302}

data:{"event":"message","content":"_","createdTime":1735558576302}

data:{"event":"message","content":"room","createdTime":1735558576303}

data:{"event":"message","content":"_status","createdTime":1735558576303}

data:{"event":"message","content":"tool","createdTime":1735558576303}

data:{"event":"message","content":"to","createdTime":1735558576304}

data:{"event":"message","content":"query","createdTime":1735558576304}

data:{"event":"message","content":"A","createdTime":1735558576304}

data:{"event":"message","content":"12","createdTime":1735558576304}

data:{"event":"message","content":"meeting room","createdTime":1735558576305}

data:{"event":"message","content":"from","createdTime":1735558576305}

data:{"event":"message","content":"9","createdTime":1735558576305}

data:{"event":"message","content":":00","createdTime":1735558576305}

data:{"event":"message","content":"to","createdTime":1735558576306}

data:{"event":"message","content":"10","createdTime":1735558576306}

data:{"event":"message","content":":00","createdTime":1735558576306}

data:{"event":"message","content":"status","createdTime":1735558576306}

data:{"event":"message","content":".","createdTime":1735558576306}

data:{"event":"message","content":"Please","createdTime":1735558576307}

data:{"event":"message","content":"wait","createdTime":1735558576307}

data:{"event":"message","content":"a moment","createdTime":1735558576307}

data:{"event":"message","content":".","createdTime":1735558576307}

data:{"event":"message","content":" ","createdTime":1735558576307}

data:{"event":"message","content":" query","createdTime":1735558576307}

data:{"event":"message","content":"_","createdTime":1735558576308}

data:{"event":"message","content":"meeting","createdTime":1735558576308}

data:{"event":"message","content":"_","createdTime":1735558576308}

data:{"event":"message","content":"room","createdTime":1735558576308}

data:{"event":"message","content":"_status","createdTime":1735558576308}

data:{"event":"message","content":"|","createdTime":1735558576308}

data:{"event":"message","content":"{\"","createdTime":1735558576309}

data:{"event":"message","content":"meeting","createdTime":1735558576309}

data:{"event":"message","content":"Room","createdTime":1735558576309}

data:{"event":"message","content":"\":","createdTime":1735558576309}

data:{"event":"message","content":"{\"","createdTime":1735558576309}

data:{"event":"message","content":"number","createdTime":1735558576310}

data:{"event":"message","content":"\":","createdTime":1735558576310}

data:{"event":"message","content":" 12","createdTime":1735558576310}

data:{"event":"message","content":"}","createdTime":1735558576310}

data:{"event":"message","content":",\"","createdTime":1735558576310}

data:{"event":"message","content":"start","createdTime":1735558576310}

data:{"event":"message","content":"\":\"","createdTime":1735558576311}

data:{"event":"message","content":"9","createdTime":1735558576311}

data:{"event":"message","content":":00","createdTime":1735558576311}

data:{"event":"message","content":"\",\"","createdTime":1735558576311}

data:{"event":"message","content":"end","createdTime":1735558576311}

data:{"event":"message","content":"\":\"","createdTime":1735558576311}

data:{"event":"message","content":"10","createdTime":1735558576311}

data:{"event":"message","content":":00","createdTime":1735558576312}

data:{"event":"message","content":"\"}","createdTime":1735558576312}

data:{"event":"message","content":" ","createdTime":1735558576312}

data:{"event":"plugin_start","type":"plugin","latency":{"overall":1.3},"plugin":{"name":"query_meeting_room_status","arguments":"{\"meetingRoom\": {\"number\": 12}, \"start\": \"9:00\", \"end\": \"10:00\"}"},"createdTime":1735558576316}

data:{"event":"plugin_end","content":{"result":"Idle"},"role":"function","latency":{"overall":1.51,"plugin":0.0},"createdTime":1735558576521}

data:{"event":"start","createdTime":1735558576522}

data:{"event":"message","content":"A","createdTime":1735558576976}

data:{"event":"message","content":"12","createdTime":1735558576977}

data:{"event":"message","content":"meeting room","createdTime":1735558576977}

data:{"event":"message","content":"from","createdTime":1735558576977}

data:{"event":"message","content":"9","createdTime":1735558576978}

data:{"event":"message","content":":00","createdTime":1735558576978}

data:{"event":"message","content":"to","createdTime":1735558576978}

data:{"event":"message","content":"10","createdTime":1735558576978}

data:{"event":"message","content":":00","createdTime":1735558576978}

data:{"event":"message","content":"in","createdTime":1735558576978}

data:{"event":"message","content":"this","createdTime":1735558576979}

data:{"event":"message","content":"during","createdTime":1735558576979}

data:{"event":"message","content":"is","createdTime":1735558576979}

data:{"event":"message","content":"idle","createdTime":1735558576979}

data:{"event":"message","content":".","createdTime":1735558576979}

data:{"event":"message","content":" ","createdTime":1735558576980}

data:{"event":"statistic_data","latency":{"overall":1.97},"createdTime":1735558576986}

data:{"event":"summary_response","content":"A12 meeting room from 09:00 to 10:00 in this duration is idle. ","role":"assistant","createdTime":1735558576987}

data:{"event":"done","createdTime":1735558577011}

Status Codes

For details, see Status Codes.

Error Codes

For details, see Error Codes.