Day04 Coze 智能体开发完整笔记

今日目标

1. 理解智能体的概念，能说清楚智能体能做什么，以及它和普通大模型聊天的区别。
2. 理解 Coze 平台的基本结构，知道空间、项目、资源库、工作流、插件、知识库、数据库分别解决什么问题。
3. 掌握工作流中常见节点的使用：开始节点、大模型节点、选择器节点、意图识别节点、输入节点、输出节点、结束节点。
4. 掌握工作流中插件的使用，能把联网搜索、图片理解、文档提取等能力接入到流程中。
5. 掌握智能体的基础搭建流程，能把已经发布的工作流配置成智能体工具，并完成预览调试。
6. 能通过运行日志定位常见问题，例如变量没传、输出选错、分支没连、工作流未发布、插件参数不匹配等。

一、智能体是什么

智能体可以先理解为一个“能自己办事的 AI 程序”。普通大模型聊天更像是“你问一句，它答一句”；智能体则更进一步，它可以围绕一个目标，自己判断下一步要做什么，需要查资料就查资料，需要调用工具就调用工具，需要整理结果就整理结果。

从结构上看，智能体通常可以拆成两部分：

1. 大模型：负责理解问题、分析目标、规划步骤、生成回答，可以理解为“大脑”。
2. 工具：负责执行具体动作，例如联网搜索、查天气、读取文档、识别图片、查询数据库，可以理解为“手和脚”。

所以一句话概括：智能体 = 大模型的思考能力 + 工具的执行能力。

大模型本身很强，但它有几个天然限制：它不知道实时新闻，不一定知道公司内部资料，不能自己打开网页操作，也不能直接读取你本地的文档。工具就是为了补足这些限制。比如学生问“今天深圳天气适合出门吗”，只靠模型记忆肯定不可靠，因为天气是实时变化的；如果智能体能调用天气插件，就可以先查数据，再组织回答。

智能体常见的组成模块包括：

1. 控制中心：决定当前任务应该走哪条路线。
2. 记忆模块：记录历史对话或用户偏好。
3. 规划模块：把一个大目标拆成几个小步骤。
4. 工具模块：调用搜索、文档提取、数据库、接口等外部能力。
5. 行动模块：把工具结果加工成用户能看懂的输出。

今日课程先不追求把每个模块都做复杂，而是先把“平台上如何搭一个能调用工具的智能体”跑通。

二、为什么要学 Coze

Coze 是一个低代码智能体开发平台。它的核心价值不是让我们少学技术，而是让我们用较低成本快速理解智能体产品的组成方式：模型、提示词、工具、工作流、插件、发布、调试，这些都是实际 AI 应用开发绕不开的概念。

学习 Coze 有三个直接好处：

1. 能快速做出可演示的 AI 应用。很多功能不需要从零写代码，拖拽节点、配置参数就能跑起来。
2. 能理解智能体开发的完整链路。即使以后公司不用 Coze，而是用 Dify、LangChain、FastAPI 自研，底层思路仍然类似。
3. 能训练产品化思维。一个 AI 功能不是“写一句提示词”就结束，而是要考虑输入、判断、工具调用、异常情况、输出格式、用户体验。

但是也要知道 Coze 的边界：云平台很方便，但定制程度有限；插件很多，但质量和稳定性需要测试；个人版通常会有积分、时长、发布范围等限制；涉及隐私数据时，不能随便把真实简历、合同、公司文件上传到公开平台。

可以把几种开发方式做一个类比：

1. Coze 这类云平台：像去饭店点菜，最快，适合入门和演示。
2. Dify 这类可私有化平台：像买半成品回家加工，比云平台更可控。
3. 代码自研：像自己买菜做饭，成本高，但最灵活，企业真实项目经常会走到这一步。

三、Coze 平台中的核心概念

1. 空间

空间可以理解为一个业务隔离区。企业里可能有金融业务、汽车业务、教育业务，不同业务的数据、插件、知识库最好相互隔离，避免混用。个人版可能只能使用一个空间，但企业版通常会更强调空间隔离。

正确理解：空间用于隔离不同业务资源。

错误理解：空间只是一个普通文件夹，随便放什么都一样。

2. 项目

项目位于空间之下，用来组织具体智能体、应用和相关资源。可以把项目理解为“这次我们要做的一组 AI 功能”。比如一个“求职助手项目”里，可以包含简历分析智能体、面试题生成智能体、岗位匹配工作流等。

正确理解：项目是围绕某个业务目标组织资源的地方。

错误理解：项目只是页面上的一个名字，对后续开发没有影响。

3. 资源库

资源库是 Coze 中非常重要的概念。它像一个共享工具箱，里面可以放插件、知识库、数据库、提示词、工作流、记忆库等。智能体要使用某个工作流或插件，通常要先在资源库中创建、配置、发布，然后再被智能体引用。

常见资源包括：

1. 插件：别人或平台封装好的工具，例如联网搜索、天气查询、图片理解、文档提取。
2. 知识库：用于存放文档、书籍、说明书等文本资料，帮助模型减少幻觉，补充专业知识。
3. 数据库：用于存放业务数据，例如订单、商品、客户信息。
4. 提示词：可复用的提示模板。
5. 工作流：按照固定流程完成任务的节点编排。

正确理解：资源库里的内容要服务于智能体能力建设。

错误理解：资源库就是资料仓库，只要上传越多越好。资源必须可控、可解释、可维护。

四、工作流是什么

工作流可以理解为一条“任务流水线”。用户输入一个问题后，数据会从开始节点进入，按照连线经过不同节点，最后到达结束节点输出结果。

工作流的关键特点是：有方向、按步骤、可分支、可调试。

在 Coze 中，工作流通常是一个 DAG，也就是有向无环图：

1. 有向：数据从前往后流动，节点之间有明确顺序。
2. 无环：不能自己绕回自己，否则流程会陷入死循环。
3. 图结构：可以有多个节点，也可以有分支。

一个最简单的工作流通常包含：

1. 开始节点：接收用户输入。
2. 中间节点：处理任务，例如调用大模型或插件。
3. 结束节点：决定最终输出什么给用户。

创建工作流时要注意命名和描述。名称要见名知意，描述要说明它能解决什么问题，因为后面智能体调用工作流时，会根据工具描述判断什么时候使用它。

正确命名示例：

1. travel_plan_workflow：用于根据用户需求生成旅游规划。
2. doc_extract_workflow：用于读取文档并提取关键信息。
3. weather_query_workflow：用于根据城市查询天气信息。

不推荐命名：

1. test
2. demo
3. aaa
4. second

这些名字自己当时能看懂，过几天就会忘，智能体也不容易根据描述准确调用。

五、常见节点详解

1. 开始节点

开始节点是工作流的数据入口。常见输入变量是 input，表示用户传进来的问题或需求。

如果任务只处理文本，输入类型通常是字符串。如果任务要处理图片或文档，就要把输入类型改成对应的文件类型，例如 image、doc、pdf 等。

易错点：

1. 错误：处理图片时仍然把输入当字符串。
2. 正确：图片理解类任务要把输入类型改成图片文件，并把图片变量传给图片理解插件。

2. 大模型节点

大模型节点负责理解、判断、生成文本。它可以单独回答问题，也可以对插件结果进行总结加工。

大模型节点通常要配置：

1. 模型：选择使用哪个模型。
2. 系统提示词：告诉模型身份、任务、规则、输出格式。
3. 用户提示词：传入用户输入或上游节点结果。
4. 变量：把前面节点产生的数据传进来，例如 {{input}}、{{city}}。
5. 输出字段：选择最终要用的结果，通常选模型的正式回答，不要误选推理过程字段。

易错点：

1. 错误：变量在左侧添加了，但提示词里没有引用，模型感知不到。
2. 正确：变量要传入节点，还要在提示词里通过 {{变量名}} 使用。
3. 错误：结束节点选择了 reasoning_content，导致输出一堆推理过程或异常内容。
4. 正确：结束节点一般选择模型的正式输出字段，例如 output。

3. 选择器节点

选择器节点类似 Python 中的 if / else。它适合处理明确条件，比如“输入是否为空”“城市是否已填写”“分数是否大于 60”。

适合用选择器的情况：

1. 用户输入为空，直接提示重新输入。
2. 用户没有上传文件，提示上传文件。
3. 某个插件返回失败，走兜底提示。

不适合用选择器的情况：

1. 判断用户到底是想旅游规划、闲聊还是查资料。
2. 判断一段话的语义类别。

这些语义判断更适合用意图识别节点。

4. 意图识别节点

意图识别节点本质上是让模型做分类。它不是简单判断“等于某个字符串”，而是理解用户这句话属于哪类需求。

例如用户说：

1. “帮我安排一个三天两晚的杭州旅游”
2. “我想去西安玩，有没有路线”
3. “端午节去长沙怎么安排”

这几句话表面文字不同，但意图都可以归为“旅游规划”。

意图识别节点常见输出是分类编号或分类名称，例如 classification_id。它适合用于后续分支判断，但不要把它当成用户原始问题传给大模型。

易错点：

1. 错误：把 classification_id 传给后面大模型，让模型围绕“1”或“2”生成内容。
2. 正确：classification_id 只负责决定走哪条分支；真正给模型生成答案时，仍然传用户原始输入。

5. 输入节点

输入节点用于在工作流中途向用户补充收集信息。比如用户说“帮我规划旅游”，但没说目的地，这时工作流可以暂停一下，追问“你想去哪个城市？”

输入节点适合解决信息不完整的问题。

例如旅游规划需要：

1. 出发地
2. 目的地
3. 天数
4. 预算
5. 偏好

第一节课不要一次做太复杂，可以先只补一个关键字段，例如目的地城市。

易错点：

1. 错误：新增输入变量仍然叫 input，和原始输入冲突。
2. 正确：新变量命名为 city、days、budget 等清晰名称。
3. 错误：输入节点收集了 city，但后面大模型节点没有添加 city 变量。
4. 正确：输入节点收集到的信息，要继续传给后续节点，并在提示词中引用。

6. 输出节点与结束节点

输出节点和结束节点负责把结果交给用户。最终输出要尽量清晰，不要把中间调试信息、插件原始 JSON、模型推理过程直接丢给用户。

好的输出应该具备：

1. 结构清楚。
2. 语言自然。
3. 和用户问题直接相关。
4. 必要时说明数据来源或限制。

如果插件返回的是一大段搜索结果，通常不要直接输出原始结果，而是先交给大模型整理成“摘要、建议、注意事项”。

六、插件是什么

插件可以理解为别人写好的函数或 API，我们在 Coze 里直接拖进工作流使用。插件能扩展智能体能力，让它从“只能聊天”变成“能查、能读、能识别、能处理”。

插件来源可以分为：

1. 官方插件：平台官方提供。
2. 自建插件：自己或团队创建。
3. 第三方插件：其他个人或机构提供。

选择插件时要注意匹配场景。比如懂车帝插件适合车辆信息，天气插件适合天气查询，文档提取插件适合读取文档，不要拿一个不相关插件硬做任务。

有些插件需要 API Key。API Key 可以理解为调用某个平台服务的身份凭证。使用这类插件前，通常要去对应官网注册账号、开通服务、复制 Key，再填到插件配置里。

1. 联网搜索插件

联网搜索插件适合处理实时信息或模型不确定的信息，例如新闻、政策、天气、近期活动、某个网站页面内容等。

基本流程：

1. 添加搜索插件节点。
2. 找到必填参数，例如搜索关键词 input query。
3. 把开始节点的用户输入传给搜索关键词。
4. 配置数量限制，例如返回 5 条结果。
5. 运行测试，查看返回字段。
6. 把搜索结果交给大模型整理，或直接在结束节点输出需要的字段。

易错点：

1. 错误：不知道插件输出选哪个字段，随便选一个后就不测试。
2. 正确：先查看示例，再试运行，看日志中的真实返回结构，确认哪个字段是需要的内容。

2. 图片理解插件

图片理解插件用于识别图片内容。常见场景包括商品图识别、截图信息提取、海报分析、票据识别等。

基本流程：

1. 开始节点增加图片输入变量，例如 image。
2. 输入类型改成图片文件。
3. 增加提示词变量，例如 prompt，说明希望模型分析什么。
4. 插件节点接收图片和提示词。
5. 输出选择插件的文本描述结果。

要注意：有些图片插件可能效果不稳定，或者参数要求不同。如果一个插件不好用，可以换同类插件，也可以直接用支持多模态的大模型节点处理图片。

3. 文档提取插件

文档提取插件用于读取 PDF、Word、简历、说明书等文件，把文档内容转换成文本。转换成文本之后，模型才能进一步总结、提取、打分、改写。

常见工作场景：

1. 简历解析：提取姓名、学历、项目、技能。
2. 合同摘要：提取甲方、乙方、金额、时间、风险条款。
3. 课程资料整理：提取文档重点，生成讲义或题目。

基本流程：

1. 开始节点创建文件输入变量，例如 doc_file。
2. 类型选择文档或文件。
3. 插件节点接收该文件变量。
4. 查看插件输出字段，选择文档正文内容字段。
5. 交给大模型进一步整理。

安全提醒：真实工作中不要随便把用户隐私、公司合同、内部数据上传到公开平台。演示时可以使用脱敏样例。

七、第一个工作流建议：旅游规划

旅游规划是适合入门的案例，因为它包含用户输入、联网搜索、大模型整理、结果输出，流程完整但不太难。

基础版本流程：

1. 开始节点接收用户输入。
2. 大模型节点理解用户需求。
3. 联网搜索插件查询目的地信息。
4. 大模型节点整理路线、交通、美食、注意事项。
5. 结束节点输出规划结果。

升级版本可以加入：

1. 选择器节点：判断用户是否输入为空。
2. 意图识别节点：判断用户是旅游规划还是闲聊。
3. 输入节点：用户没说目的地时，补问目的地。
4. 输出格式约束：按“行程安排、推荐理由、注意事项”输出。

课堂上建议先跑通基础版本，再逐步增加节点。每加一个节点都要测试一次，不要等全部搭完再测试，否则错误定位会很痛苦。

八、第一个智能体搭建流程

工作流像一个工具，智能体像一个会选择工具的人。一个智能体可以挂载多个工作流，例如旅游规划、文档读取、天气查询、图片识别。

搭建步骤：

1. 创建智能体，选择单 Agent 模式。
2. 设置名称和简介，名称要让用户知道它能干什么。
3. 编写人设与任务说明，让智能体知道自己的职责。
4. 添加工具，把已经发布的工作流加入智能体。
5. 配置开场白和预设问题。
6. 预览调试，分别测试每个工具是否能被正确调用。
7. 根据测试结果修改提示词、工具描述或工作流节点。
8. 确认稳定后发布。

重点提醒：工作流必须先发布，智能体才能正常调用。如果工作流没有发布，在智能体工具列表中可能找不到，或者调用不到最新版本。

九、调试时重点看什么

Coze 的运行日志非常重要。不要只看最后回答对不对，还要看每个节点到底拿到了什么输入、输出了什么结果、耗时多久、有没有调用插件。

调试时依次检查：

1. 用户输入有没有进入开始节点。
2. 变量有没有传到下一个节点。
3. 分支有没有走到预期路线。
4. 插件必填参数有没有填。
5. 插件输出字段有没有选对。
6. 大模型提示词有没有引用变量。
7. 结束节点有没有输出正确字段。
8. 工作流是否保存并发布。

常见问题对照：

1. 页面出现变量缺失：检查变量有没有添加、有没有连线、有没有在提示词里引用。
2. 输出为空：检查结束节点选择的字段是否正确。
3. 智能体不用某个工具：检查工具名称、工具描述、工作流是否发布。
4. 运行很慢或超时：减少插件数量，简化提示词，换更快的模型，拆分过长流程。
5. 分支判断不准：明确选择器条件，语义分类任务改用意图识别。

十、和 AI 工作的关系

今天的 Coze 课不是为了记住某个按钮在哪里，而是为了理解 AI 应用开发的骨架。

真实工作里，常见需求可能是：

1. 做一个求职助手：读取简历，提取技能，匹配岗位，生成面试题。
2. 做一个企业客服：识别用户意图，查询知识库，必要时转人工。
3. 做一个数据问答助手：识别问题，查询数据库，生成图表或解释。
4. 做一个课程助教：读取课程资料，生成讲义、作业、答疑内容。

这些项目看起来不同，但底层都离不开同一条链路：

用户输入 -> 智能体理解目标 -> 判断意图 -> 调用工具或知识 -> 整理结果 -> 输出给用户。

学会 Coze 的意义，就是先把这条链路看明白、跑通、调试会。以后换成 Dify、LangChain、FastAPI 或公司自研框架，技术形式会变，但这条思路不会变。

十一、今日易错点汇总

1. 智能体不是普通聊天机器人。普通聊天机器人主要回答问题，智能体还要能规划、调用工具、执行任务。
2. 插件不是提示词。提示词负责告诉模型怎么想，插件负责让模型能做更多外部动作。
3. 工作流不是智能体。工作流是工具或流程，智能体可以调用一个或多个工作流完成任务。
4. 选择器节点不是意图识别节点。选择器适合明确条件，意图识别适合语义分类。
5. classification_id 不是用户问题。它用于分支判断，不要直接传给大模型生成答案。
6. 输入节点新增变量后，后续节点必须接收并引用该变量，否则补充输入没有效果。
7. 工作流未发布时，智能体通常无法正常调用它。
8. 插件输出字段不能靠猜，要看示例、看运行日志、做测试。
9. 文件和图片上传到云平台要注意隐私，课堂演示要使用脱敏资料。
10. 命名不能随意。工具名称和描述越清楚，智能体越容易正确调用。