Calling an Application

Function

Allows you to call the API of a created application and input a question to obtain the application 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}/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	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
agent_id	Yes	String	Definition: 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. 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	Yes	Boolean	Definition: Whether to enable streaming calling. This function is enabled by default. Constraints: Currently, the agent supports only streaming calling. Therefore, set this parameter to true. Value range: true: enabled false: disabled Default value: N/A

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
query	Yes	String	Definition: User's question, used as the input to the agent. Constraints: N/A Value range: N/A Default value: N/A

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	Definition: 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. Constraints: N/A Value range: N/A Default value: N/A

**Table 5** Data units output in streaming mode
Parameter	Type	Description
event	String	Definition: Data unit type. Constraints: N/A Value range: 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. Default value: N/A
content	Object	Definition: Message block content, which varies depending on the event value. Constraints: N/A Value range: N/A Default value: N/A
createdTime	long	Definition: Timestamp for returning the message block, for example, 1733817348963. Constraints: N/A Value range: N/A Default value: N/A
latency	Object	Definition: 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 Constraints: N/A Value range: N/A Default value: N/A
plugin	Object	Definition: Plug-in request, including the following elements: name: plug-in name arguments: input parameters of the plug-in Constraints: N/A Value range: N/A Default value: N/A

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":"duration","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}