Agent API 创建与外部调用

目标：给已发布的 Agent 生成可供外部系统调用的 API Key，并拿到官方调用文档进行对接。

创建API Key

进入 Agent 的 API Console

在 Agent 编排页右上角点击 API Console。
进入后会看到 API channels 列表页。

创建 API Channel

点击 Add a new channel。
在弹窗中填写：
- Name：如 API
- Description：如 API
点击 Save 保存。

进入 Channel 的密钥页

在 channel 列表中找到刚创建的记录。
点击 Learn More 进入 API Keys 页面。

生成 API Key

点击 Add a key。
在弹窗中设置：
- Name：如 API
- Deadline：按需求选择有效期（如 3 Months）
点击 Save 生成密钥。
立即复制并安全保存 Key（页面关闭后通常不再完整展示）。

获取调用文档并对接

在 API Keys 页面点击 Access Document。
在文档中复制以下信息用于外部系统接入：
- 请求地址（Endpoint）
- 鉴权方式（通常是 Authorization: Bearer <API_KEY>）
- 请求体示例（输入参数）
- 返回体示例（输出字段）
外部系统按文档示例发起 HTTP 请求即可调用该 Agent。

调用接口与 Agent 聊天

API Key 授权

Method: POST
Endpoint: https://{host}/webapi/lite_api/v2/api/chat-with-bot/chat
Header: api-key: YOUR_API_KEY

请求体（JSON）关键字段：

messages（必填）：对话消息数组，role 支持 user/ai/system/human/assistant
stream（可选，默认 false）：是否流式返回
show_tool_result（可选，默认 false）：是否返回工具结果或引用
file_id（可选）：文件 ID（字符串或字符串数组）
workspace_id（可选）：工作空间 ID（字符串或字符串数组）
layout_mode（可选，默认 0）：1 返回知识检索内容，0 正常聊天
skip_hint（可选，默认 false）：是否跳过 PII 提示

注意：

最后一条消息的 role 建议使用 human 或 user
图片输入需先调用“上传图片 API”获取 image_ids

最小请求示例：

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

成功响应要点：

非流式：data.full_output 为最终回答，data.tool_result 为可选工具结果
流式：事件流包含 stream、tool_result、end

获取 Access Token

Access Token 通过以下三步获取：创建 Client → 查询 Client 获得凭证 → 生成 Token。

1. 创建 Client

Method: POST
Endpoint: https://{host}/webapi/lite_api/v1/admin/clients
Header: Authorization: Bearer YOUR_ADMIN_TOKEN

请求体（JSON）关键字段：

name（必填）：Client 名称
description（可选）：描述
trusted domains（可选）：可信域名列表，默认为空数组

curl --location 'https://{host}/webapi/lite_api/v1/admin/clients' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ADMIN_TOKEN' \
  --data '{
    "name": "测试",
    "description": "测试",
    "trusted domains": []
  }'

成功响应中会返回 client_id 与 client_secret，请妥善保存。

2. 查询 Client 列表（可选）

如需查看已创建的 Client 及其 client_id，可通过以下接口查询：

Method: GET
Endpoint: https://{host}/webapi/lite_api/v1/admin/clients?page=1&page_size=10
Header: Authorization: Bearer YOUR_ADMIN_TOKEN

curl --location 'https://{host}/webapi/lite_api/v1/admin/clients?page=1&page_size=10' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ADMIN_TOKEN'

3. 生成 Access Token

使用步骤 1 获取的 client_id 和 client_secret 生成访问令牌：

Method: POST
Endpoint: https://{host}/webapi/lite_api/v1/iam/client_token

请求体（JSON）关键字段：

client_id（必填）：创建 Client 时获取的 ID
client_secret（必填）：创建 Client 时获取的密钥
username（必填）：关联的用户名

curl --location 'https://{host}/webapi/lite_api/v1/iam/client_token' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "username": "YOUR_USERNAME"
  }'

成功响应示例：

{
  "code": 200,
  "data": {
    "access_token": "eyJhbGci...",
    "token_type": "Bearer",
    "expires_in": 3600
  },
  "message": "success"
}

将响应中的 access_token 值作为下方接口中的 YOUR_ACCESS_TOKEN 使用。

Access Token 授权

Method: POST
Endpoint: https://{host}/webapi/lite_api/v2/api/chat-with-bot/{agent_id}
Header: Authorization: Bearer YOUR_ACCESS_TOKEN

路径参数：

agent_id：目标 Agent 的 UUID（可从 Agent 页面 URL 中获取）

请求体（JSON）关键字段：

messages（必填）：role 限制为 user/human，且数组长度最大为 1
stream、show_tool_result、file_id、workspace_id、layout_mode、skip_hint（同上）
conversation_id（可选）：多轮对话会话 ID；不传则系统创建并在响应返回

最小请求示例：

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

成功响应要点：

data.conversation_id：用于后续多轮对话复用
data.full_output：最终回答

上传图片

Method: POST
新 Endpoint（推荐）：https://{host}/webapi/lite_api/v2/api/chat-with-bot/upload-images
旧 Endpoint（即将废弃）：https://{host}/webapi/lite_api/v2/api/chat-with-bot/{agent_id}/upload-images
Header（示例）：api-key: YOUR_API_KEY
Content-Type: multipart/form-data

请求参数：

files（必填）：一个或多个图片文件

成功响应示例：

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

说明：

将返回的 ids 填入聊天接口 messages[].content 中的 image_ids 字段即可完成图片问答。

聊天图片 / 文件信息获取说明

Last updated by | Gavin Guo (Medalsoft) | 2026年8月12日 at GMT+8 14:23

本文档整理了在聊天（message）场景中，图片和文件从「返回 ID」到「最终预览/下载」的完整接口调用流程，便于排查问题时快速定位。

一、图片

流程概览

message 返回图片 ID
调用 ekb-temporary 接口，用 file_id 换取临时链接
访问临时链接（需带 authorization 请求头）
图片展示/预览

1. message 返回图片 ID

聊天消息中，图片以 Markdown 图片语法返回，链接里包含图片的临时文件 ID：

![](/api/workspace/file/TemporaryFile/7485579177907720192)

说明：7485579177907720192 即为图片对应的 file_id，用于下一步换取真实可访问的临时下载链接。

2. 用 file_id 换取临时链接

接口：POST /webapi/knowledge/v1/file/ekb-temporary
作用：将上一步拿到的 file_id 传入，换取真实可访问的临时文件链接

请求示例：

curl 'https://demo.next.serviceme.com/webapi/knowledge/v1/file/ekb-temporary' \
	-H 'accept: application/json, text/plain, */*' \
	-H 'authorization: Bearer <token>' \
	-H 'content-type: application/json' \
	-H 'locale: zh-CN' \
	--data-raw '{"file_id":["7485579177907720192"]}'

关键参数说明：

参数	位置	说明
`authorization`	Header	登录态 Bearer Token，必须携带，否则接口会拒绝
`file_id`	Body（数组）	待换取临时链接的文件 ID 列表，支持批量

返回结果：接口会返回类似以下真实可访问的临时文件链接（示例省略部分签名字符）：

https://demo.next.serviceme.com/webapi/knowledge/v1/file/ekb-temporary-file/83ba1459f010783229f5787c

3. 访问临时链接

拿到临时链接后可直接 GET 获取图片内容，但同样需要携带 authorization 请求头。

GET https://demo.next.serviceme.com/webapi/knowledge/v1/file/ekb-temporary-file/<签名后的临时文件标识>
authorization: Bearer <token>

小结（排查要点）：

图片链接中的数字 ID 只是 file_id，不能直接访问，必须先换临时链接
临时链接不是免鉴权链接，访问时仍需带 authorization
图片加载失败优先检查：file_id 是否正确、Token 是否过期、临时链接是否过期

二、文件

流程概览

message 返回文件 ID（通常可通过 category: "tool" 识别）
调用 get_detail 查询文件详情（包含 document_id 对应信息）
调用 ekb-preview 完成文件预览

1. message 返回文件 ID

聊天消息（message）中，若某条消息的 category 字段为 "tool"，通常表示这是一条与文件相关的消息，其中会携带文件对应的 ID（如 document_id）。

2. 获取文件详情

接口：GET /webapi/knowledge/v1/rag/get_detail?document_id={document_id}
作用：根据 document_id 查询文件详细信息（如文件名、类型、objectType 等），用于后续预览接口参数拼装

请求示例：

curl 'https://demo.next.serviceme.com/webapi/knowledge/v1/rag/get_detail?document_id=7485164512316755968' \
	-H 'accept: application/json, text/plain, */*' \
	-H 'authorization: Bearer <token>' \
	-H 'content-type: application/json' \
	-H 'locale: zh-CN' \
	--data-raw '{}'

关键参数说明：

参数	位置	说明
`document_id`	Query String	文件对应文档 ID，从 message 中获取
`authorization`	Header	登录态 Bearer Token，必须携带

3. 预览文件

接口：POST /webapi/knowledge/v1/file/ekb-preview
作用：根据文件 ID、对象类型、文件类型等信息，获取文件预览内容或预览地址

请求示例：

curl 'https://demo.next.serviceme.com/webapi/knowledge/v1/file/ekb-preview' \
	-H 'accept: application/json, text/plain, */*' \
	-H 'authorization: Bearer <token>' \
	-H 'content-type: application/json' \
	-H 'locale: zh-CN' \
	--data-raw '{"id":"7485164641157386241","objectType":"2","filetype":1}'

关键参数说明：

参数	说明
`id`	文件 ID（通常来自 `get_detail` 返回结果，与 `document_id` 可能不同）
`objectType`	对象类型（具体取值以 `get_detail` 返回为准）
`filetype`	文件类型标识
`authorization`	登录态 Bearer Token，必须携带

小结（排查要点）：

文件类消息可通过 category: "tool" 区分
拿到文件 ID 后，先调 get_detail，再调 ekb-preview
Token 过期会导致相关接口统一返回 401

三、图片 vs 文件接口对比

场景	消息标识	关键接口	是否需要 authorization
图片	Markdown 图片语法 `![](/api/workspace/file/TemporaryFile/{file_id})`	`ekb-temporary`（换临时链接）→ 访问临时链接	是（两步都需要）
文件	`category: "tool"`	`get_detail`（查详情）→ `ekb-preview`（预览）	是（两步都需要）

共同点：所有接口调用都必须携带有效的 Bearer Token，Token 过期是最常见的排查突破口。

创建API Key​

进入 Agent 的 API Console​

创建 API Channel​

进入 Channel 的密钥页​

生成 API Key​

获取调用文档并对接​

调用接口与 Agent 聊天​

API Key 授权​

获取 Access Token​

1. 创建 Client​

2. 查询 Client 列表（可选）​

3. 生成 Access Token​

Access Token 授权​

上传图片​

聊天图片 / 文件信息获取说明​

一、图片​

流程概览​

1. message 返回图片 ID​

2. 用 file_id 换取临时链接​

3. 访问临时链接​

二、文件​

流程概览​

1. message 返回文件 ID​

2. 获取文件详情​

3. 预览文件​

三、图片 vs 文件接口对比​

创建API Key

进入 Agent 的 API Console

创建 API Channel

进入 Channel 的密钥页

生成 API Key

获取调用文档并对接

调用接口与 Agent 聊天

API Key 授权

获取 Access Token

1. 创建 Client

2. 查询 Client 列表（可选）

3. 生成 Access Token

Access Token 授权

上传图片

聊天图片 / 文件信息获取说明

一、图片

流程概览

1. message 返回图片 ID

2. 用 file_id 换取临时链接

3. 访问临时链接

二、文件

流程概览

1. message 返回文件 ID

2. 获取文件详情

3. 预览文件

三、图片 vs 文件接口对比