使用Python requests库调用扣子(coze)API实现AI智能体对话案例

置顶 LaoYuanPython

已于 2025-03-02 15:19:21 修改

阅读量3.5k

点赞数 41

分类专栏：老猿Python 零基础机器学习入门文章标签： python coze扣子AI应用开发 AI智能体开放API requests库

于 2025-03-01 16:51:51 首次发布

本文链接：https://blog.csdn.net/LaoYuanPython/article/details/145829443

版权

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

1144 篇文章

订阅专栏

零基础机器学习入门

11 篇文章

订阅专栏

☞ ░ 前往老猿Python博客 ░ https://blog.csdn.net/LaoYuanPython

一、引言

在《扣子(coze)智能体创建发布过程及开放API信息查阅方法》介绍了如何在字节跳动旗下扣子AI应用开发平台开发一个简单智能体的全过程，并介绍了访问智能体的API文档信息查阅方法。

coze官方API文档中提供的Python调用是基于cozepy库来实现的，由于只能访问coze应用平台，没有通用性，因此本文介绍利用Python requests库调用API访问扣子(coze)智能体实现对话作为案例，对于访问别的智能体平台有一定的参考价值。

在这里插入图片描述

二、一些基础概念

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

三、对应接口说明

本案例是实现与智能体对话，智能体已经在上篇博文《扣子(coze)智能体创建发布过程及开放API信息查阅方法》中介绍了创建发布过程，在此直接使用。
要实现对话，需要使用对话相关API，这些API请见coze官方API管理信息：
在这里插入图片描述

3.1、发起对话

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

本文案例采用的是非流式响应。

请求url为： https://api.coze.cn/v3/chat，请求需要的主要参数包括：

token：扣子 API访问令牌，以进行 API 请求的鉴权，token的生成请参考上篇博文《扣子(coze)智能体创建发布过程及开放API信息查阅方法》；
conversation_id：会话ID，可以为空，为空表示创建一个新会话，否则表示继承一个历史会话；
bot_id：智能体ID，请参考上篇博文《扣子(coze)智能体创建发布过程及开放API信息查阅方法》；
user_id：平台用户ID；
stream：是否启用流式响应；
additional_messages.content：要发送的消息内容；
additional_messages.content_type：消息内容的类型，支持为text或object_string；
additional_messages.role：发送这条消息的实体，user：代表该条消息内容是用户发送的，assistant：代表该条消息内容是智能体发送的；
additional_messages.type：消息类型，取值包括question、answer、function_call等。如果 autoSaveHistory=true，type 支持设置为 question 或 answer。如果 autoSaveHistory=false，type 支持设置为 question、answer、function_call、tool_output/tool_response。其中，type=question 只能和 role=user 对应，即仅用户角色可以且只能发起 question 类型的消息
※ question：用户输入内容
※ answer：智能体返回给用户的消息内容，支持增量返回。如果工作流绑定了消息节点，可能会存在多 answer 场景，此时可以用流式返回的结束标志来判断所有 answer 完成
※ function_call：智能体对话过程中调用函数（function call）的中间结果。
※ tool_response：调用工具（function call）后返回的结果。
auto_save_history：是否保存本次对话记录。

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

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

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

返回消息内容示例：

{
    "data": {
        "id": "7474915122180309018",
        "conversation_id": "7474915122180292634",
        "bot_id": "7473391635976831011",
        "created_at": 1740389300,
        "last_error": {
            "code": 0,
            "msg": ""
        },
        "status": "in_progress"
    },
    "code": 0,
    "msg": ""
}

注意：

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

3.2、查看对话详情

在非流式会话场景中，调用发起对话接口后，可以先轮询此 API 确认本轮对话已结束（status=completed），再调用接口查看对话消息详情查看本轮对话的模型回复。

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

该消息不需要单独的请求消息消息体，只需要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。

有2种应答消息：

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

应答消息示例：

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

3.3、查看对话消息详情

查看指定对话中模型回复、智能体执行的中间结果等消息。
查看对话消息详情 API 通常用于非流式对话场景中，查看某次对话（chat）中 type=answer 的智能体回复及 type=follow-up 等类型的对话中间态消息。

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

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

应答消息示例：

{
    "code": 0,
    "data": [
        {
            "bot_id": "7473391635976831011",
            "chat_id": "7474915122180309018",
            "content": "早上好！有什么关于饮食与健康方面的问题，都可以来问我哦，比如你在饮食上有什么疑惑，或者想让我帮你制定饮食计划，都尽管说。  ",
            "content_type": "text",
            "conversation_id": "7474915122180292634",
            "created_at": 1740389300,
            "id": "7474915122180538394",
            "reasoning_content": "",
            "role": "assistant",
            "type": "answer",
            "updated_at": 1740389302
        },
        {
            "bot_id": "7473391635976831011",
            "chat_id": "7474915122180309018",
            "content": "{\"msg_type\":\"generate_answer_finish\",\"data\":\"{\\\"finish_reason\\\":0,\\\"FinData\\\":\\\"\\\"}\",\"from_module\":null,\"from_unit\":null}",
            "content_type": "text",
            "conversation_id": "7474915122180292634",
            "created_at": 1740389304,
            "id": "7474915133123395611",
            "role": "assistant",
            "type": "verbose",
            "updated_at": 1740389304
        },
        {
            "bot_id": "7473391635976831011",
            "chat_id": "7474915122180309018",
            "content": "制定一份一周的健康减肥食谱",
            "content_type": "text",
            "conversation_id": "7474915122180292634",
            "created_at": 1740389304,
            "id": "7474915133123428379",
            "role": "assistant",
            "type": "follow_up",
            "updated_at": 1740389304
        },
        {
            "bot_id": "7473391635976831011",
            "chat_id": "7474915122180309018",
            "content": "高血糖患者应该避免食用哪些食物？",
            "content_type": "text",
            "conversation_id": "7474915122180292634",
            "created_at": 1740389304,
            "id": "7474915133123444763",
            "role": "assistant",
            "type": "follow_up",
            "updated_at": 1740389304
        },
        {
            "bot_id": "7473391635976831011",
            "chat_id": "7474915122180309018",
            "content": "地中海饮食对健康有哪些好处？",
            "content_type": "text",
            "conversation_id": "7474915122180292634",
            "created_at": 1740389304,
            "id": "7474915133123461147",
            "role": "assistant",
            "type": "follow_up",
            "updated_at": 1740389304
        }
    ],
    "detail": {
        "logid": "20250224172825B3BFE4D387216708F753"
    },
    "msg": ""
}

消息返回data数据有多条，每条消息的作用需要看type的取值，返回信息的关键字段如下：
1、content：智能体返回给用户的消息内容
2、type：返回消息的类别

answer：content中为智能体针对请求的返回应答文本内容
verbose：多 answer 场景下，服务端会返回一个 verbose 包，对应的 content 为 JSON 格式，content.msg_type =generate_answer_finish 代表全部 answer 回复完成，如果不采用轮询 查看对话详情 API 确认本轮对话已结束（status=completed）时，也可以通过此机制判断回复是否完成
follow-up：如果在智能体上配置打开了用户问题建议开关，则会返回推荐问题相关的回复内容，content中为推荐的问题

四、程序示例代码

上面介绍了coze平台对话相关的三个API，通过顺序发起对话->查看对话详情->查看对话消息详情三个API，就可以在客户端远程调用一次智能体服务。

下面是使用Python requests库调用扣子(coze)API实现AI智能体对话的一个参考案例：

import requests
import json,time

api_key = "pat_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

botid = "7473391635976831011"
baseUrl =  'https://api.coze.cn/v3/chat'
headers = {
    "Authorization": f"Bearer {api_key}",
    'Content-Type': 'application/json'
}

def processQuestionAnswer(response_data):
    if response_data['code']:
        print("应答异常：",response_data['msg'])
    else:
        data = response_data['data']
        count = 0
        for item in data:
            if item['type']=='answer':
                print("大模型应答：",item['content'])
            elif item['type']=='follow_up':
                if count==0:
                    print("您可以参考如下方式提问：")
                print(f"☆ 问题{count+1}：",item['content'])
                count += 1


def getQuesyionAnswer(conversationID,chatID):
    params = { "bot_id": botid,"task_id": chatID }
    getChatStatusUrl = baseUrl+f'/retrieve?conversation_id={conversationID}&chat_id={chatID}&'
    
    while True:
        response = requests.get(getChatStatusUrl, headers=headers, params=None)
        if response.status_code == 200:
            response_data = response.json()
            print(f"response_data:\n{json.dumps(response_data,indent=4, ensure_ascii=False)}")
            status = response_data['data']['status']
            if status == 'completed':
                # 从响应中提取实际的应答内容
                getChatAnswerUrl = baseUrl+f'/message/list?chat_id={chatID}&conversation_id={conversationID}'
                response = requests.get(getChatAnswerUrl, headers=headers, params=params)
                if response.status_code == 200:
                    response_data = response.json()
                    print("模型返回数据:\n", json.dumps(response_data,indent=4, ensure_ascii=False))
                    processQuestionAnswer(response_data)
                    return True
                break
            else:
                print(f"任务仍在处理中，状态: {status}")
                time.sleep(1)  # 等待5秒后再次检查
        else:
            print(f"请求失败，状态码: {response.status_code}")
            break
    return False
        
def questionService(questionText):
     
    # 定义API的URL和授权令牌

    data = {
    "bot_id": botid,
    "user_id": "jiangwp",
    "stream": False,
    "auto_save_history": True,
    "additional_messages": [
        {
            "role": "user",
            "content": questionText,
            "content_type": "text"
        }
        ]
    }

    # 发送POST请求
    print(f"请求信息:{json.dumps(data,indent=4, ensure_ascii=False)}")
    response = requests.post(baseUrl, headers=headers, data=json.dumps(data))

    # 检查响应状态码
    if response.status_code == 200:
        # 解析响应内容
        response_data = response.json()
        print("响应内容:", json.dumps(response_data,indent=4, ensure_ascii=False))
        chatid = response_data['data']['id']
        answer = response_data.get("answer")
        conversation_id = response_data['data']['conversation_id']
        print(f"chatid={chatid},智能体应答: {answer}")

        getQuesyionAnswer(conversation_id,chatid)

    else:
        print("请求失败，状态码:", response.status_code)
        print("错误信息:", response.text)



questionService("Dify是什么？")

程序输出信息如下：

请求信息:{
    "bot_id": "7473391635976831011",
    "user_id": "jiangwp",
    "stream": false,
    "auto_save_history": true,
    "additional_messages": [
        {
            "role": "user",
            "content": "Dify是什么？",
            "content_type": "text"
        }
    ]
}
响应内容: {
    "data": {
        "id": "7475257328695164954",
        "conversation_id": "7475257328695148570",
        "bot_id": "7473391635976831011",
        "created_at": 1740468976,
        "last_error": {
            "code": 0,
            "msg": ""
        },
        "status": "in_progress"
    },
    "code": 0,
    "msg": ""
}
chatid=7475257328695164954,智能体应答: None
response_data:
{
    "code": 0,
    "data": {
        "bot_id": "7473391635976831011",
        "conversation_id": "7475257328695148570",
        "created_at": 1740468977,
        "id": "7475257328695164954",
        "status": "in_progress"
    },
    "detail": {
        "logid": "20250225153617FDAC4DFF66ABFC06349B"
    },
    "msg": ""
}
任务仍在处理中，状态: in_progress
response_data:
{
    "code": 0,
    "data": {
        "bot_id": "7473391635976831011",
        "conversation_id": "7475257328695148570",
        "created_at": 1740468977,
        "id": "7475257328695164954",
        "status": "in_progress"
    },
    "detail": {
        "logid": "202502251536185C3716AA38C8430A3CFB"
    },
    "msg": ""
}
任务仍在处理中，状态: in_progress
response_data:
{
    "code": 0,
    "data": {
        "bot_id": "7473391635976831011",
        "conversation_id": "7475257328695148570",
        "created_at": 1740468977,
        "id": "7475257328695164954",
        "status": "in_progress"
    },
    "detail": {
        "logid": "202502251536196FE43050EDAB7205C321"
    },
    "msg": ""
}
任务仍在处理中，状态: in_progress
response_data:
{
    "code": 0,
    "data": {
        "bot_id": "7473391635976831011",
        "conversation_id": "7475257328695148570",
        "created_at": 1740468977,
        "id": "7475257328695164954",
        "status": "in_progress"
    },
    "detail": {
        "logid": "2025022515362066DD46AB5621640A4BE5"
    },
    "msg": ""
}
任务仍在处理中，状态: in_progress
response_data:
{
    "code": 0,
    "data": {
        "bot_id": "7473391635976831011",
        "completed_at": 1740468982,
        "conversation_id": "7475257328695148570",
        "created_at": 1740468977,
        "id": "7475257328695164954",
        "status": "completed",
        "usage": {
            "input_count": 647,
            "output_count": 54,
            "token_count": 701
        }
    },
    "detail": {
        "logid": "20250225153621F4E616C4ACCC210B83FB"
    },
    "msg": ""
}
模型返回数据:
 {
    "code": 0,
    "data": [
        {
            "bot_id": "7473391635976831011",
            "chat_id": "7475257328695164954",
            "content": "很抱歉，我只能回答与饮食和健康有关的问题。如果你有饮食与健康方面的问题，比如关于某种食物对健康的影响、如何制定健康的饮食计划等，都可以随时问我，我会尽力为你解答。  ",
            "content_type": "text",
            "conversation_id": "7475257328695148570",
            "created_at": 1740468977,
            "id": "7475257328695296026",
            "reasoning_content": "",
            "role": "assistant",
            "type": "answer",
            "updated_at": 1740468978
        },
        {
            "bot_id": "7473391635976831011",
            "chat_id": "7475257328695164954",
            "content": "{\"msg_type\":\"generate_answer_finish\",\"data\":\"{\\\"finish_reason\\\":0,\\\"FinData\\\":\\\"\\\"}\",\"from_module\":null,\"from_unit\":null}",
            "content_type": "text",
            "conversation_id": "7475257328695148570",
            "created_at": 1740468981,
            "id": "7475257347137634355",
            "role": "assistant",
            "type": "verbose",
            "updated_at": 1740468981
        },
        {
            "bot_id": "7473391635976831011",
            "chat_id": "7475257328695164954",
            "content": "Dify和ChatGPT有什么区别？",
            "content_type": "text",
            "conversation_id": "7475257328695148570",
            "created_at": 1740468982,
            "id": "7475257347137650739",
            "role": "assistant",
            "type": "follow_up",
            "updated_at": 1740468981
        },
        {
            "bot_id": "7473391635976831011",
            "chat_id": "7475257328695164954",
            "content": "如何使用Dify？",
            "content_type": "text",
            "conversation_id": "7475257328695148570",
            "created_at": 1740468982,
            "id": "7475257351251951653",
            "role": "assistant",
            "type": "follow_up",
            "updated_at": 1740468981
        },
        {
            "bot_id": "7473391635976831011",
            "chat_id": "7475257328695164954",
            "content": "Dify的应用场景有哪些？",
            "content_type": "text",
            "conversation_id": "7475257328695148570",
            "created_at": 1740468982,
            "id": "7475257351251968037",
            "role": "assistant",
            "type": "follow_up",
            "updated_at": 1740468981
        }
    ],
    "detail": {
        "logid": "20250225153621C49658C32F868A0B3936"
    },
    "msg": ""
}
大模型应答： 很抱歉，我只能回答与饮食和健康有关的问题。如果你有饮食与健康方面的问题，比如关于某种食物对健康的影响、如何制定健康的饮食计划等，都可以随时问我，我会尽力为你解答。  
您可以参考如下方式提问：
☆ 问题1： Dify和ChatGPT有什么区别？
☆ 问题2： 如何使用Dify？
☆ 问题3： Dify的应用场景有哪些？