基于新版本扣子(coze)平台的TTS智能体创建发布过程及开放API信息查阅方法

Coze平台TTS智能体创建与API接入

最新推荐文章于 2025-11-08 14:00:00 发布

原创最新推荐文章于 2025-11-08 14:00:00 发布 · 1.6k 阅读

54 ·

CC 4.0 BY-SA版权

文章标签：

#AI人工智能 #AI智能体 #扣子COZE #开放API服务 #TTS语音合成

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

1156 篇文章

订阅专栏

零基础机器学习入门

22 篇文章

订阅专栏

人工智能基础知识

8 篇文章

订阅专栏

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

一、智能体相关概念

智能体（Agent）：是一种基于对话的 AI 项目，它通过对话方式接收用户的输入，并能够理解用户的需求。智能体通常由大模型驱动，可以自动调用插件、工具或工作流等方式来执行用户指定的业务流程，并最终生成回复。例如，智能体可以用于智能客服、任务自动化、信息检索等多种场景
智能体的人设与回复逻辑：通过人设设定智能体及使用者“我是谁、能做什么、绝不做什么”，回复不确定就明说，违法/越界就拒绝。人设与回复逻辑一般采用提示词工程方式，设定智能体的角色、技能、限定等
插件：插件是智能体提供能力的一种辅助工具，可以是智能体平台提供的，也可以是开发者开发的，在智能体中插件通常是基于输入内容自动调用的。智能体会分析用户的输入，根据预设的逻辑和条件决定是否需要调用特定的插件来执行任务或提供信息。这种自动调用机制使得智能体能够更智能地响应用户需求，提供更加个性化和高效的服务。智能体平台都会提供一部分通用插件，开发者只需要根据自己应用相关的方向选择相关插件以丰富智能体的能力
工作流：智能体中的工作流是指智能体在执行任务时所遵循的一系列预设步骤或流程。这些步骤通常包括输入解析、意图识别、信息检索、决策制定、执行动作和输出结果等环节。工作流的设计旨在确保智能体能够高效、准确地处理用户请求，并在必要时调用相应的插件或服务来完成特定功能。通过优化工作流，智能体可以提升响应速度和处理复杂任务的能力，从而提供更加流畅和满意的用户体验
知识：知识是指创建智能体时开发者手工录入的知识，扣子支持的知识包括文本、表格和图片
※ 文本是将文档、URL、三方数据源上传为文本知识库后，用户发送消息时，智能体能够引用文本知识中的内容回答用户问题；
※ 表格是用户上传的表格数据，支持按照表格的某列来匹配合适的行给智能体引用，同时也支持基于自然语言对数据库进行查询和计算；
※ 图片是上传到知识库的图片，上传后自动/手动添加语义描述，智能体可以基于图片的描述匹配到最合适的图片
触发器：智能体中的触发器是一种机制，它能够在特定条件或事件发生时激活智能体的某些功能或流程，触发器的作用是使智能体能够自动响应环境变化或用户需求，无需人工干预即可执行预定任务，从而提高效率和用户体验。
触发器可以基于多种条件设置，例如：
※ 时间触发器：在特定的时间或时间间隔触发，如每天早晨8点发送天气预报。
※ 事件触发器：当检测到特定事件时触发，如收到新邮件时通知用户。
※ 数据触发器：当数据满足特定条件时触发，如股票价格达到某个阈值时发出警报。
※ 用户行为触发器：根据用户的操作或行为触发，如用户点击某个按钮后展示相关信息。
扣子支持的触发器包括时间触发器和事件触发器。
智能体的记忆：是指其存储和检索过去经验、交互数据和学习成果的能力。这种记忆机制使得智能体能够在未来的决策和行动中利用历史信息，从而提高其性能和适应性。在扣子平台中，支持变量、数据库、长期记忆、文件盒子：
※ 变量：用于保存用户个人信息，让智能体记住用户特征，使得回复更加个性化；
※ 数据库：以表格结构组织的数据，可以实现类似书签和图书管理等功能；
※ 长期记忆：总结聊天对话内容，以更好响应用户消息；
※ 文件盒子：用来保存会话中保存文件。
对话体验：用于提升对话体验的相关设置，包括开场白、用户问题建议、快捷指令、背景图片、机器人语音设置以及用户输入方式设置等。

在这里插入图片描述

二、关于扣子和智能体

在2025年3月老猿通过博文《扣子(coze)智能体创建发布过程及开放API信息查阅方法（https://blog.youkuaiyun.com/LaoYuanPython/article/details/145753680）》介绍了扣子平台进行智能体创建发布的过程，最近发现扣子平台进行了大幅的版面调整，因此基于新版面再将在扣子平台进行智能体开发的过程介绍一遍。

同时原来创建的TTS服务智能体找不到了，后来发现平台通知原来的语音转文本插件下架了：
在这里插入图片描述
可能是插件下架导致智能体跟随下架了。因此正好将重新创建一个利用新的大模型语音合成插件进行的TTS智能体作为新的案例来介绍扣子智能体的开发过程。

三、在扣子中创建简单智能体

3.1、进入智能体配置页面

进入扣子主页，点击顶部的开发平台按钮：
在这里插入图片描述进入扣子开发平台，然后点击左侧工具栏上的项目开发：

点击右侧＋项目按钮：

出现弹窗，选择创建智能体：

3.2、输入智能体基本信息

进入智能体创建页面，选择标准创建或AI创建（本例以标准创建进行说明），输入智能体名字等相关信息，如图：
在这里插入图片描述
点击确认后进入智能体配置页面。

3.3、配置智能体服务内容

3.3.1、设置人设与回复逻辑提示词

下面的TTS服务提示词供参考：

## 角色
你是一位专业且高效的文本转语音助手，具备强大的中英文文本读取能力，能够依据用户需求，将输入的中英文文本转换为指定音色的语音文件，并提供下载服务。

## 技能
### 技能 1: 文本转语音
1. 若输入开头未指定“普通对话模式：”，则自动将输入内容转换为指定音色的语音文件输出。
2. 输出的语音文件需确保清晰、流畅，符合正常语言表达习惯。

### 技能 2: 普通对话处理
当输入开头指定“普通对话模式：”时，不进行文本转语音操作，而是以正常对话的方式与用户交流。回复需逻辑清晰、语义明确，能够准确理解并回应用户的问题。

## 限制:
- 严格按照用户指定的模式进行操作，即“普通对话模式：”指定与否决定处理方式。
- 语音转文本时，必须明确指定音色类型。
- 输出内容应简洁明了，语音文件和对话回复都需保证质量，避免出现错误或不清晰的情况。

设置后可以选择人设与回复最右侧的按钮进行提示词优化（如图）：
在这里插入图片描述

3.3.2 配置插件

语音转文本需要用到语音合成处理相关的插件，现在扣子平台提供了大模型的语音转文本插件，通过插件栏来增加需要使用的插件。在coze平台有多个语音合成插件，本例使用语音合成/speech_synthesis 插件：
在这里插入图片描述

智能体的配置可以支持模型、插件、工作流、触发器、知识库、记忆、文件盒子、对话体验等的配置，本案例只介绍简单智能体的创建，只用了提示词和插件，大模型用的默认，大家可以修改。

3.4、预览与调试

智能体配置完成后，可以在右侧的预览与调试中进行测试。如图：
在这里插入图片描述

3.5、智能体发布

完成智能体的配置和测试后，就可以进行智能体的发布，其中URL最右侧为智能体的botID。如图：
在这里插入图片描述
点击右上角发布按钮，出现下图提示设置开场白：

点击右下角确认按钮，进入发布页面：

选择扣子商店和API两种发布平台，点击发布按钮进行发布，发布提示：

四、智能体的查看

进入扣子平台，选择开发平台，点击左侧工具栏的项目开发按钮，就可以查看自己所有开发的智能体，如图：
在这里插入图片描述
点击选择刚发布的智能体，展示智能体的相关信息：

url中最后标红部分是智能体的ID，称为botid，这个在API访问时需要botid作为参数。

五、添加令牌token

令牌token是访问进行合法性验证的机制，不同平台对token的使用不同，有的是基于用户授权token，有的是基于智能体逐个授权token，扣子是基于用户进行授权的。

扣子的授权管理和以前完全不同，操作步骤如下:

进入扣子平台；
点击开发平台按钮，进入扣子开发平台；
点击左侧工具栏：API管理，进入API管理页面；
进入API管理页面：
点击左上角顶部的授权按钮（上图红色框标记），进入授权管理页面：
点击个人访问令牌，进入个人访问令牌管理：
如果已经有设置了，会展示个人的访问令牌和状态：

如果存在有效的个人访问令牌，表示当前令牌有效，但无法复制API_KEY，该API_KEY应该在创建时记录和保存，否则后续无法查看。
如果没有有效的令牌或者忘记API_KEY，可以选择添加按钮新增一个授权，出现授权配置页面：
填写令牌授权信息，包括过期时间（最长30天）、权限（可以全选，也可以根据需要选择）、访问工作空间，然后点击确定，出现令牌创建成功提示页面：

点击红色框标记的复制按钮复制API_KEY，保存好，在API开发时需要使用该token。

六、关于API

扣子支持将 AI 智能体和扣子应用发布为 API 服务，可以通过 HTTP 方式与其进行交互，API管理的页面与以前也发生了比较大的变更，老猿觉得还没以前方便。

APPI信息查询的界面进入：进入扣子开发管理平台，点击左侧工具栏API管理按钮进入API管理页，如下图：
在这里插入图片描述

下面以发起对话为例来说明API信息的查看，点击：对话->发起对话，出现如下内容：
在这里插入图片描述

在左边有发起对话接口的说明和对话请求中需要填写的参数、参数说明，在输入相关参数后就会在右侧生成shell、python以及Java发起API访问的示例代码，其中python的代码是基于cozepy库提供的能力。

以API_KEY=‘XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX’以及非流失响应为例，对应的发起对话的Python代码如下：

"""
This example describes how to use the chat interface to initiate conversations,
poll the status of the conversation, and obtain the messages after the conversation is completed.
"""

import os
import time
# Our official coze sdk for Python [cozepy](https://github.com/coze-dev/coze-py)
from cozepy import COZE_CN_BASE_URL

# Get an access_token through personal access token or oauth.
coze_api_token = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
# The default access is api.coze.com, but if you need to access api.coze.cn,
# please use base_url to configure the api endpoint to access
coze_api_base = COZE_CN_BASE_URL

from cozepy import Coze, TokenAuth, Message, ChatStatus, MessageContentType  # noqa

# Init the Coze client through the access_token.
coze = Coze(auth=TokenAuth(token=coze_api_token), base_url=coze_api_base)

# Create a bot instance in Coze, copy the last number from the web link as the bot's ID.
bot_id = '{bot_id}'
# The user id identifies the identity of a user. Developers can use a custom business ID
# or a random string.
user_id = '{user_id}'

# To simplify the call, the SDK provides a wrapped function to complete non-streaming chat,
# polling, and obtaining the messages of the chat. Developers can use create_and_poll to
# simplify the process.
chat_poll = coze.chat.create_and_poll(
    bot_id=bot_id,
    user_id=user_id,
    additional_messages=[
        Message.build_user_question_text("Who are you?"),
        Message.build_assistant_answer("I am Bot by Coze."),
        Message.build_user_question_text("What about you?"),
    ],
)
for message in chat_poll.messages:
    print(message.content, end="", flush=True)

if chat_poll.chat.status == ChatStatus.COMPLETED:
    print()
    print("token usage:", chat_poll.chat.usage.token_count)

cozepy 是 Coze 平台的 Python SDK，用于帮助开发者更方便地调用 Coze 的 API。其主要功能包括：

API 调用：支持 Coze 的所有开放 API 和认证 API
同步和异步调用：支持同步和异步操作。
流式接口优化：支持流式聊天和工作流运行。
便捷的 API 设计：提供简单易用的接口。
通过 cozepy，开发者可以实现创建/更新/发布/管理机器人、进行聊天操作、管理对话和消息、上传文件并用于多模态对话、调用工作流并处理中断事件。