# 调用运行时 - InvokeRuntime #### 功能介绍 该接口用于运行场景化应用，支持在指定的智能体、工作流中执行。接口支持流式响应模式，可以根据需要返回增量执行结果，适用于实时交互场景。 适用场景： - 在项目中运行预定义的工作流/智能体。 - 支持调试模式和发布模式，适用于不同开发和生产环境。 - 支持流式响应，适用于需要实时反馈的场景（如聊天机器人、实时数据分析等）。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-agentarts/agentarts_07_0003.html)。 #### 授权信息 当前API调用无需身份策略权限。 #### URI POST /runtimes/{runtime_name}/invocations 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | runtime_name | 是 | String | **参数解释**： 需要执行的运行时名称。 获取方法： 方式一 1. 进入AgentArts智能体平台，在左侧菜单栏选择"智能体管理"，选择"工作流"或者"智能体"。 2. 鼠标移动至待运行的智能体/工作流卡片上，单击"调用路径"。 3. 在弹出的卡片中，复制运行时名称，名称为"agent-arts-"开头 。 方式二 1. 进入AgentArts智能体平台，在左侧菜单栏选择"智能体管理"，选择"工作流"或者"智能体"。 2. 鼠标移动至待运行的智能体/工作流卡片上，单击"复制ID"。 3. 在左侧菜单栏选择"智能体运行时"。 4. 在搜索框内输入智能体/工作流ID，单击搜索。结果即为运行时名称信息。 **约束限制**： 不涉及。 **取值范围**： 由英文，数字，"-"，"_"组成，不超过64位字符。 **默认取值**： 不涉及。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | Authorization | 是 | String | **参数解释**： 鉴权参数，根据部署时所选择的方式填写对应的鉴权，分为API Key认证、OAuth 2.0认证、IAM认证（AK/SK认证），获取参数详情参考[认证鉴权](https://support.huaweicloud.com/api-agentarts/agentarts_07_0005.html)。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | X-Invoke-Mode | 否 | String | **参数解释**： 该参数用于标识运行时运行的模式。 **约束限制**： 不涉及。 **取值范围**： - X-Invoke-Mode的值为debug时，运行模式为调试模式。调试模式会生成日志、详细的执行步骤，便于排查问题。 - X-Invoke-Mode的值为published时，运行模式为发布模式。 **默认取值**： published。 | | X-Sdk-Content-Sha256 | 否 | String | **参数解释**： 如果智能体运行时的入站认证类型为IAM认证时，需要指定该Header头为UNSIGNED-PAYLOAD。 **约束限制**： 不涉及。 **取值范围**： 固定为UNSIGNED-PAYLOAD。 **默认取值**： 不涉及。 | | x-hw-agentarts-session-id | 是 | String | **参数解释**： 会话ID，每个会话的唯一标识符。用户可将会话ID设置为任意字符串，例如"123e4567e89b12d3a456426614174000"，无需在其他地方获取。 **约束限制**： 不涉及。 **取值范围**： 由英文，数字，"-"，"_"组成，不超过64位字符。 **默认取值**： 不涉及。 | | X-Request-Id | 否 | String | **参数解释**： 调用链ID，每个请求的唯一标识符。用于日志中跟踪整个请求的调用链路。用户可将调用链ID设置为任意字符串，例如"123e4567e89b12d3a4564266141740"，无需在其他地方获取。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | Content-Type | 是 | String | **参数解释**： 发送的实体的MIME类型。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： application/json。 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | query | 否 | String | **参数解释**： 用户请求的问题。 调用单智能体/多智能体选择此参数，必填。 **约束限制**： 不涉及 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | inputs | 是 | Map\ | **参数解释**： 在调用工作流接口时，inputs对象中的字段（Key）并非API预留的固定字段，而是取决于您在工作流"开始节点"中定义的变量名。例如在开始节点定义了一个string类型变量，名称为name，值为名字，就需在请求体构建{inputs：{"name":"名字"}}的形式传参。支持String、Integer、Object、Boolean、Array\[string\]、Array\[String\]、Array\[Object\]、Array\[Integer\]形式 **约束限制**： 为确保工作流正常运行，请遵循以下原则判断哪些变量需要传入： 配置必填项：如果在"开始节点"中将某个变量设为"必填"，则调用API时必须包含该字段，且取值不能为空（如果后续节点未引用，可填写任意占位值）。 逻辑引用项：如果某个变量在"开始节点"中设为"可选"，但其后的任何一个节点（如大模型节点、工具节点）引用了该变量，则调用API时必须传入该字段，否则会导致引用该变量的节点执行失败。 可选忽略项：只有在"开始节点"中设为"可选"，且后续所有节点均未引用的情况下，该字段才可以在调用时省略。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | plugin_configs | 否 | Array of [PluginConfig] objects | **参数解释**： 该参数仅适用于工作流场景。 **约束限制**： 不涉及。 **取值范围**： 当工作流中添加了非AgentArts资产广场的第三方插件，且该插件需要鉴权时，需要添加plugin_id、config参数。 **默认取值**： 不涉及。 | 表4PluginConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | plugin_id | 否 | String | **参数解释**： 插件ID。 获取方式： 1. 进入AgentArts智能体平台。 2. 在左侧导航选择"开发中心 \> 组件库 \> 插件"。 3. 鼠标移动至待复制ID的插件卡片上，单击"更多 \> 复制ID"。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | config | 否 | Map\ | **参数解释**： 用于工作流中有添加的插件时，在调用api时动态的传递插件请求头参数，config可以配成：{"key2:"value"}，key为插件的请求头变量名称，value为具体的值，会与HTTP请求头合并后作为该插件API调用的请求头参数。其他情况该参数无需传值，plugin_configs传空数组或者不传即可。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | #### 响应参数 **状态码：200** 表5响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | event | Map\ | **参数解释**： 运行时最终输出内容表示运行时结果。 **取值范围**： 不涉及。 | | data | [data] object | **参数解释**： 运行时回复内容。例如，提问器节点问题消息。 **取值范围**： 不涉及。 | | createdTime | Long | **参数解释**： 响应事件创建时间，格式为毫秒级时间戳（13位整数）。例如，1733817348963。 **取值范围**： 不涉及。 | 表6data | 参数 | 参数类型 | 描述 | |:---|:---|:---| | text | String | **参数解释**： 运行时输出内容消息块。 **取值范围**： 不涉及。 | | index | Integer | **参数解释**： 消息块索引。 **取值范围**： 不涉及。 | | node_id | String | **参数解释**： 节点ID。 **取值范围**： 不涉及。 | | node_type | String | **参数解释**： 工作流节点类型。 **取值范围**： 不涉及。 | | node_name | String | **参数解释**： 节点名称。 **取值范围**： 不涉及。 | | workflow_id | String | **参数解释**： 工作流ID。 **取值范围**： 不涉及。 | | workflow_name | String | **参数解释**： 工作流名称。 **取值范围**： 不涉及。 | | createdTime | Long | **参数解释**： 创建时间，格式为毫秒级时间戳（13位整数）。例如，1733817348963。 **取值范围**： 不涉及。 | #### 请求示例 调用运行时 ``` { "method" : "POST", "url" : "https://api.example.com/runtimes/agent-arts-ef727077-9903-4e0a-9196-e93298bfcce3/invocations", "headers" : { "Authorization" : "Bearer *******", "x-hw-agentarts-session-id" : 123456789 }, "body" : { "inputs" : { "query" : "你好" }, "plugin_configs" : [ { "plugin_id" : "xxxxxxxxx", "config" : { "key" : "value" } } ] } } ``` #### 响应示例 **状态码：200** 成功响应。 ``` { "event" : "message", "data" : { "text" : null, "index" : 11, "node_id" : "node_end", "node_type" : "End", "node_name" : "结束", "workflow_id" : "cd7a8f33-66e3-455c-b008-a6b18dd27319", "workflow_name" : "flowouttest", "createdTime" : 1760169416635 }, "createdTime" : 1760169416635 } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 成功响应。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-agentarts/ErrorCode.html)。