1.2 Coze平台入门实战¶

学习目标¶

了解Coze平台中的基本功能
掌握工作流的搭建和常见节点的用法
掌握常见的工作流的使用
掌握完整的智能体的搭建

一、Coze平台的基本使用¶

1 功能简介¶

1.1 工作空间¶

空间是资源组织的基础单元，不同空间内的资源和数据相互隔离。一个空间内可创建多个智能体和 AI 应用，并包含一个资源库。在资源库中创建的资源可以被相同空间内的智能体和 AI 应用使用。

工作空间存在的意义是为了隔离不同的业务，比如某公司采购了一个企业版的Coze，公司有做打车业务的、有做金融业务的，这些业务团队之间只能访问自己业务团队的开发好的智能体和应用，团队之间应当互相隔离。

1.2 项目¶

项目分为智能体和 AI 应用两种类型，AI 应用内可以创建多种应用专属资源，也可以和智能体共享空间资源库中的资源。

当我们创建一个项目时，如下图，有智能体和应用两种选择。

关于智能体和AI应用我们在上文已经给出大家解释，以下是官方文档中的原文：

智能体：智能体（Agent）通常指的是一个能够独立执行任务、做出决策并进行学习的一种自动化程序。智能体可以根据用户输入的指令，自主调用模型、知识库、插件等技能并完成编排，最终完成用户的指令。
AI 应用：AI 应用是指利用大模型技术开发的应用程序，这些应用程序能够使用大模型，执行复杂任务，分析数据，并作出决策。

空间和项目以及资源库的关系图下图，可以看到：

一个空间中可以包含多个项目，包括智能体AI应用两种类型
智能体和AI应用的开发会引用资源库中的多种资源类型。

1.3 资源库¶

资源库：你可以在资源库内创建、发布、管理共享资源，例如插件、知识库、数据库、提示词等。这些资源可以被同一空间内的智能体和应用使用。

资源可以存在于两个实体内，一个是空间的资源库，一个是 AI 应用项目中的项目资源库。

空间资源库：在空间资源库内创建的资源可以被空间内的 AI 应用项目和智能体项目使用，属于空间内的共享资源。
AI 应用项目：在 AI 应用项目中也可以创建资源，但这些资源是项目自有的资源，默认不可以被其他项目使用也不会展示在空间资源库内。

当需要将 AI 应用项目中的资源转换成公共资源给其他 AI 应用或智能体使用时，可以将这些资源转移或复制到空间资源库内。

在资源库中添加一个资源，我们可以看到，coze平台支持如下几种资源类型。并非所有的资源类型都是常用的，在实际工作中，我们最常用的是插件、工作流、对话流、知识库、数据库。

1.4 插件¶

扣子平台提供了一个多样化的插件库，这些插件涵盖了从基础的文本处理到高级的机器学习功能。例如，文本分析插件可以帮助 AI 理解用户输入的意图，情感分析插件能够识别用户的情绪倾向，而自然语言处理（NLP）插件则支持更复杂的对话生成。
此外，还有图像识别、语音识别、数据分析等插件，这些插件的数量和种类不断增加，以适应不断变化的技术趋势和市场需求。

1.5 工作流和对话流¶

coze平台 提供了灵活的工作流设计工具，开发者可以通过拖拽式界面轻松搭建复杂的对话流程 。工作流本质是一个有向无环图，由边和节点构成，边代表执行顺序，节点则表示一个具体的执行步骤
工作流用于处理功能类的请求，可通过顺序执行一系列节点实现某个功能。适合数据的自动化处理场景，例如生成行业调研报告、生成一张海报、制作绘本等。

工作流是coze平台最核心的功能，它是资源库中一种特殊的资源类型，我们在实际工作中，几乎所有的功能都需要基于工作流实现。我们上文中提到的插件、知识库、数据库这些核心功能，在实际开发时，都是作为工作流中的节点进行使用。
对话流是基于对话场景的特殊工作流，更适合处理对话类请求。对话流通过对话的方式和用户交互，并完成复杂的业务逻辑。对话流适用于 Chatbot 等需要在响应请求时进行复杂逻辑处理的对话式应用程序，例如个人助手、智能客服、虚拟伴侣等。

工作流的具体使用方法，我们在后面将用一个较长的篇幅进行介绍。

1.6 知识库和数据库¶

扣子开发平台支持使用扣子官方知识库和火山知识库（更加专业版的知识库），两者均支持上传和存储外部知识内容，并提供了多种检索能力。扣子的知识能力可以解决大模型幻觉、专业领域知识不足的问题，提升大模型回复的准确率。
知识库中一般存放的是各类文档数据，比如专业书籍、说明书、产品介绍文档等文本类数据。
数据库存放的是各类业务记录，比如订单、流水、操作记录等结构化数据。

2 工作流的使用¶

智能体、AI应用和工作流的关系和前文中项目和资源库的关系类似，一个项目（智能体、AI应用）可以引用多个工作流。但是在这里我们强调的是，几乎所有的资源类型都是以智能体引入工作流的方式

接下来，我们将使用一个”旅游规划小助手“作为案例，帮助同学理解工作流的使用和

2.1 创建一个工作流¶

进入资源库页面，点击右上角的”+资源“，即可完成工作流的创建

点击后，弹出如下页面：

输入以下内容：
工作流名称：需要全英文+数字+下划线的方式输入，长度不可超过30
工作流的描述：需要告诉大模型什么时候调用工作流。 在一个智能体中添加多个工作流时，大模型可以通过工作流描述，自动去调用工作流。在后续的项目中，我们将使用这种方式实现一个智能体根据业务场景不同调用多个工作流。
点击创建后，进入如下页面。这个页面是一个可以拖动控件进行操作的画布，初始包含：开始和两个节点
开始：工作流的入口，相当于一段程序中的主函数，接收变量并传递到后面的节点。开始节点支持配置 String、Number 等多种类型的输入参数。其中 Object 类型的参数最多支持 3 层嵌套。
- 返回变量模式下，工作流运行结束后会以 JSON 格式输出所有返回参数，适用于工作流绑定卡片或作为子工作流的场景。如果工作流直接绑定了智能体，对话中触发了工作流时，大模型会自动总结 JSON 格式的内容，并以自然语言回复用户。返回变量支持配置 String、Number、Object 等多种类型，其中 Object 类型的参数最多支持 3 层嵌套。

结束：工作流的出口，相当于一段程序中的最后一行代码，返回变量给工作流的调用方。结束节点支持两种返回方式，即返回变量和返回文本。

返回文本模式下，工作流运行结束后，智能体中的模型将直接使用指定的内容回复对话。回答内容中支持引用输出参数，也可以设置流式输出。具体说明如下：

设置	说明
输出变量	输出节点中输出的参数。为工作流绑定卡片时可以使用这些参数。
回答内容	工作流的最终输出内容，不可设置为空。支持引用输出参数，引用方式为{{变量名}}。

很明显，只有一个开始和一个结束节点是无法组成一个可执行的工作流的。接下来我们将继续学习工作流的常用节点。、

2.2 大模型节点¶

大模型节点可以调用大型语言模型，根据输入参数和提示词生成回复，通常用于执行文本生成任务，例如文案制作、文本总结、文章扩写等。

创建一个大模型节点：

在画布中点击“+”按钮，添加大模型节点：

选择模型：选择要使用的模型。此节点的输出内容质量很大程度上受模型能力的影响，建议根据实际业务场景选择模型。可选的模型范围取决于当前的账号类型，个人免费版或个人进阶版用户可以使用默认的几类模型，且存在对话数量限制，团队版或企业版套餐用户可以使用火山引擎方舟平台的模型。

设置模型的参数：

用于从多个维度调整不同模型在生成内容时的随机性。扣子提供以下预置的模式供你选择，每个模式的模型参数取值不同。
精确模式：模型的输出内容严格遵循指令要求，可能会反复讨论某个主题，或频繁出现相同词汇。
平衡模式：模型的输出内容更具随机性和准确性。
创意模式：模型的输出内容更具多样性和创新性，某些场景下可能会偏离主旨。
你也可以根据需求，展开高级设置，修改每个模式下的具体参数值。参数随机性，即 temperature，用于控制结果的随机性。
调高此参数值，会使模型的输出更具多样性和创新性。
降低此参数值，会使输出内容更加严格遵循指令要求。当该数值接近零时，模型将变得确定和重复。

在基于事实的问答场景，你可以使用较低的回复随机性数值，以获得更真实和简洁的答案，例如售后客服场景；在创造性的任务例如小说创作，你可以适当调高回复随机性数值。

最大长度：模型每次生成的内容长度受限于最大输出长度（max_token），过长的内容会被截断，试运行时大模型节点同时提示“输出内容因超出模型最大输出长度被截断。”

给大模型添加技能：

给大模型添加一个技能：头条搜索。大模型在执行任务时，可以自动的把我们输入的提示词的一部分，调用技能中的”头条搜索“进行联网检索。技能可以拓宽大模型的能力边界，但是也是因为这个调用是自动化的，所以我们不知道调用工具时到底检索了什么内容。
技能的本质实际上就是”插件“，插件是coze中非常核心且具有竞争力的功能，它可以完成各类工具的调用，我们在后续的内容中将详细介绍。

给大模型输入prompt：

输入：点击“+”，把开始节点的输入传过来作为大模型的输入
在prompt引入变量：使用 {{变量名}}的方式引入和使用变量，系统提示词和用户提示词都可以使用。
系统提示词：用于指定人设和回复风格。支持直接插入提示词库中的提示词模版、插入团队资源库下已创建的提示词，也可以自行编写提示词。

你是一个旅游规划助手，能够根据用户输入的内容规划行程，并根据互联网搜索结果给出可执行的方案。需要注意

1. 你的回复必须言简意赅，不要有太多的长篇大论
2. 请从每天的行程安排、天气和应对措施、主要景点、特色食物、民族特色等多个维度按天安排行程
3. 最后整理一个表格，按照吃、住、行等多个维度，计算2-4个人的人均支出

用户提示词：模型的用户提示词是用户在本轮对话中的输入，用于给模型下达最新的指令或问题。

{{input}}

指定输出：指定模型的输出格式，因为在结束的节点我们就直接输出了，所以这里我们使用markdown格式。
文本：纯文本格式。此时大模型节点只有一个输出参数，参数值为模型回复的文本内容。
Markdown：Markdown 格式。此时大模型节点只有一个输出参数，参数值为模型回复的文本内容。
JSON：标准 JSON 格式。你可以直接导入一段 JSON 样例，系统会根据样例格式自动设置输出参数的结构，也可以直接添加多个参数并设置参数类型。

设置输出节点：

一般来讲，对于输出的内容是对话类型的，设置返回文本格式；需要格式化的输出（比如返回JSON的），设置返回变量。最后，使用{{变量名}}的方式，把上一步的输出返回给调用方。如果生成内容比较多，可以勾选“流式输出”，这样模型则会边生成内容，边返回

2.3 试运行工作流¶

2.3.1 调试工作流¶

点击试运行工作流，并给开始节点的所有输入变量赋值后，再点击右侧下方的试运行按钮，即可完成调试。

点击试运行后，效果如下：

运行过程中，每个节点的执行结果都可以看到，方便我们进行调试。也会展示整体的执行时间，以及token的消耗数。可以看到，因为加入了头条搜索的功能，消费3750个token数，并不算少。

2.3.2 查看工作流执行日志¶

如果想看到更加细节的信息，比如将具体每个节点的执行时间，输入/输出的token数分别是多少等信息，可以查看日志。

如上图，在“旅游规划助手”这个LLM节点，我们看到它分了两个阶段，第二个节点右侧可以看到这里调用了插件，并返回了对应的结果。同时也看到了这个阶段消耗的token数，包括输入/输出的token数细节。
同样的，工作流在修改之后如果效果不如预期，可能会需要去查看之前的调用日志，可以在下拉框中选择历史的执行记录，去查看历史版本的执行结果。

点击右侧的按钮，跳转到了历史的执行记录中，可以看到：执行日志中不仅仅只是调用时的输入和返回值，还有当时的整个工作流节点的各类信息，比如当时的prompt是怎么写的。这对于工作流的调试起到非常重要的指导作用。

在实际工作中，往往一个工作流会复杂的多，学会调试工作流、查看日志，是coze应用开发的基本功。基本功的好与坏影响开发一个应用的时间，希望同学们认真对待。

2.4 其他常用节点¶

2.4.1 选择器节点¶

该节点是一个 if-else 节点，用于设计工作流内的分支流程。当向该节点输入参数时，节点会判断是否符合如果区域的条件，符合则执行如果对应的工作流分支，否则执行否则对应的工作流分支。

接下来，我们在这个demo中增加一个选择器节点，用来判断用户输如是否为空，如果为空直接结束不调用大模型。如果不为空则执行后续的逻辑。

2.4.2 意图识别节点¶

意图识别（Intent Recognition）指的是让智能体理解用户通过自然语言表达的意图或目的。意图识别是智能助手的典型能力，例如用户在对话中输入“我想查看今天的 AI 新闻”，其中“查看新闻”为用户意图，也就是用户希望智能体执行的操作。扣子工作流支持意图识别节点对用户意图进行归类，无需再通过大模型节点配合选择器节点实现意图识别，使工作流运行更加高效。

意图识别节点可用于以下场景：

客户服务：识别用户问题的类型，并转交各类知识库处理，对于知识库中未匹配的问题，转交人工客服处理。
医疗咨询：对用户咨询的医学问题进行归类，非医学问题的咨询则拒绝回复。
综合类智能体：对于功能多样的智能体，可以先由意图识别节点对用户咨询进行初步分类，转交各个 Agent 分支处理。

意图识别节点支持极速模式或完整模式运行。

极速模式：以较快的速度对用户意图进行分类，适用于关注工作流运行效率的场景。极速模式不支持设置系统提示词。
完整模式：意图识别效果优先，响应速度可能较长，适用于需要复杂逻辑判断的场景，例如剧情类游戏中根据情节发展切换剧情。完整模式往往需要选择意图识别能力较强的模型，并配合细致、严谨的提示词。

和选择器一样，意图识别节点也是一种分支选择节点，区别就是在于意图识别是基于大模型做场景分类，选择器是基于代码层面的逻辑判断。接下来，我们将结合意图识别、输入和输出节点，改造一下我们的旅游规划小助手。

2.4.3 输入和输出节点

输入节点：

在比较复杂的工作流场景中，某些节点的执行往往需要额外的用户输入。如果上游节点中没有获取到这些信息，你可以添加一个输入节点来主动收集信息。工作流执行到输入节点时会暂时中断，直到此节点收集到必要的用户输入。实际上，开始节点就是特殊的输入节点

输出节点：

通常情况下，工作流会在执行完毕后通过结束节点输出最终的执行结果。当工作流处理流程较长、运行时间较久时，开发者可以在工作流中添加输出节点，临时输出一段消息，避免用户等待时间过长、放弃对话。例如提示用户任务正在执行中，建议用户耐心等待。

改造小助手

接下来，结合意图识别、输入和输出节点，改造一下我们的旅游规划小助手。首先，增加一个意图识别节点：

把开始节点的input作为query，判断意图：
旅游规划：提示用户输入”城市“，然后把用户输入的城市作为旅游助手的输入。
其他意图：输出”本系统不支持闲聊“，然后退出

别忘了修改大模型中的变量：

编辑后，试运行模型：

输入：

帮我规划一个7天的自驾游

点击执行后，如下图：

输入：

成都

然后继续执行，结果如下：

到这里，说明了意图识别、分支判断等功能都正确无误得到了执行。（因大模型产生的内容具有随机性，所以同学们执行后这里的内容很可能和教案中有一些出入，只要是7天+成都，就说明流程是没有问题的）

2.4.3 代码节点¶

代码节点支持通过编写代码来生成返回值。扣子支持在代码节点内使用 IDE 工具，通过 AI 自动生成代码或编写自定义代码逻辑，来处理输入参数并返回响应结果。
代码节点支持 JavaScript 和 Python 两种语言。我们展开说一下python，官方介绍：

支持的模块包括 curses、dbm、ensurepip、fcntl、grp、idlelib、lib2to3、msvcrt、pwd、resource、syslog、termios、tkinter、turtle.py、turtledemo、venv、winreg、winsound、multiprocessing、threading、sockets、pty 和 tty。

在 Python 环境中，仅内置了两个第三方依赖库：requests_async 和 numpy。其中，requests_async 与 requests 类似，但在使用时需要搭配 await。

说明：

Python 运行时暂不支持 Http.client 方式的请求。

不支持使用除 requests_async 、numpy 以外的第三方依赖库。

time.sleep() 方法由于是阻塞调用，会对代码执行性能产生影响，因此推荐使用异步版本的 asyncio.sleep() 来替代。

示例如下：

import requests_async as requests

async def main(args: Args) -> Output:
    # args是调用这个节点传入的参数，通过args.params['url']这种方式获取。 通过requests方法，我们这里就可以通过代码实现一个服务接口的调用，从而实现复杂的逻辑。 
    url = args.params['url']
    response = await requests.get(url)
    ret = {
      'code': response.status_code,
      'res': response.text,
    }
    return ret

除此以外，还有一些常用的用法:

操作	说明
使用 AI 生成代码	你可以在 IDE 底部单击尝试 AI，并输入自然语言设定代码逻辑，AI 将自动生成代码。你也可以选中代码片段，通过快捷键（macOS 为 Command + I、Windows 为 Ctrl + I）唤起 AI，并输入自然语言让 AI 帮助你修改代码。
补全代码	如果你已经为代码节点配置好了输入参数，编辑时支持自动补全参数。

接下来，我们继续改造小助手，给它增加一个代码块组件，让小助手知道我们运行工作流时的当前时间。

具体代码如下：

接下来，我们再次试运行工作流，输入：

请帮我规划以下周末2天的自驾游行程

弹出后续输入框时，输入：

河北

中间过程略，最终输出可以看到，规划出来的行程是基于当前时间做出来的方案。

3 在工作流中使用插件¶

插件节点用于在工作流中调用插件运行指定工具。
插件是一系列工具的集合，每个工具都是一个可调用的 API。商店中的上架插件或已创建的个人或团队插件支持以节点形式被集成到工作流中，拓展智能体的能力边界。

接下来我们介绍一些常见的插件。

3.1 联网搜索插件¶

联网搜索插件包括头条、B站、懂车帝、百度、谷歌、豆瓣、微博、小红书等各种平台，具体使用哪个需要结合业务。

我们以头条搜索为例：

查看示例：

在search工具中输入上述内容，输出如下：

3.2 图片理解插件¶

图片理解插件可以实现图片到文字的转化，需要依赖两部分的输入：
图片
用户提示词

接下来我们使用一个案例帮助大家理解如何使用图片理解插件，首先，我们准备好一张图片：教案素材中的 01-编码器细节.jpg，然后搭建一个简单的工作流。如下图：

开始节点输入
img ：需要被理解的图片, image类型，支持常见的jpg、bmp、png等图片类型
prompt：用户提示词，str类型。就是用户要对图片问的问题

将输入部分的参数赋值给图片理解插件
text：接收str类型，输入用户的提示词
url：接收str图片地址。这里需要注意：如果是从输入节点上传过来的图片类型，这里会报红，但是可以正常执行、

接下来，我们执行一下流水线：

可以看到，输入的图片被转成了url，同时。在response_for_model字段中，返回了图片的内容，且内容是正确的。

3.3 链接读取插件¶

链接读取插件也是我们使用coze开发时常用的插件，不要被它的名称迷惑了，它实际上是一个”文件阅读器“而不是一个”链接阅读器“，它主要包含两个功能：
链接内容获取：当传入给插件的输入是一个html页面时，获取html页面中的文本内容
文档内容提取：当传入的内容是doc、pdf时，提取文档中的文本内容

所以，这个插件我们经常会用来处理用户上传的各类文档，效果还算可以。除此以外，还有一些其他官方或者非官方的类似功能的插件，但是毫无疑问，链接读取插件这个插件的使用量要多的多。同时，除非业务有特殊需求以及通过多个case验证这些插件，否则还是建议使用官方提供的”链接读取“插件，大量的调用量已经说明这个插件已经被证明可以用到生产中。

接下来，我们通过一个案例，让同学们理解这个插件如何使用。首先，我们先构建一个简单的流水线：

上传文件：素材 02-简历.docx，执行流水线。

查看日志，我们可以看到，在插件输出的字段中，pdf_content字段有内容，并且正确识别了素材文件中的文字，而其他字段都是空的。这是因为我们给的链接是docx的文件，而不是html。

如果我们传入的是一个html的网页，比如:http://www.baidu.com。那执行结果则会如下（修改流水线过程略）：可以看到，数据出现在了data字段中。

因此我们可以总结到一个规律：
如果给的docx、pdf文件地址，那么数据则会出现在pdf_content中
如果我们传入的是html页面地址，那么数据则会出现在data中。并且在error_code和error_msg字段中还会有调用报错信息。

记住以上规律，对使用这个插件开发一个支持文件、网页内容获取能力智能体很要。

3.4 其他插件¶

新闻资讯
头条新闻
天气预报
墨迹天气
出行必备
飞常准
猫途鹰
生活便利
快递查询助手，国内快递查询
食物大师
懂车帝
幸福里
猎聘

二、搭建一个完整的智能体¶

接下来，我们将结合 旅游规划工作流和文档内容读取工作流实现一个简单，但是功能完整的智能体，可以通过：

创建一个智能体
编写提示词
添加工作流
发布智能体

以上4个步骤完成。

1 创建一个智能体¶

输入智能体名称和功能介绍，然后单击图标旁边的生成图标，自动生成一个头像。

2 编写提示词¶

在左侧人设与回复逻辑面板中描述智能体的身份和任务。
在中间技能面板为智能体配置各种扩展能力。
在右侧预览与调试面板中，实时调试智能体。

提示词：

# 角色 
你是一个多功能机器人，能够根据用户输入的提示词选择使用不同的工作流完成对应的工作。


## 工作步骤 
- 如果用户上传了文档，则识别文档中的文本内容
- 如果用户输入的内容和旅行相关，则进行旅游规划

如下图：

在这里我们保持默认的“单Agent(自助规划模式)”不动，把工作流调用的选择权交给模型。

3 添加和发布工作流¶

在添加工作流之前，我们要修改工作流的名称和描述，以便大模型去选择调用哪个
旅游助手工作流改为：
文档内容读取工作流改为：
编辑完成后，还需要发布工作流。这里需要注意： 只有发布过的工作流才能被智能体使用。因为我们之前已经调试过了，所以在这里发布时，点击”坚持发布“即可，实际工作中，如果工作流没有试运行过，不建议抱有侥幸心理直接发布。这样会让BUG隐患带到智能体中，在实际生产中，我们建议尽量把风险前置，越早发现BUG，越早解决，这样最后整个工程的质量就越容易把控。

最后，我们把刚刚发布的两个工作流添加到编排内容中：

4 调试智能体¶

给智能体添加开场白和预置问题：

预览和调试：

试运行机器人：

可以看到，工作流被正常调用。输出正常

5 发布智能体¶

完成调试后，单击发布将智能体发布到各种渠道中，在终端应用中使用智能体。目前支持将智能体发布到飞书、微信、抖音、豆包等多个渠道中，你可以根据个人需求和业务场景选择合适的渠道。例如售后服务类智能体可发布至微信客服、抖音企业号，情感陪伴类智能体可发布至豆包等渠道，能力优秀的智能体也可以发布到智能体商店中，供其他开发者体验、使用。

在智能体的编排页面右上角，单击发布。
在发布页面输入发布记录，并选择发布渠道。
单击发布。

在这里我们只选择”扣子商店“这一种方法。API使用方法我们将在进阶课程中给大家讲解。其他方法比如抖音小程序、微信等因流程比较繁杂且和coze本身关系不大，感兴趣的同学们可以自行按照官方文档操作，实现一个智能体的编排。