Agent API Creation and External Invocation

Objective: Generate an API Key for a published Agent so it can be called by external systems, and obtain the official API documentation for integration.

Create an API Key

Enter the Agent's API Console

1. On the Agent orchestration page, click API Console in the upper-right corner.

2. After entering, you will see the API channels list page.

Create an API Channel

1. Click Add a new channel.

2. In the pop-up window, fill in:

   • Name: for example API

   • Description: for example API

3. Click Save to save.

Enter the Channel's key page

1. Find the record you just created in the channel list.

2. Click Learn More to enter the API Keys page.

Generate an API Key

1. Click Add a key.

2. In the pop-up window, set:

   • Name: for example API

   • Deadline: select the validity period as needed (for example, 3 Months)

3. Click Save to generate the key.

4. Copy and securely save the Key immediately (it is usually no longer fully displayed after the page is closed).

Obtain the API documentation and integrate

1. On the API Keys page, click Access Document.

2. In the documentation, copy the following information for external system integration:

   • Request URL (Endpoint)

   • Authentication method (usually Authorization: Bearer <API_KEY>)

   • Request body example (input parameters)

   • Response body example (output fields)

3. The external system can call the Agent by sending an HTTP request according to the examples in the documentation.

Call the API and Chat with the Agent

API Key Authentication

• Method: POST

• Endpoint: https://{host}/webapi/lite_api/v2/api/chat-with-bot/chat

• Header: api-key: YOUR_API_KEY

Key fields in the request body (JSON):

• messages (required): an array of conversation messages; role supports user/ai/system/human/assistant

• stream (optional, default false): whether to return a streaming response

• show_tool_result (optional, default false): whether to return tool results or references

• file_id (optional): file ID (string or array of strings)

• workspace_id (optional): workspace ID (string or array of strings)

• layout_mode (optional, default 0): 1 returns knowledge retrieval content, 0 for normal chat

• skip_hint (optional, default false): whether to skip the PII prompt

Notes:

• It is recommended that the role of the last message be human or user

• For image input, you must first call the "Upload Image API" to obtain image_ids

Minimal request example:

{
	"messages": [
		{"role": "system", "content": "Today is Monday"},
		{
			"role": "user",
			"content": [
				{"type": "text", "text": "Please describe the following images"},
				{"type": "image_ids", "image_ids": ["uuid1", "uuid2"]}
			]
		}
	],
	"stream": false,
	"show_tool_result": false
}

Successful response highlights:

• Non-streaming: data.full_output is the final answer, and data.tool_result is the optional tool result

• Streaming: the event stream includes stream, tool_result, and end

Access Token Authentication

• Method: POST

• Endpoint: https://{host}/webapi/lite_api/v2/api/chat-with-bot/{agent_id}

• Header: Authorization: Bearer YOUR_ACCESS_TOKEN

Path parameters:

• agent_id: the UUID of the target Agent (can be obtained from the Agent page URL)

Key fields in the request body (JSON):

• messages (required): role is limited to user/human, and the maximum array length is 1

• stream, show_tool_result, file_id, workspace_id, layout_mode, skip_hint (same as above)

• conversation_id (optional): multi-turn conversation session ID; if not provided, the system creates one and returns it in the response

Minimal request example:

{
	"messages": [
		{
			"role": "user",
			"content": [
				{"type": "text", "text": "Please describe the following images"},
				{"type": "image_ids", "image_ids": ["uuid1", "uuid2"]}
			]
		}
	],
	"stream": false,
	"show_tool_result": false,
	"layout_mode": 0,
	"conversation_id": null
}

Successful response highlights:

• data.conversation_id: used for reuse in subsequent multi-turn conversations

• data.full_output: the final answer

Upload Images

• Method: POST

• New Endpoint (recommended): https://{host}/webapi/lite_api/v2/api/chat-with-bot/upload-images

• Old Endpoint (to be deprecated soon): https://{host}/webapi/lite_api/v2/api/chat-with-bot/{agent_id}/upload-images

• Header (example): api-key: YOUR_API_KEY

• Content-Type: multipart/form-data

Request parameters:

• files (required): one or more image files

Successful response example:

{
	"code": 201,
	"data": {
		"ids": ["2973a321-905d-4f07-9ad4-ff0ef47a174f"]
	},
	"message": "success"
}

Description:

• Fill the returned ids into the image_ids field in messages[].content of the chat API to complete image-based Q&A.