调用Agent（AK/SK认证）
功能介绍
系统级接口，使用平台AK/SK做鉴权。调用本接口，向已发布的Agent发起一次对话请求。若无已发布的Agent，请先在AI原生应用引擎中创建Agent并进行发布。
调用方法
请参见如何调用API。
URI
POST https://aiae.appstage.myhuaweicloud.com/v1/routes/open/platform/{agentId}/execute
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
agentId |
是 |
String |
参数解释： Agent的唯一id。进入AI原生应用引擎，在左侧导航栏选择“Agent编排中心 > 我的Agent”，选择“我创建的”页签，选择列表操作列的“更多 > 修改”，在浏览器地址栏查看id。 约束限制： 不涉及。 取值范围： 由英文字母和数字组成，长度为32个字符。 默认取值： 不涉及。 |
请求参数
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
X-User-Info |
是 |
String |
参数解释： 鉴权信息。示例：{"iam_user_info":{"domain_id":"087708f382d2471bbd4649a97346530d","domain_name":"","user_id":"fb55057381ff41748cbdbc3c9ea8df0a","user_id_type":"0","user_name":"","project_id":"","project_name":""}}。 约束限制： 不涉及。 取值范围： 不涉及。 默认取值： 不涉及。 |
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
query |
是 |
String |
参数解释： 发起对话的内容。 约束限制： 不涉及。 取值范围： 不涉及。 默认取值： 不涉及。 |
|
quote |
否 |
String |
参数解释： 对话中引用文件盒子中文件的完整名称，包含后缀。 约束限制： 如果发布Agent时，用户在该Agent的文件盒子中没有文件，需要先上传文件。 取值范围： 只支持pdf、txt、docx等文本文件格式。 默认取值： 不涉及。 |
|
memory |
否 |
Array of memory objects |
参数解释： 在本次对话请求中，让大模型提前记住的部分。 约束限制： 不涉及。 取值范围： 不涉及。 默认取值： 不涉及。 |
|
user_id |
否 |
String |
参数解释： 用户id，允许自定义，与conversation_id共同使用可以使Agent自动获取该用户相同对话id下的前几轮对话内容。 约束限制： 不与memory同时生效，memory存在时memory优先生效。 取值范围： 不涉及。 默认取值： AI引擎用户的真实user_id，orgid的不可逆加密值。 |
|
conversation_id |
否 |
String |
参数解释： 对话id，允许自定义，与user_id共同使用可以使Agent自动获取该用户相同对话id下的前几轮对话内容。 约束限制： 不与memory同时生效，memory存在时memory优先生效。 取值范围： 不涉及。 默认取值： 随机生成的仅包含英文字母与数字的32位字符串。 |
|
variables |
否 |
Object |
参数解释： 变量用于用户个人信息，例如语言偏好等，并让Agent记住这些特征，使回复更加个性化。 约束限制： 变量包括一般变量和敏感变量，一般变量可用于对话和工作流，敏感变量只用于工作流。如果Agent中设置了敏感变量，敏感变量为必传，一般变量非必需。 取值范围： 一般变量common_variables和敏感变量sensitive_variables。 默认取值： 不涉及。 |
响应参数
状态码：200
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
request_id |
String |
参数解释： 唯一请求id。 取值范围： 只由英文字母及数字组成，长度为32个字符。 |
|
agent_id |
String |
参数解释： Agent的唯一id。 取值范围： 只由英文字母及数字组成，长度为32个字符。 |
|
user_id |
String |
参数解释： 本轮对话的用户唯一身份标识。 取值范围：
|
|
conversation_id |
String |
参数解释： 会话ID。 取值范围：
|
|
type |
String |
参数解释： 返回内容的类型。 取值范围：
|
|
data |
Object |
参数解释： 不同响应类型的响应体中包含不同的参数，见示例。 取值范围： 不涉及。 |
状态码：400
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
error_code |
String |
参数解释： 错误码。 取值范围： 不涉及。 |
|
error_msg |
String |
参数解释： 错误信息。 取值范围： 不涉及。 |
状态码：500
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
error_code |
String |
参数解释： 错误码。 取值范围： 不涉及。 |
|
error_msg |
String |
参数解释： 错误信息。 取值范围： 不涉及。 |
请求示例
-
设置memory，向Agent发起一次对话请求。
/v1/routes/open/platform/{agentId}/execute { "query" : "查询北京天气", "memory" : [ { "role" : "user", "content" : "你是谁" }, { "role" : "assistant", "content" : "我是盘古大模型" }, { "role" : "user", "content" : "南京天气" }, { "role" : "assistant", "tool_calls" : [ { "id" : "efd6ff92-422c-4ba4-b531-ac1991af7c1a", "type" : "function", "function" : { "name" : "查询当前天气 查询当前天气", "arguments" : "{\"city\":\"320100\",\"extensions\":\"all\"}" } } ] }, { "role" : "tool", "tool_call_id" : "efd6ff92-422c-4ba4-b531-ac1991af7c1a", "content" : "{\"data\":{\"status\":\"1\",\"count\":\"1\",\"info\":\"OK\",\"infocode\":\"10000\",\"forecasts\":[{\"city\":\"南京市\",\"adcode\":\"320100\",\"province\":\"江苏\",\"reporttime\":\"2024-08-20 16:32:01\",\"casts\":[{\"date\":\"2024-08-20\",\"week\":\"2\",\"dayweather\":\"中雨\",\"nightweather\":\"中雨\",\"daytemp\":\"32\",\"nighttemp\":\"26\",\"daywind\":\"西北\",\"nightwind\":\"西北\",\"daypower\":\"1-3\",\"nightpower\":\"1-3\",\"daytemp_float\":\"32.0\",\"nighttemp_float\":\"26.0\"}]}]}}" } ] } -
设置引用文件、自定义的用户id和对话id、一般变量，向Agent发起一次对话请求。
/v1/routes/open/platform/{agentId}/execute { "query" : "上海有哪些旅游景点", "quote" : "上海旅游攻略.docx", "user_id" : 1008600000300604420, "conversation_id" : "70dc6dfd397244edbbf4847acb78bfa9a", "variables" : { "common_variables" : { "上海古典名园" : "豫园" } } }
响应示例
状态码：200
-
表示Agent成功接收对话请求，正常响应。
-
响应采用Server-Sent Events（SSE）机制进行流式输出，数据内容用data字段表示，示例如下：data: message；需注意，这并不是一个JSON数据。此外，还可以有冒号开头的行，表示注释，通常可忽略。
-
Agent的响应类型为hint，用于提示接下来使用knowledge，tool或workflow进行响应，示例中的提示为workflow。
{ "request_id" : "266e71692aba45ec8b111d847963109d", "agent_id" : "50b58e0041e843b0b7bd343dca076443", "user_id" : 1008600000300604420, "conversation_id" : "c568e962b0004650bc12b63aec96366d", "type" : "hint", "data" : { "id" : "ce7f20a1-a3dd-4249-b7ca-8c5039dd8c74", "name" : "儿科问答", "tool_type" : "workflow" } } -
Agent使用workflow进行响应。
{ "request_id" : "266e71692aba45ec8b111d847963109d", "agent_id" : "50b58e0041e843b0b7bd343dca076443", "user_id" : 1008600000300604420, "conversation_id" : "c568e962b0004650bc12b63aec96366d", "type" : "workflow", "data" : { "id" : "ce7f20a1-a3dd-4249-b7ca-8c5039dd8c74", "name" : "儿科问答", "status" : "SUCCESS", "request" : { "query" : "婴儿肥胖怎么办" }, "response" : { "data" : { "responseBody" : "{\"result\":\"问题分析:主要控制儿童饮食，合理饮食不喝酒，不吃油炸食物意见和建议:建议孩子们多锻炼一点，每天至少锻炼一到两个小时，而且他们必须坚持锻炼。他们也应该少吃油和脂肪，多吃水果和蔬菜。我认为我们应该在一段时间后恢复正常。就食疗而言，父母必须参与其中，并被要求掌握一些相关知识，如不允许孩子吃得太多或太多，不给予高糖、高脂肪、高热量的饮食。治疗节食中的儿童并让他们挨饿也很困难。因此，在进行饮食控制之前，有必要耐心而详细地告诉儿童肥胖的危害、\"}", "responseHeaders" : { "Server" : "api-gateway", "X-Request-Id" : "6701c75b8f23102a659e63a3cc5a20d6", "X-Content-Type-Options" : "nosniff", "Connection" : "keep-alive", "X-Download-Options" : "noopen", "Date" : "Tue, 20 Aug 2024 08:37:27 GMT", "Referrer-Policy" : "no-referrer", "X-Frame-Options" : "SAMEORIGIN", "Strict-Transport-Security" : "max-age=31536000; includeSubdomains;", "lubanops-nenv-id" : "28164", "Content-Length" : "660", "X-XSS-Protection" : "1; mode=block;", "Content-Type" : "application/json" }, "statusCode" : 200 } } } } -
Agent使用tool进行响应。
{ "request_id" : "266e71692aba45ec8b111d847963109d", "agent_id" : "50b58e0041e843b0b7bd343dca076443", "user_id" : 1008600000300604420, "conversation_id" : "c568e962b0004650bc12b63aec96366d", "type" : "tool", "data" : { "id" : "b6dbf1a6-f374-4d44-96fb-45726f7fa7f0", "name" : "航班信息 航班信息", "status" : "SUCCESS", "request" : { "city" : "南京", "endcity" : "大理", "date" : "2024-08-24" }, "response" : { "data" : { "status" : 0, "msg" : "ok", "result" : { "city" : "NKG", "endcity" : "DLU", "date" : "2024-08-24", "list" : [ { "flightno" : "ZH2010", "airline" : "深圳航空", "realflightno" : "TV6026", "departportcode" : "NKG", "departport" : "禄口国际机场", "arrivalportcode" : "DLU", "arrivalport" : "大理荒草坝机场", "departterminal" : "T1", "arrivalterminal" : "", "departdate" : "2024-08-24", "arrivaldate" : "2024-08-24", "departtime" : "16:35", "arrivaltime" : "19:40", "departdateadd" : 0, "arrivaldateadd" : 0, "craft" : "19N", "stopnum" : "0", "costtime" : "03:05", "punctualrate" : "95", "pricelist" : [ ], "minprice" : "0", "airporttax" : "50", "fueltax" : "50", "food" : "1,", "isasr" : "1,", "iseticket" : "1,", "iscodeshare" : 1 } ] } } } } } -
Agent使用knowledge进行响应。
{ "request_id" : "266e71692aba45ec8b111d847963109d", "agent_id" : "50b58e0041e843b0b7bd343dca076443", "user_id" : 1008600000300604420, "conversation_id" : "c568e962b0004650bc12b63aec96366d", "type" : "knowledge", "data" : { "id" : "7e4cf06bd8404ec594c621c8f47c44f1", "name" : "华西医院", "status" : "SUCCESS", "request" : { "query" : "肠息肉怎么办" }, "response" : "结直肠息肉应该怎么办？\n结直肠息肉是什么\n结肠息肉需不需要切除" } } -
Agent使用大模型进行响应。
{ "request_id" : "266e71692aba45ec8b111d847963109d", "agent_id" : "50b58e0041e843b0b7bd343dca076443", "user_id" : 1008600000300604420, "conversation_id" : "c568e962b0004650bc12b63aec96366d", "type" : "knowledge", "data" : { "id" : "202412302111448bd332d627ed4c5f", "content" : "著名的", "url" : null, "raw" : { "role" : "assistant", "content" : "著名的" } } }
状态码：400
缺少请求体。
{
"error_code" : "AIAE.00001400",
"error_msg" : "Request body is missing"
}
状态码：500
服务器内部错误或三方服务器内部错误。
{
"error_code" : "AIAE.00001500",
"error_msg" : "Internal Server Error."
}
状态码
|
状态码 |
描述 |
|---|---|
|
200 |
|
|
400 |
缺少请求体。 |
|
500 |
服务器内部错误或三方服务器内部错误。 |
错误码
请参见错误码。
