# 调用智能体应用 - runAgent #### 功能介绍 该接口用于运行知识型智能体应用，支持单智能体和多智能体，支持在指定的项目、智能体和对话上下文中执行智能体逻辑。接口支持流式响应模式，可以根据需要返回增量执行结果，适用于实时交互场景。 适用场景： - 在项目中运行预定义的知识型智能体应用。 - 支持调试模式和发布模式，适用于不同开发和生产环境。 - 支持流式响应，适用于需要实时反馈的场景（如聊天机器人、实时数据分析等）。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-agentarts0/agentarts_07_0003.html)。 #### URI POST /v1/{project_id}/agents/{agent_id}/conversations/{conversation_id} 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | **参数解释**： 当前租户项目ID。 获取方法请参考[获取项目ID](https://support.huaweicloud.com/api-agentarts0/agentarts_07_0018.html)。 **约束限制**： 不涉及。 **取值范围**： 由英文，数字，"-"，"_"组成，不超过64位字符。 **默认取值**： 不涉及。 | | agent_id | 是 | String | **参数解释**： 智能体应用ID。 获取方式： 1. 进入AgentArts智能体开发平台。 2. 在左侧导航选择"开发中心 \> 智能体管理 \> 单智能体"或选择"开发中心 \> 智能体管理 \> 多智能体"。 3. 鼠标移动至待复制ID的智能体应用卡片上，单击"更多 \> 复制ID"。 **约束限制**： 不涉及。 **取值范围**： 由英文，数字，"-"，"_"组成，不超过64位字符。 **默认取值**： 不涉及。 | | conversation_id | 是 | String | **参数解释**： 会话ID，每个会话的唯一标识符。用户可将会话ID设置为任意字符串，例如"123e4567e89b12d3a456426614174000"，无需在其他地方获取。 **约束限制**： 不涉及。 **取值范围**： 由英文，数字，"-"，"_"组成，不超过64位字符。 **默认取值**： 不涉及。 | 表2Query参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | workspace_id | 否 | String | **参数解释**： 工作空间ID，用于标识特定的工作空间。 获取方法请参考[获取工作空间ID](https://support.huaweicloud.com/api-agentarts0/agentarts_07_0020.html)。 **约束限制**： 不涉及。 **取值范围**： 由英文，数字，"-"，"_"组成，不超过64位字符。 **默认取值**： 不涉及。 | | version | 否 | String | **参数解释**： 发布版本。 获取方式： 1. 进入AgentArts智能体开发平台。 2. 在左侧导航选择"开发中心 \> 智能体管理 \> 单智能体应用"或选择"开发中心 \> 智能体管理 \> 多智能体"。 3. 选择需要查找的智能体应用。 4. 在智能体界面右上角，单击"版本历史"，获取ID。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | type | 否 | String | **参数解释**： 该参数允许调用者指定智能体应用的执行类型，支持不同的执行方式和返回模式。 **约束限制**： 不涉及。 **取值范围**： - type为controller时，为多智能体。 - type为agent时，为单智能体。 **默认取值**： agent。 | #### 请求参数 表3请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释**： 用户Token。 通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | X-Invoke-Mode | 否 | String | **参数解释**： 该参数用于标识智能体应用运行的模式。 **约束限制**： 不涉及。 **取值范围**： - X-Invoke-Mode的值为debug时，智能体应用的运行模式为调试模式。调试模式会生成日志、详细的执行步骤，便于排查问题。 - X-Invoke-Mode的值为published时，智能体应用的运行模式为发布模式。 **默认取值**： published。 | | stream | 否 | Boolean | **参数解释**： 是否开启流式调用。当前智能体应用只支持流式调用。 - 当stream为true时，服务器以流式方式逐步返回结果，适合需要实时反馈的场景。 - 当stream为false时，服务器在处理完成后一次性返回结果，适合处理较小数据或不需要实时反馈的场景。 **约束限制**： 不涉及。 **取值范围**： - true：开启。 - false：不开启。 **默认取值**： true。 | | Content-Type | 是 | String | **参数解释**： 发送的实体的MIME类型。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： application/json。 | 表4请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | query | 否 | String | **参数解释**： 用户请求的问题。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | inputs | 是 | Map\ | **参数解释**： 入参变量在此处填写，key-value形式，动态传递入参变量的值给智能体运行。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | user_profile | 否 | [UserProfile] object | **参数解释**： 用户画像。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | tool_switch_dict | 否 | Map\ | **参数解释**： 插件是否开启。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | model_deployment_id | 否 | String | **参数解释**： 为智能体配置的模型的id。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | enable_history | 否 | Boolean | **参数解释**： 是否记录会话历史。 **约束限制**： 布尔值。 **取值范围**： true：开启。 false：关闭。 **默认取值**： true。 | | histories | 否 | Array of [Message] objects | **参数解释**： 传入的会话历史。 **约束限制**： 布尔值。 **取值范围**： true：开启。 false：关闭。 **默认取值**： true。 | | files | 否 | Array of strings | **参数解释**： 上传文件url。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | 表5UserProfile | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | enable_retrieve | 否 | Boolean | **参数解释**： 运行时，是否读取用户画像。 **约束限制**： 不涉及。 **取值范围**： 不涉及 **默认取值**： false。 | | enable_extract | 否 | Boolean | **参数解释**： 运行时，是否构建用户画像。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： false。 | 表6Message | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | role | 否 | String | **参数解释**： 会话角色。 **约束限制**： 不涉及。 **取值范围**： - user：用户输入的消息，包括提示词和上下文信息。 - assistant：模型生成的回复内容。 **默认取值**： 不涉及。 | | content | 否 | String | **参数解释**： 会话内容。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | #### 响应参数 **状态码：200** 表7响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | data | String | **参数解释**： 当请求参数"stream"值为"true"时，智能体的消息以流式形式返回。生成的内容以增量的方式逐步发送回来，每个data字段均包含一部分生成的内容，直到所有data返回，响应结束。 **取值范围**： 不涉及。 | | event | String | **参数解释**： 数据单元类型。 **取值范围**： - start：开始节点，表示开始调用模型进行会话。 - message：消息节点，表示模型返回的消息。 - plugin_start：插件调用请求节点，表示调用插件的请求信息。 - plugin_end：插件调用响应节点，表示调用插件的响应信息。 - statistic_data：执行数据节点，包含本次调用的耗时信息。 - summary_response：消息总结节点，包含本次调用的全量响应信息。 - done：流式调用结束节点，表示流式响应结束。 | | content | Object | **参数解释**： 消息块内容。"event"参数类型不同，内容结构不同。 **取值范围**： 不涉及。 | | createdTime | Long | **参数解释**： 消息块返回的时间戳。例如，1733817348963。 **取值范围**： 不涉及。 | | latency | [latency] object | **参数解释**： 耗时。 **取值范围**： - plugin： 插件调用耗时。 - model： 模型调用耗时。 - overall： 总耗时。 | | plugin | [plugin] object | **参数解释**： 插件请求信息。 **取值范围**： - name：插件名。 - arguments：插件入参名。 | 表8latency | 参数 | 参数类型 | 描述 | |:---|:---|:---| | plugin | Long | **参数解释**： 插件调用耗时。 **取值范围**： 不涉及。 | | model | Long | **参数解释**： 模型调用耗时。 **取值范围**： 不涉及。 | | overall | Long | **参数解释**： 总耗时。 **取值范围**： 不涉及。 | 表9plugin | 参数 | 参数类型 | 描述 | |:---|:---|:---| | name | String | **参数解释**： 插件名。 **取值范围**： 不涉及。 | | arguments | Object | **参数解释**： 插件入参名。 **取值范围**： 不涉及。 | #### 请求示例 - 调用智能体 ``` { "method" : "POST", "url" : "https://{endpoint}/v1/{project_id}/agents/{agent_id}/conversations/{conversation_id}", "headers" : { "Content-Type" : "application/json", "X-Auth-Token" : "MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...", "stream" : true }, "body" : { "query" : "查询A12会议室在9:00到10:00的状态" } } ``` #### 响应示例 **状态码：200** 流式响应，返回模型生成内容的增量数据块。 ``` data:{"event":"start","createdTime":1735558575017} data:{"event":"message","content":"好的","createdTime":1735558576300} data:{"event":"message","content":"，","createdTime":1735558576301} data:{"event":"message","content":"我将","createdTime":1735558576301} data:{"event":"message","content":"调用","createdTime":1735558576302} data:{"event":"message","content":"query","createdTime":1735558576302} data:{"event":"statistic_data","latency":{"overall":1.97},"createdTime":1735558576986} data:{"event":"summary_response","content":"A12会议室在9:00到10:00的时间段内是空闲的。","role":"assistant","createdTime":1735558576987} data:{"event":"done","createdTime":1735558577011} ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 流式响应，返回模型生成内容的增量数据块。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-agentarts0/ErrorCode.html)。