文档首页/ 智能体平台 Versatile/ API参考/ API/ 工作流/智能体/ 调用智能体应用 - runAgent
更新时间：2026-01-21 GMT+08:00
查看PDF
分享

调用智能体应用 - runAgent

功能介绍

该接口用于运行知识型智能体应用，支持单智能体和多智能体，支持在指定的项目、智能体和对话上下文中执行智能体逻辑。接口支持流式响应模式，可以根据需要返回增量执行结果，适用于实时交互场景。

适用场景：

  • 在项目中运行预定义的知识型智能体应用。

  • 支持调试模式和发布模式，适用于不同开发和生产环境。

  • 支持流式响应，适用于需要实时反馈的场景（如聊天机器人、实时数据分析等）。

调用方法

请参见如何调用API。

URI

POST /v1/{project_id}/agents/{agent_id}/conversations/{conversation_id}

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

参数解释：

当前租户项目ID。

获取方法请参考获取项目ID。

约束限制：

不涉及。

取值范围：

由英文，数字，“-”，“_”组成，不超过64位字符。

默认取值：

不涉及。

agent_id

是

String

参数解释：

智能体应用ID。

获取方式：

  1. 进入Versatile智能体平台。

  2. 在左侧导航选择“开发中心 > 应用管理 > 单智能体应用”或选择“开发中心 > 应用管理 > 多智能体应用”。

  3. 在待复制ID的智能体应用卡片上，单击“▪▪▪ > 复制ID”。

约束限制：

不涉及。

取值范围：

由英文，数字，“-”，“_”组成，不超过64位字符。

默认取值：

不涉及。

conversation_id

是

String

参数解释：

会话ID，每个会话的唯一标识符。用户可将会话ID设置为任意字符串，例如“123e4567e89b12d3a456426614174000”，无需在其他地方获取。

约束限制：

不涉及。

取值范围：

由英文，数字，“-”，“_”组成，不超过64位字符。

默认取值：

不涉及。
表2 Query参数

参数

是否必选

参数类型

描述

workspace_id

否

String

参数解释：

工作空间ID，用于标识特定的工作空间。

获取方法请参考获取工作空间ID。

约束限制：

不涉及。

取值范围：

由英文，数字，“-”，“_”组成，不超过64位字符。

默认取值：

不涉及。

version

否

String

参数解释：

发布版本。

获取方式：

  1. 进入Versatile智能体平台。

  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<String,String>

参数解释：

用户提出的问题，作为运行工作流的输入，与工作流开始节点输入参数对应。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

user_profile

否

UserProfile object

参数解释：

用户画像。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

tool_switch_dict

否

Map<String,Boolean>

参数解释：

插件是否开启。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

model_deployment_id

否

String

参数解释：

为智能体配置的模型的id。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

enable_history

否

Boolean

参数解释：

是否记录会话历史。

约束限制：

布尔值。

取值范围：

true：开启。

false：关闭。

默认取值：

true。

histories

否

Array of Message objects

参数解释：

传入的会话历史。

约束限制：

布尔值。

取值范围：

true：开启。

false：关闭。

默认取值：

true。

files

否

Array of strings

参数解释：

上传文件url。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表5 UserProfile

参数

是否必选

参数类型

描述

enable_retrieve

否

Boolean

参数解释：

运行时，是否读取用户画像。

约束限制：

不涉及。

取值范围：

不涉及

默认取值：

false。

enable_extract

否

Boolean

参数解释：

运行时，是否构建用户画像。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

false。
表6 Message

参数

是否必选

参数类型

描述

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：插件入参名。
表8 latency

参数

参数类型

描述

plugin

Long

参数解释：

插件调用耗时。

取值范围：

不涉及。

model

Long

参数解释：

模型调用耗时。

取值范围：

不涉及。

overall

Long

参数解释：

总耗时。

取值范围：

不涉及。
表9 plugin

参数

参数类型

描述

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

流式响应，返回模型生成内容的增量数据块。

错误码

请参见错误码。

父主题： 工作流/智能体

相关文档