扣子智能体实现非流式对话的过程及API详解

最新推荐文章于 2025-11-24 15:28:47 发布

原创最新推荐文章于 2025-11-24 15:28:47 发布 · 1.6k 阅读

26 ·

CC 4.0 BY-SA版权

文章标签：

#扣子COZE #智能体 #非流式对话 #开放API服务 #python

老猿Python 同时被 3 个专栏收录

1156 篇文章

订阅专栏

零基础机器学习入门

22 篇文章

订阅专栏

人工智能基础知识

8 篇文章

订阅专栏

☞ ░ 前往老猿Python博客 ░ https://blog.youkuaiyun.com/LaoYuanPython

一、引言

在博文《基于新版本扣子(coze)平台的TTS智能体创建发布过程及开放API信息查阅方法（https://blog.youkuaiyun.com/LaoYuanPython/article/details/153961814）》中，老猿介绍了基于2025年10月访问扣子平台的版本怎么创建一个TTS服务智能体的过程。在本节将基于上面博文介绍的TTS智能体，来说明怎么使用Python实现通过API调用TTS智能体。

在这里插入图片描述

二、背景知识

2.1、基础概念

会话（Conversation）：智能体和用户之间的一段问答交互。一个会话包含一条或多条消息，并且能够自动处理截断，以适应模型的上下文内容；
消息（Message）：一条由用户或智能体创建的消息，消息内容可以包括文本、图片或文件。消息以列表的形式储存在对话中。
对话（chat）：在会话中对智能体的一次调用。智能体收到请求后，结合用户输入、通过预设的一系列工作流等配置来调用模型或工具执行指定任务。每个对话都是会话的一部分，智能体会将对话中产生的消息添加到会话中。可以直接发起对话，与智能体进行一次交互；也可以创建会话和消息，并在指定会话中发起对话，会话中的其他消息会作为历史消息传递给大模型。下面的案例采用直接发起对话方式。
个人访问令牌：用于其他应用程序和平台的个人访问令牌。不要与他人共享个人访问令牌，也不要在浏览器或其他客户端代码中暴露，以保护账户的安全。
bot_id：智能体ID。进入智能体的开发页面，开发页面 URL 中 bot 参数后的数字就是智能体ID。
user_id：标识当前与智能体交互的用户
流式响应：智能体在生成回复的同时，将回复消息以数据流的形式逐条发送给客户端。处理结束后，服务端会返回一条完整的智能体回复；
非流响应：无论对话是否处理完毕，立即发送响应消息。开发者可以通过接口查看对话详情确认本次对话处理结束后，再调用查看对话消息详情接口查看模型回复等完整响应内容

开发者可以按需选择响应方式，即流式或非流式响应，响应方式决定了开发者获取智能体回复的方式。本文案例采用的是非流式响应，因为非流式响应是请求和应答是异步模式，可以等服务端处理完之后一次性获取智能体答复，而流式响应是持续多次返回信息，因此老猿觉得非流式响应更符合开发习惯。

2.2、本案例智能体API调用过程解析

本文的案例采用不先建立会话就直接发起对话的方式调用智能体的服务，且使用非流失响应，在本文的扣子智能体调用中一次完整的智能体服务请求过程如下：

发起对话，并在请求中提供对话要完成的任务信息；
查看对话信息，以判断智能体服务任务是否处理完成，如果没处理完成，休眠一定时间后重复这个过程，否则转下步；
查看对话消息详情，获取智能体返回的信息内容。

通过顺序发起对话->查看对话详情->查看对话消息详情三个API，就可以在客户端远程调用一次智能体服务。

下面详细介绍扣子智能体平台中这三个相关的API。

三、发起对话API介绍

3.1 概述

发起对话接口用于向指定智能体发起一次对话，支持在对话时添加对话的上下文消息，以便智能体基于历史消息做出合理的回复。开发者可以按需选择响应方式，即流式或非流式响应，响应方式决定了开发者获取智能体回复的方式。

流式响应：智能体在生成回复的同时，将回复消息以数据流的形式逐条发送给客户端。处理结束后，服务端会返回一条完整的智能体回复。详细说明可参考流式响应
非流式响应：无论对话是否处理完毕，立即发送响应消息。开发者可以通过接口查看对话详情确认本次对话处理结束后，再调用查看对话消息详情接口查看模型回复等完整响应内容。详细说明可参考非流式响应。

本文以非流式响应为例进行介绍。

3.2、请求url

请求url为： https://api.coze.cn/v3/chat，

3.3 请求消息头

HTTP消息头主要用于 API 调用时的身份验证和数据格式指定：

Authorization：身份验证，取值：Bearer $Acess_Token，一种令牌认证方式，表示"持有者认证"，使用 API 密钥或访问令牌，在本文的案例里使用API 密钥，token的生成请参考上篇博文《基于新版本扣子(coze)平台的TTS智能体创建发布过程及开放API信息查阅方法》；
Content-Type：请求体的数据格式，服务器会根据这个头来正确解析你发送的数据。取值application/json：表示发送的数据是 JSON 格式

3.4、请求消息体

请求消息体需要的主要参数包括：

conversation_id：会话ID，可以为空，为空表示创建一个新会话，否则表示继承一个历史会话；
bot_id：智能体ID；
user_id：平台用户ID；
stream：是否启用流式响应；
additional_messages.content：要发送的消息内容，支持文本或字典对象，字典对象的键和值由智能体的参数来决定，发送请求前需要将字典序列化为 JSON 格式的字符串；
additional_messages.content_type：消息内容的类型，支持为text或object_string，text就是纯文本，object_string为一个字典类型序列号的json数据，里面保存要发给智能体的多个参数信息，如文本消息、TTS服务的音色类型、语速等智能体需要提供的参数；
additional_messages.role：发送这条消息的实体，user：代表该条消息内容是用户发送的，assistant：代表该条消息内容是智能体发送的；
additional_messages.type：消息类型，取值包括question、answer、function_call等，请求时可以不设置，默认为question。如果 autoSaveHistory=true，type 支持设置为 question 或 answer。如果 autoSaveHistory=false，type 支持设置为 question、answer、function_call、tool_output、tool_response。
其中：
※ question：用户输入内容，type=question 只能和 role=user 对应，即仅用户角色可以且只能发起 question 类型的消息
※ answer：智能体返回给用户的消息内容，支持增量返回。如果工作流绑定了消息节点，可能会存在多 answer 场景，此时可以用流式返回的结束标志来判断所有 answer 完成
※ function_call：智能体对话过程中调用函数（function call）的中间结果，是由智能体主动发出的消息。当用户的提问或对话上下文需要调用一个你预先配置好的工具（如查询天气、执行计算、调用API）时，智能体的核心会生成一个结构化的调用请求给对应工具，其消息类型就是function_call
※ tool_response：调用工具（function call）后返回的结果的消息类型
※ tool_output是智能体在收到 tool_response（原始数据）后，由大模型对原始数据进行理解、加工和总结，最终生成的对用户友好、可读的回复消息的消息类型。
auto_save_history：是否保存本次对话记录，如果设置 stream = false，必须设置auto_save_history=true，表示使用非流式响应，并记录历史消息。这是因为非流式响应依赖历史记录来“找回”对话内容，如果 auto_save_history = false，系统将不会保存任何消息记录，导致后续查询时无法获取 AI 的回复内容
custom_variables：智能体提示词中定义的变量。在智能体 prompt 中设置变量 {{key}} 后，可以通过该参数传入变量值，变量名只支持英文字母和下划线。

以下是一个请求消息体的示例：

{
    "bot_id": "7473391635976831011",
    "user_id": "XXX",
    "stream": false,
    "auto_save_history": true,
    "additional_messages": [
        {
            "role": "user",
            "content": "早上好！",
            "content_type": "text"
        }
    ]
}

注意：botid一定是字符串，如果没有用引号标识，作为数字输入会报botid不正确的错误。

3.5 返回消息体

消息的应答非流式和流式是差别比较大的，下面主要介绍的是非流式应答消息的主要内容：

1、code：调用状态码，整型，0 表示调用成功，其他值表示调用失败，失败可通过 msg 字段判断详细的错误原因

2、msg：状态信息，文本信息，API 调用失败时可通过此字段查看详细错误信息。状态码为 0 时，msg 默认为空。

3、data：返回智能体应答的详细内容，字典类型数据，包括如下子域

bot_id：字符串，该会话所属的智能体的 ID。
completed_at：整型，对话结束的时间。格式为 10 位的 Unixtime 时间戳，单位为秒
conversation_id：字符串，会话 ID，即会话的唯一标识
id：对话 ID，即对话的唯一标识
last_error：object类型，字典对象，包含code和msg字段，感觉和消息主体的code和msg重复
meta_data：发起对话时的附加消息，用于传入使用方的自定义数据，查看对话详情时也会返回此附加消息。自定义键值对，应指定为 Map 对象格式。长度为 16 对键值对，其中键（key）的长度范围为 1～64 个字符，值（value）的长度范围为 1～512 个字符
status：对话的运行状态。取值为：
※ created：对话已创建。
※ in_progress：智能体正在处理中。
※ completed：智能体已完成处理，本次对话结束。
※ failed：对话失败。
※ requires_action：对话中断，需要进一步处理。
※ canceled：对话已取消。

非流式响应返回消息内容示例：

{
    "data": {
        "id": "7568646187499667462",
        "conversation_id": "7568646187499634694",
        "bot_id": "7565727230333337636",
        "created_at": 1762212764,
        "last_error": {
            "code": 0,
            "msg": ""
        },
        "status": "in_progress"
    },
    "code": 0,
    "msg": ""
}

注意：

由于消息是以非流式响应发送的，这个应答是收到消息后的立即应答，状态为“in_progress”，表示智能体正处理相关任务
conversation_id：表示会话id，后续需要复用，记下来放到后续请求参数中
id：这个ID经验证就是对话id，即chatid
code：为0表示对话请求成功，如果不为0，则msg中返回错误原因。

四、查看对话详情API介绍

4.1、概述

在非流式会话场景中，调用发起对话接口后，可以先轮询调用 查看对话详情 API 确认本轮对话智能体是否已经处理结束（status=completed），如果已经处理结束，则再调用下个API接口查看对话消息详情查看本轮对话的智能体回复信息。

注意：

仅在对话开启了保存历史记录（auto_save_history=True）后，可通过此接口查看对话的详细信息。
建议每秒最多调用 1 次此接口，否则可能触发接口限流。

4.2、请求消息

该消息不需要单独的请求消息消息体，只需要URL地址即可。请求url为： https://api.coze.cn/v3/chat/retrieve?conversation_id={conversationID}&chat_id={chatID}&，需要的主要参数包括：

token：扣子 API访问令牌，以进行 API 请求的鉴权，token的生成请参考上篇博文《扣子(coze)智能体创建发布过程及开放API信息查阅方法》；
conversation_id：会话ID，可以为空，为空表示创建一个新会话，否则表示继承一个历史会话；
chat_id：对话的唯一标识，即上面发起对话消息应答消息中的ID。

4.3、应答消息

有2种应答消息：

任务还未处理完，返回应答消息的状态为in_progress，需要休眠后继续轮询；
任务处理完，返回应答消息的状态为completed。

应答的具体消息关键内容字段如下：

code：整数，调用状态码，0 表示调用成功，其他值表示调用失败，你可以通过 msg 字段判断详细的错误原因
msg：状态信息。API 调用失败时可通过此字段查看详细错误信息。状态码为 0 时，msg 默认为空
data：本次对话的基本信息，包括：
※ id：字符串，对话 ID，即对话的唯一标识
※ conversation_id：会话 ID，即会话的唯一标识
※ bot_id：该会话所属的智能体的 ID
※ status：对话的运行状态。取值及含义：created-对话已创建、in_progress-智能体正在处理中、completed-智能体已完成处理，本次对话结束、failed-对话失败、requires_action-对话中断，需要进一步处理、canceled-对话已取消

应答消息示例：

{
    "code": 0,
    "data": {
        "bot_id": "7473391635976831011",
        "conversation_id": "7474915122180292634",
        "created_at": 1740389300,
        "id": "7474915122180309018",
        "status": "in_progress"
    },
    "detail": {
        "logid": "2025022417282095E03F20E43A3B938B4E"
    },
    "msg": ""
}

五、查看对话消息详情API介绍

5.1、概述

查看指定对话中除 Query 以外的其他消息，包括模型回复、智能体执行的中间结果等消息。

查看对话消息详情 API 通常用于非流式对话场景中，查看某次对话（chat）中 type=answer 的智能体回复及 type=function_call、tool_response 和 follow-up 类型类型的对话中间态消息。不包括用户发送的 Query。

调用此 API 之前，建议先以每秒最多 1 次的频率轮询 查看对话详情 API 确认本轮对话已结束（status=completed），否则调用此 API 时获取到的消息内容可能不完整。

5.2、请求消息

该消息不需要单独的请求消息消息体，只需要URL地址即可:
https://api.coze.cn/v3/chat/message/list?chat_id={chatID}&conversation_id={conversationID}

除了消息头，带2个参数，对话ID（chatID，在发起对话接口 Response 中查看 id 字段）和会话ID（conversationID，在发起对话接口 Response 中查看 conversation_id 字段）。

5.3、应答消息

应答消息的关键内容如下：

code：整型，调用状态码。0 表示调用成功，其他值表示调用失败，可以通过 msg 字段判断详细的错误原因
msg：状态信息。API 调用失败时可通过此字段查看详细错误信息。状态码为 0 时，msg 默认为空
data：返回具体消息内容，是一个字典数据的json串，消息返回data数据有多条，每条消息的作用需要看type的取值，返回信息的关键字段如下：
※ bot_id：字符串，此消息的智能体 ID
※ chat_id：字符串，对话ID
※ conversation_id：会话ID
※ content：字符串，消息的内容，支持纯文本、多模态（文本、图片、文件混合输入）、卡片等多种类型的内容。当 role 为 user 时，支持返回多模态内容，当 role 为 assistant 时，只支持返回纯文本内容。示例：{“msg_type”:“generate_answer_finish”,“data”:“”,“from_module”:null,“from_unit”:null}
※ content_type：字符串，消息内容的类型，取值包括：text：文本，object_string：多模态内容，即文本和文件的组合、文本和图片的组合。card：卡片。此枚举值仅在接口响应中出现，不支持作为入参
※ id：Message ID，即消息的唯一标识
※ reasoning_content：模型的思维链（CoT），展示模型如何将复杂问题逐步分解为多个简单步骤并推导出最终答案。仅当模型支持深度思考、且智能体开启了深度思考时返回该字段
※ meta_data：创建消息时的附加消息，查看消息列表时也会返回此附加消息
※ role：发送这条消息的实体。取值：user：代表该条消息内容是用户发送的，assistant：代表该条消息内容是智能体发送的
※ type：消息类型，具体类型请参考下面的注释。

注：返回的消息类型type取值及其含义如下：

question：用户输入内容
answer：智能体返回给用户的消息内容，支持增量返回。如果工作流绑定了 messge 节点，可能会存在多 answer 场景，此时可以用流式返回的结束标志来判断所有 answer 完成
function_call：智能体对话过程中调用函数（function call）的中间结果
tool_output：调用工具（function call）后返回的结果
tool_response：调用工具（function call）后返回的结果
follow_up：如果在智能体上配置打开了用户问题建议开关，则会返回推荐问题相关的回复内容
verbose：多 answer 场景下，服务端会返回一个 verbose 包，对应的 content 为 JSON 格式，content.msg_type =generate_answer_finish 代表全部 answer 回复完成。
仅发起对话（v3）接口支持将此参数作为入参，且：
如果 autoSaveHistory=true，type 支持设置为 question 或 answer。
如果 autoSaveHistory=false，type 支持设置为 question、answer、function_call、tool_output、tool_response。
其中，type=question 只能和 role=user 对应，即仅用户角色可以且只能发起 question 类型的消息。

应答消息示例：

{
  "code": 0,
  "data": [
    {
      "bot_id": "7565727230333337636",
      "chat_id": "7569075867776647194",
      "content": "{\"name\":\"yuyinhecheng-speech_synthesis\",\"arguments\":{\"speaker_id\":\"爽快思思/Skye\",\"text\":\"娥曼\",\"language\":\"中文\",\"speed_ratio\":0.8,\"emotion_scale\":3},\"plugin_id\":7426655854067351562,\"plugin_name\":\"yuyinhecheng\",\"api_id\":7426655854067367946,\"api_name\":\"speech_synthesis\",\"plugin\":\"语音合成\",\"plugin_icon\":\"https://lf6-appstore-sign.oceancloudapi.com/ocean-cloud-tos/plugin_icon/372098605791453_1729153029627658847_7vpeyBUsGn.jpeg?lk3s=cd508e2b&x-expires=1764904673&x-signature=Ic7su2QX%2FWXlvHeyZ4f0kohqfzQ%3D\",\"plugin_icon_uri\":\"plugin_icon/372098605791453_1729153029627658847_7vpeyBUsGn.jpeg\",\"plugin_type\":1}",
      "content_type": "text",
      "conversation_id": "7569075867776598042",
      "created_at": 1762312810,
      "id": "7569075881710026802",
      "meta_data": {
        "call_id": "f918f5fa-2219-49f9-8770-e084e8ec20de"
      },
      "role": "assistant",
      "type": "function_call",
      "updated_at": 1762312810
    },
    {
      "bot_id": "7565727230333337636",
      "chat_id": "7569075867776647194",
      "content": "{\"log_id\":\"20251105112007E1FE42CE386279ADE3D6\",\"code\":0,\"msg\":\"success\",\"data\":{\"link\":\"https://lf26-appstore-sign.oceancloudapi.com/ocean-cloud-tos/VolcanoUserVoice/speech_7426720361753903141_eba7ceb9-22d2-468d-941d-73ae2cb8c381.mp3?lk3s=da27ec82&x-expires=1762572010&x-signature=Ke5yGV%2FrC4D1ejNDaG1Tf54FSw4%3D\",\"duration\":1.464}}",
      "content_type": "text",
      "conversation_id": "7569075867776598042",
      "created_at": 1762312811,
      "id": "7569075882367942707",
      "meta_data": {
        "call_id": "f918f5fa-2219-49f9-8770-e084e8ec20de"
      },
      "role": "assistant",
      "type": "tool_response",
      "updated_at": 1762312810
    },
    {
      "bot_id": "7565727230333337636",
      "chat_id": "7569075867776647194",
      "content": "已将\"娥曼\"转换为语音。你可以点击下面的链接下载生成的语音文件：\n[speech_7426720361753903141_eba7ceb9-22d2-468d-941d-73ae2cb8c381.mp3](https://lf26-appstore-sign.oceancloudapi.com/ocean-cloud-tos/VolcanoUserVoice/speech_7426720361753903141_eba7ceb9-22d2-468d-941d-73ae2cb8c381.mp3?lk3s=da27ec82&x-expires=1762572010&x-signature=Ke5yGV%2FrC4D1ejNDaG1Tf54FSw4%3D)\n语音时长：1.464 秒\n本次使用的音色为：爽快思思/Skye，语速为 0.8。",
      "content_type": "text",
      "conversation_id": "7569075867776598042",
      "created_at": 1762312810,
      "id": "7569075881710010418",
      "reasoning_content": "",
      "role": "assistant",
      "type": "answer",
      "updated_at": 1762312817
    },
    {
      "bot_id": "7565727230333337636",
      "chat_id": "7569075867776647194",
      "content": "{\"msg_type\":\"generate_answer_finish\",\"data\":\"{\\\"finish_reason\\\":0,\\\"FinData\\\":\\\"\\\"}\",\"from_module\":null,\"from_unit\":null}",
      "content_type": "text",
      "conversation_id": "7569075867776598042",
      "created_at": 1762312819,
      "id": "7569075915172544522",
      "role": "assistant",
      "type": "verbose",
      "updated_at": 1762312819
    },
    {
      "bot_id": "7565727230333337636",
      "chat_id": "7569075867776647194",
      "content": "可以将\"娥曼\"转换为其他音色吗？",
      "content_type": "text",
      "conversation_id": "7569075867776598042",
      "created_at": 1762312819,
      "id": "7569075915172593674",
      "role": "assistant",
      "type": "follow_up",
      "updated_at": 1762312819
    },
    {
      "bot_id": "7565727230333337636",
      "chat_id": "7569075867776647194",
      "content": "如何调整语音的语速？",
      "content_type": "text",
      "conversation_id": "7569075867776598042",
      "created_at": 1762312819,
      "id": "7569075915172610058",
      "role": "assistant",
      "type": "follow_up",
      "updated_at": 1762312819
    },
    {
      "bot_id": "7565727230333337636",
      "chat_id": "7569075867776647194",
      "content": "还有哪些语音可以转换？",
      "content_type": "text",
      "conversation_id": "7569075867776598042",
      "created_at": 1762312819,
      "id": "7569075915172626442",
      "role": "assistant",
      "type": "follow_up",
      "updated_at": 1762312819
    }
  ],
  "detail": {
    "logid": "20251105112020FDDB849D7CFD79AE947B"
  },
  "msg": ""
}

六、小结

本文介绍了调用扣子智能体平台智能体实现非流式对话的过程，并介绍了实现中需要涉及的API相关请求和应答消息内容。通过发起对话API实现向智能体提交服务请求，通过查看对话详情API查看对话是否处理完成，通过查看对话消息详情API可以获取非流式对话的智能体处理完成应答，就可以在客户端远程调用一次智能体服务。

更多人工智能知识学习过程中可能遇到的疑难问题及解决办法请关注专栏《零基础机器学习入门》及付费专栏《机器学习疑难问题集》后续的文章。