Coze 智能体搭建教学文档

概述

Coze 是一个强大的智能体开发平台，允许开发者通过工作流（Workflow）、数据库、大模型（LLM）等组件构建复杂的智能体。本文档将详细介绍如何在 Coze 上搭建智能体，涵盖从数据库设计、工作流配置到提示词编写等核心流程，并通过示例帮助您理解如何协调各个模块以实现智能体的功能。文档力求详尽，包含大量示例和流程配合说明，适合初学者和需要深入理解 Coze 的开发者。

Coze 核心组件
- 工作流（Workflow）
- 数据库（Database）
- 大模型节点（LLM Node）
- 意图识别节点
- SQL 节点
- 提示词（Prompt）
数据库设计
- 表结构定义
- 数据初始化
- 示例：游戏场景数据库
工作流设计
- 工作流输入输出
- 节点类型与配置
- 参数传递与映射
- 示例：简易对话智能体的工作流
大模型节点配置
- 系统提示词
- 用户提示词
- 技能配置
- 示例：提示词设计
完整示例：简易对话智能体
- 场景描述
- 数据库设计
- 工作流设计
- 提示词示例
- 测试与调试
进阶技巧
- 模块化设计
- 动态参数传递
- 错误处理与默认分支
结语

1. Coze 核心组件

1.1 工作流（Workflow）

定义：工作流是智能体的“骨架”，由多个节点按顺序或条件连接，控制数据流向和执行逻辑。
作用：定义智能体的整体执行流程，例如从用户输入到最终输出的完整路径。
示例流程：
1. 用户输入 → 意图识别 → 查询数据库 → 生成响应 → 输出。
注意事项：
- 工作流需要清晰的输入和输出定义。
- 节点之间需要通过参数传递数据。

1.2 数据库（Database）

作用：存储智能体所需的数据，如用户状态、NPC 信息、地点描述等。
设计原则：
- 表名和字段名全小写，使用下划线分隔（如 player_status）。
- 主键字段避免使用 id（系统保留），建议使用明确名称（如 player_id）。
支持操作：
- 查询（SELECT）
- 插入（INSERT）
- 更新（UPDATE）

1.3 大模型节点（LLM Node）

功能：执行自然语言处理任务，如生成文本、分析意图等。
配置：
- 系统提示词：定义大模型的行为和角色。
- 用户提示词：提供具体输入数据，引导大模型生成响应。
- 技能：允许大模型调用其他工作流（仅在提示词明确要求时配置）。
输出：纯文本字符串。

1.4 意图识别节点

功能：分析用户输入，匹配预定义的意图。
输入：固定为 query（字符串），通常来源于开始节点的输入参数。
输出：根据配置项的分支，决定后续执行路径。
示例：
- 输入：“与村民张三对话”
- 输出分支：跳转到与张三对话的工作流。

1.5 SQL 节点

功能：执行数据库查询或更新操作。
配置：
- SQL 语句：支持 SELECT、INSERT、UPDATE 等。
- 数据表：指定操作的表，一个 SQL 节点只能配置一个表。
- 输出：
  - outputList：查询结果（数组）。
  - rowNum：受影响行数（整数）。
示例：
- SQL 语句：SELECT dialogue FROM npcs WHERE name = {{npc_name}}
- 输出：outputList 中包含 NPC 的对话内容。

1.6 提示词（Prompt）

系统提示词：

作用：定义大模型的角色和行为规范。

示例：

你是一个农场冒险游戏的主控助手，使用中文协调逻辑。输出格式参考以下示例：
user_input: 用户输入内容
npc_response: NPC 响应内容

用户提示词：
- 作用：提供具体输入数据，引导大模型生成响应。
- 格式：使用 {{变量名}} 引用参数。
- 示例：
```
用户输入：{{user_input}}\nNPC 响应：{{npc_response}}
```
注意事项：
- 提示词应清晰、具体，避免歧义。
- 系统提示词和用户提示词需配合使用，确保大模型理解任务。

2. 数据库设计

2.1 表结构定义

命名规则：
- 表名：全小写，使用下划线分隔（如 player_status）。
- 字段名：全小写，使用下划线分隔。
- 主键字段：避免使用 id，建议使用明确名称（如 player_id）。

示例：

locations 表：
- location_id（整数，主键）
- name（字符串）
- description（文本）

npcs 表：
- npc_id（整数，主键）
- name（字符串）
- description（文本）
- location_id（整数，关联 locations.location_id）
- dialogue（文本）

2.2 数据初始化

手动创建表：
- 在 Coze 数据库管理中手动创建表。
插入初始数据：
- 通过 SQL 节点或手动插入，确保智能体启动时有数据可用。
示例数据：
- locations 表：
  - location_id: 1, name: "村庄广场", description: "一个热闹的广场，村民们在此闲聊。"
- npcs 表：
  - npc_id: 1, name: "村民张三", description: "一个热情的农夫，喜欢分享故事。", location_id: 1, dialogue: "你好啊，今天天气不错，适合种菜！"
  - npc_id: 2, name: "村民李四", description: "一个安静的渔夫，总是带着鱼竿。", location_id: 1, dialogue: "广场边的河里鱼儿不少，想试试钓鱼吗？"

3. 工作流设计

3.1 工作流输入输出

开始节点：
- 定义工作流的输入参数，参数名需明确。
- 示例：user_input（用户输入的字符串）。
结束节点：
- 定义工作流的输出参数，指定来源（如大模型节点的输出）。
- 示例：game_output（最终输出内容）。

3.2 节点类型与配置

意图识别节点：
- 输入：query（来源：开始节点的输入参数）。
- 配置项：定义意图标签。
- 输出分支：根据意图跳转不同工作流。
- 示例：
  - 配置项："与村民张三对话" → 分支 1
  - 配置项："与村民李四对话" → 分支 2
SQL 节点：
- 输入：可引用 {{变量名}}。
- SQL：编写查询或更新语句。
- 输出：outputList 或 rowNum。
- 示例：
  - SQL 语句：SELECT dialogue FROM npcs WHERE name = {{npc_name}}
  - 输出：outputList 中包含 NPC 的对话内容。
大模型节点：
- 输入参数：明确定义并注明来源。
- 系统提示词：定义角色和行为。
- 用户提示词：使用 {{变量名}} 引用输入。
- 任务：描述大模型需要完成的具体任务。
- 输出：纯文本字符串。

3.3 参数传递与映射

工作流内部：
- 节点之间通过参数传递数据，需明确来源。
- 示例：意图识别节点的输出 → SQL 节点的输入。
工作流之间：
- 通过连接映射传递参数，如 main_game.game_output → ui_manager.ui_input。
- 注意：映射在外部定义，保持模块独立性。

4. 大模型节点配置

4.1 系统提示词

作用：定义大模型的角色和行为规范。

示例：

你是一个农场冒险游戏的主控助手，使用中文协调逻辑。输出格式参考以下示例：
user_input: 用户输入内容
npc_response: NPC 响应内容

4.2 用户提示词

作用：提供具体输入数据，引导大模型生成响应。

示例：

用户输入：{{user_input}}\nNPC 响应：{{npc_response}}

4.3 技能配置

何时配置：仅当提示词要求大模型主动调用其他工作流时。
示例：
- 提示词中包含“调用工作流 X 获取数据”，则配置技能 X。
注意：
- 如果工作流通过节点串联执行，大模型节点无需配置技能。

5. 完整示例：简易对话智能体

5.1 场景描述

地点：固定为“村庄广场”。
NPC：2 个固定的 NPC（村民张三和村民李四）。
功能：用户可以选择与某个 NPC 对话，智能体会返回对话内容和当前画面。

5.2 数据库设计

locations 表：
- location_id: 1
- name: "村庄广场"
- description: "一个热闹的广场，村民们在此闲聊。"
npcs 表：
- npc_id: 1, name: "村民张三", description: "一个热情的农夫，喜欢分享故事。", location_id: 1, dialogue: "你好啊，今天天气不错，适合种菜！"
- npc_id: 2, name: "村民李四", description: "一个安静的渔夫，总是带着鱼竿。", location_id: 1, dialogue: "广场边的河里鱼儿不少，想试试钓鱼吗？"

5.3 工作流设计

main_game：
- 输入：user_input
- 输出：game_output
- 节点：
  - 意图识别节点：基于 user_input 判断对话目标。
  - 大模型节点：整合 user_input 和 npc_response。
npc_manager：
- 输入：npc_name
- 输出：dialogue_output
- 节点：
  - SQL 节点：查询 NPC 数据。
  - 大模型节点：生成对话响应。
ui_manager：
- 输入：ui_input
- 输出：ui_output
- 节点：
  - SQL 节点：查询地点和 NPC 数据。
  - 大模型节点：生成 UI 画面。

5.4 提示词示例

main_game 大模型节点：