Coze 智能体搭建教学文档

概述

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

---

目录

1. Coze 核心组件

   • 工作流（Workflow）
   • 数据库（Database）
   • 大模型节点（LLM Node）
   • 意图识别节点
   • SQL 节点
   • 提示词（Prompt）

2. 数据库设计

   • 表结构定义
   • 数据初始化
   • 示例：游戏场景数据库

3. 工作流设计

   • 工作流输入输出
   • 节点类型与配置
   • 参数传递与映射
   • 示例：简易对话智能体的工作流

4. 大模型节点配置

   • 系统提示词
   • 用户提示词
   • 技能配置
   • 示例：提示词设计

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

   • 场景描述
   • 数据库设计
   • 工作流设计
   • 提示词示例
   • 测试与调试

6. 进阶技巧

   • 模块化设计
   • 动态参数传递
   • 错误处理与默认分支

7. 结语

---

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 大模型节点：
  • 系统提示词：

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

  • 用户提示词：

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

  • 任务：

    1. 整合用户输入和 NPC 响应。
    2. 输出格式如下：
       user_input: [用户输入]
       npc_response: [NPC 响应]
    

5.5 测试与调试

• 输入：“与村民张三对话”
• 输出：

  你站在村庄广场，一个热闹的广场，村民们在此闲聊。村民张三一个热情的农夫，站在一边，村民李四一个安静的渔夫，拿着鱼竿。村民张三笑着对你说：‘你好啊，今天天气不错，适合种菜！’他看起来很热情。
  可执行动作：与村民李四对话
  

---

6. 进阶技巧

6.1 模块化设计

• 将智能体功能拆分为多个独立的工作流，每个工作流负责单一任务（如对话管理、UI 生成）。
• 优点：
  • 提高可维护性和复用性。
  • 便于调试和扩展。

6.2 动态参数传递

• 使用 {{变量名}} 动态引用参数，确保灵活性。
• 避免硬编码，确保工作流可泛化。
• 示例：
  • SQL 节点中使用 {{npc_name}} 动态查询 NPC 数据。

6.3 错误处理与默认分支

• 在意图识别节点中设置默认分支，处理未匹配的输入。
• 提供友好提示，引导用户输入有效命令。
• 示例：
  • 用户输入：“查看地图”
  • 默认分支输出：“当前功能暂不支持，请尝试与 NPC 对话。”

---

7. 结语

本文档详细介绍了 Coze 智能体的搭建流程，涵盖了数据库设计、工作流配置、大模型节点设置等关键步骤。通过简易对话智能体的示例，您可以快速掌握 Coze 的核心机制。建议在实践中不断调试和优化提示词，以提升智能体的表现。希望这份文档能帮助您和其他开发者顺利搭建 Coze 智能体！