文档首页/ 智能体平台 Versatile/ API参考/ API/ 智能体/ 调用智能体应用
更新时间：2025-09-15 GMT+08:00
查看PDF
分享

调用智能体应用

功能介绍

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

适用场景：

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

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

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

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设置为任意值，使用标准UUID格式。

  1. 进入Versatile智能体平台。

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

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

  4. 在弹出的“调用路径”页面，单击“复制路径”即可获取调用路径。其中，conversation_id参数为会话ID，唯一标识每个会话的标识符，可将会话ID设置为任意值，使用标准UUID格式。

约束限制：

不涉及。

取值范围：

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

默认取值：

不涉及。
表2 Query参数

参数

是否必选

参数类型

描述

workspace_id

是

String

参数解释：

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

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

约束限制：

不涉及。

取值范围：

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

默认取值：

不涉及。

version

否

String

参数解释：

发布版本号。

获取方式：

  1. 进入Versatile智能体平台。

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

  3. 选择需要查找的智能体应用。

  4. 在智能体界面右上角，单击“发布历史”，获取发布版本号。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

type

否

String

参数解释：

该参数允许调用者指定智能体应用的执行类型，支持不同的执行方式和返回模式。

约束限制：

不涉及。

取值范围：

  • 实时处理：设置type为AGENT，使用流式返回，适用于需要实时反馈的场景，如实时聊天。

  • 批量处理：设置type为CONTROLLER，使用非流式返回，适用于处理完成后一次性返回结果的场景，如数据处理。

默认取值：

Constant.AppType.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时，工作流应用的运行模式为发布模式。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

stream

否

Boolean

参数解释：

是否开启流式调用。当前智能体应用只支持流式调用。

  • 当stream为true时，服务器以流式方式逐步返回结果，适合需要实时反馈的场景。

  • 当stream为false时，服务器在处理完成后一次性返回结果，适合处理较小数据或不需要实时反馈的场景。

约束限制：

不涉及。

取值范围：

  • true：开启。

  • false：不开启。

默认取值：

不涉及。
表4 请求Body参数

参数

是否必选

参数类型

描述

query

是

String

参数解释：

用户问题，作为运行智能体的输入。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

响应参数

状态码：200

表5 响应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：插件入参名。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表6 latency

参数

参数类型

描述

plugin

Long

插件调用耗时。

model

Long

模型调用耗时。

overall

Long

总耗时。
表7 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

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

错误码

请参见错误码。

父主题： 智能体

相关文档