# 调用Agent（AK/SK认证） #### 功能介绍 系统级接口，使用平台AK/SK做鉴权。调用本接口，向已发布的Agent发起一次对话请求。若无已发布的Agent，请先在[AI原生应用引擎](https://support.huaweicloud.com/usermanual-wiseagent/appstage_04_0638.html#section0)中创建Agent并进行发布。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-appstage/appstage_07_0008.html)。 #### URI POST https://aiae.appstage.myhuaweicloud.com/v1/routes/open/platform/{agentId}/execute 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | agentId | 是 | String | **参数解释：** Agent的唯一id。进入[AI原生应用引擎](https://support.huaweicloud.com/usermanual-wiseagent/appstage_04_0638.html#section0)，在左侧导航栏选择"Agent编排中心 \> 我的Agent"，选择"我创建的"页签，选择列表操作列的"更多 \> 修改"，在浏览器地址栏查看id。 **约束限制：** 不涉及。 **取值范围：** 由英文字母和数字组成，长度为32个字符。 **默认取值：** 不涉及。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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":""}}。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | query | 是 | String | **参数解释：** 发起对话的内容。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | quote | 否 | String | **参数解释：** 对话中引用文件盒子中文件的完整名称，包含后缀。 **约束限制：** 如果发布Agent时，用户在该Agent的文件盒子中没有文件，需要先[上传文件](https://support.huaweicloud.com/api-appstage/FileBoxUpload.html)。 **取值范围：** 只支持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。 **默认取值：** 不涉及。 | 表4memory | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | role | 是 | String | **参数解释：** 对话角色。 **约束限制：** 只支持user，assistant或tool三种取值。 **取值范围：** user，assistant或tool。 **默认取值：** 不涉及。 | | content | 是 | String | **参数解释：** 对话内容。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | #### 响应参数 **状态码：200** 表5响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | request_id | String | **参数解释：** 唯一请求id。 **取值范围：** 只由英文字母及数字组成，长度为32个字符。 | | agent_id | String | **参数解释：** Agent的唯一id。 **取值范围：** 只由英文字母及数字组成，长度为32个字符。 | | user_id | String | **参数解释：** 本轮对话的用户唯一身份标识。 **取值范围：** - 在发起对话请求时自定义的user_id。 - AI引擎用户的真实user_id，orgid的不可逆加密值。 | | conversation_id | String | **参数解释：** 会话ID。 **取值范围：** - 在发起对话请求时自定义的conversation_id。 - 随机生成的仅包含英文字母与数字的32位字符串。 | | type | String | **参数解释：** 返回内容的类型。 **取值范围：** - hint - workflow - tool - knowledge - message。 | | data | Object | **参数解释：** 不同响应类型的响应体中包含不同的参数，见示例。 **取值范围：** 不涉及。 | **状态码：400** 表6响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码。 **取值范围：** 不涉及。 | | error_msg | String | **参数解释：** 错误信息。 **取值范围：** 不涉及。 | **状态码：500** 表7响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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 | - 表示Agent成功接收对话请求，正常响应。 - 响应采用Server-Sent Events（SSE）机制进行流式输出，数据内容用data字段表示，示例如下：data: message；需注意，这并不是一个JSON数据。此外，还可以有冒号开头的行，表示注释，通常可忽略。 | | 400 | 缺少请求体。 | | 500 | 服务器内部错误或三方服务器内部错误。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-appstage/ErrorCode.html)。