AI 智能体入门：基于 Coze 平台的构建指南

Coze 有两个版本，一个国内版，一个海外版；访问限制、支持的大模型、官方插件、更新速度有所不同。

主页功能概览：

• 扣子编程：查看、创建个人项目、资源库、任务中心、API 等。新版本还可以通过大模型对话，直接生成网页、移动应用、小程序、智能体等。
• 自定义 - 低代码模式：支持智能体开发、工作流开发。
• 个人空间：管理所有项目和智能体，可切换不同工作空间，适合团队协作。
• 项目开发：当前页面，集中管理所有开发中的项目（智能体/应用）。
• 资源库：存储/管理知识库、工作流、提示词模板等开发资源。
• 任务中心：查看后台任务进度，如文档向量化、工作流执行。
• 空间配置：设置空间权限、成员管理、自定义域名等高级配置。
• API 管理：生成 API 密钥，用于将智能体集成到外部系统。
• 文档中心：官方开发文档和教程。

智能体体验

目前已有许多智能体可供参考，建议开发者多浏览智能体推荐以获取灵感。

自定义 Bot 搭建

自己如何搭建一个功能强大的机器人？ Coze 中的智能体被称为 Bot。

进入智能体创建页面，映入眼帘的是人设与回复逻辑、编排、预览调试。

选择模式：Coze 扣子平台，智能体的三种核心模式：

1. 单 Agent 自主规划模式：由单个大模型自主思考、决策和执行，不需要预设固定流程。
2. 单 Agent 对话流模式：按照在工作流中编排的固定流程执行，支持多轮历史对话记录。
3. 多 Agents：一个智能体中设置多个子 Agent，每个 Agent 负责不同子任务，通过协作完成复杂逻辑。主 Agent 会将复杂任务拆解，分配给不同的子 Agent 处理，最后汇总结果，企业多选择。

人设与回复逻辑：这是定义智能体灵魂的地方，通过编写 Prompt 来设定它的角色、语气、技能和回复规则，支持 Markdown 格式和变量插槽，让交互更灵活。

编排（核心配置区）：为智能体赋予能力的地方，主要包括：

• 模型设置：选择底层大模型，当前是豆包・1.8・深度思考，也可切换其他主流模型。
• 技能（插件）：调用平台提供的 60+ 插件，拓展能力，如代码生成、天气查询等。
• 工作流：通过可视化拖拽，构建复杂的任务执行流程。
• 知识：接入扣子知识库，让智能体掌握专业知识。
• 记忆：定义变量，可在对话中动态使用变量。
• 长期记忆：开启后，智能体能总结历史对话，用于后续更精准的响应。

预览与调试：实时测试你的智能体，输入问题后查看它的回复和执行日志。

发布：点击右上角的发布按钮，可将智能体部署到微信、飞书、抖音等多平台。

MyAgent 示例

经过上述配置，可以定义一个基本的 Agent 智能体。什么都不做，直接与其沟通，发现它就是一个基本的沟通大模型，基于豆包模型。为了更好的体验通常需要给其置顶对应的规则（提示词、技能、知识库等）。

例如设置提示词：

你叫 WSM，你是一个动漫爱好者; 会给人推荐最近新的动漫，根据动漫分析故事剧情，推荐同类型的动漫等等 

Prompt 提示词工程

什么是提示词？ 提示词（Prompt）是与 AI 沟通的说明书，是开发者赋予 Bot 的身份、能力和行为规范，直接决定了 Bot 的响应质量和风格。它帮助用户控制语言模型的输出，生成符合特定需求的结果，是搭建智能体的第一步。

设计提示词 4 个关键要素：

1. 角色定位：明确 Bot 的身份，角色越具体，回复越专业。
   • ❌ 示例：你是一个助手，什么都懂一点，随便聊聊
   • ✅ 示例：你是一位有 15 年经验职场 HR，擅长处理敏感的人际关系问题，性格温和、专业、善于共情
2. 技能描述：清晰定义 Bot 的目标，让它知道做什么。
3. 输出格式：结构化回复要求，让 Bot 知道怎么做。例如按以下格式输出，情况分析 50 字，回复建议 3 条，每条 30 字，完整范文 150 字。
4. 约束条件：为 Bot 设置行为边界，确保安全合规，避免敏感话题（政治、宗教、冒犯性语言等）。

Coze 提示词分类

Coze 中设置提示词的三种方法：

1. 使用提示词模版：Coze 提供多套场景化模版，可直接使用或参考修改。
2. AI 自动生成：通过自然语言描述需求，大语言模型会自动生成或优化提示词。
3. 直接编写：根据业务需求手动编写，提示词越清晰明确，智能体的回复越符合预期。

Coze 提示词对比

Coze 支持对多种提示词进行对比开发，更方便的比对选择提示词，开发定义智能体。

高情商回复 Agent 案例

为了更方便地感受到定义一个智能体来体验吧！

• 角色锚定精准：避免了 AI 泛泛而谈建议，确保输出都围绕高情商展开。
• 技能拆解颗粒度适中：拆解为语气、内容、关系三个可量化维度。
• 输出格式标准化：明确要求以【开场寒暄】【表达理解与感谢】等五个固定板块输出。
• 限制条件清晰：直击职场拒绝痛点，有效防止 AI 生成生硬、啰嗦或引发二次矛盾回复。

# 角色 你是一位经验丰富的沟通专家，拥有 10 年职场历练，在各类职场场景中都能游刃有余。尤其擅长撰写高情商、得体且有效的沟通文本，在拒绝请求时，能巧妙地平衡关系与边界。

## 技能
### 技能 1: 语气把控
1. 以积极、友好的话语作为开头，营造融洽氛围。
2. 表达观点时，以'我'为主语阐述自身限制。
3. 杜绝使用指责性、命令式的语言。

### 技能 2: 内容构建
1. 率先表达对对方请求的理解以及诚挚的感谢。
2. 清晰、明确地说明自身存在的限制。
3. 根据实际情况，提供切实可行的替代方案或合理建议。
4. 以开放的态度，展望未来合作的可能性。

### 技能 3: 关系维护
1. 适时、恰当地表达歉意。
2. 真诚肯定对方工作的价值与贡献。
3. 始终保持专业且友善的态度。

## 输出格式
【开场寒暄】用积极友好的语言开启交流。
【表达理解与感谢】清晰传达对对方的理解与感激。
【委婉说明限制】明确阐述自身的限制条件。
【提供替代方案】给出具体的替代办法或建议。
【结尾祝福】以积极的话语结束对话，表达美好祝愿。

## 限制
- 避免使用'不''拒绝'等直接的负面词汇。
- 不可过度承诺或给予虚假安慰。
- 不贬低对方请求的合理性。
- 不过多解释个人情况。

如此可以看到 AI 已经根据定义提示词规则来输出回答我们的问题，这就是提示词作用。

RAG 知识库

为什么需要知识库？ 大模型存在幻觉问题。大模型的本质是根据文字概率猜下一句话，不是真的懂知识、记事实。所谓幻觉就是没见过的信息瞎编，记不清的内容乱凑，问专业/私有数据，大模型则会一本正经胡说八道。

什么是知识库？ RAG = Retrieval-Augmented Generation 检索增强生成，给大模型配一本标准答案参考书。把真实文档（合同、制度、手册、资料、FAQ、行业知识等）存进知识库；用户提问时，系统先从知识库里检索相关内容，大模型只基于这些真实内容回答，不许自己瞎编。用外部真实知识，管住大模型的幻觉，让回答准确、可控、可更新。

具体价值：使大模型不幻觉（只说知识库有的事实）、用私有知识（企业内部资料、个人资料、未公开信息）、随时更新（改文档就行，不用重训大模型）、可追溯（回答从哪段来的，能查到来源）。

之前没有 RAG：直接将用户的问题 query，送入 LLM 大模型，得到结果。

配置 RAG：

1. 将用户的问题 query，先和知识库做相关性检索，检索出和问题相关的 Context 上下文。
2. 再将 query 和 Context 融合拼接得到一个完整的结果 result。
3. 将第二步融合结果 result 送入大模型得到最后的结果。

构建知识库

Coze 支持知识库——构建文档类型：

文档预处理建议：清理无关内容（广告、水印、冗余信息），按主题分类整理。文件命名规范包含关键信息。

文档切片

长文档无法直接送入大模型，需要先进行切片（切分）。切片目的是适应大模型的上下文长度限制，提升检索的精度和效率。切分方式按字符数（每 300 字一段）、符号、语义结构进行切分。最佳实践是按符号 + 字符长度混合切分，每段控制在 200-500 字。

文档向量化

向量化是将文本转换为高维空间中的数字向量（数组），核心作用是计算语义相似度。让机器理解文本的深层含义，快速找到与用户问题最相关的文档片段，在向量数据库中高效匹配，提升响应速度。

Coze 构建知识库

选择资源库：右上角 + 资源新建资源库，选择知识库。上传后等待处理，系统自动完成「文本提取→切分→向量化」，大文件需耐心等待几分钟。

文档创建设置：文档解析策略、分段策略直接影响后续检索的精度和效率。

文档解析策略：

• 精准解析：从文档中提取图片、表格、公式等所有元素，信息完整，处理耗时更长。适用于包含重要图表、表格的文档。
• 快速解析：仅提取纯文本，忽略图片、表格等非文本元素，处理速度快。适用于纯文本类文档。

分段策略：

• 自动分段与清洗：系统自动按语义、段落、换行符等规则切分，并自动去重、去噪。
• 按层级分段：按照文档的层级结构（如标题 1、标题 2、标题 3）切分，转化树状结构。
• 自定义：手动设置分段规则（如按字符数、分隔符）、分段长度及预处理规则。

Coze 支持多类型知识导入：

Function Call

Function Calling 是让大模型具备调用外部工具的能力，打破大模型仅能基于训练数据生成内容的限制，让 AI 能实时获取外部信息，解决大模型的三大痛点：

工作原理：Function Calling 的核心是先判断、再调用、后生成。

1. 用户请求：用户向 AI 发送问题（今天北京天气怎么样？），同时提供可调用的函数列表（如 get_weather(location)）。
2. 模型判断：大模型分析问题，判断是否需要调用函数，还是直接生成文本回答。
3. 执行函数：如果需要调用函数，AI 生成函数调用指令，由服务端执行函数（如调用天气 API）。
4. 生成回答：大模型结合函数返回的结果，生成连贯、准确的自然语言回答。

Coze 中的 Function Call

在 Coze 平台中，插件就是 Function Calling 的实现形式。无需编写代码，即可让智能体调用外部工具。插件是一个工具集，包含一个或多个工具，每个工具对应可调用 API（如天气查询、代码生成、数据分析）。

核心机制：大模型通过阅读「插件描述」，自动判断是否需要调用该插件。

旅行助手 Agent 案例

创建一个普通的旅行助手 Demo1.0，可以看到普通大模型对于天气数据没办法精确获取。所以需要引入插件的作用。

创建一个 Coze 插件的旅行助手 Demo2.0。

Prompt 提示词：在提示词中出现 {指定要使用插件} 并规定了最终要输出的格式。使用的插件有：联网问答 search_url、高德地图 Search_around、墨迹天气 DayWeather、简易计算器 calculate。

# 角色 你是一位专业且贴心的旅游规划助手，擅长综合考虑时间、天气、价格、旅游景点等多元信息，为用户精心打造性价比超高的出行计划。

## 技能
### 技能 1: 深度探索名胜古迹历史
当用户提出旅行计划相关需求时，首先运用 {search_url} 搜索插件精准挖掘相关历史信息。

### 技能 2: 精准搜索周边特色饭店
借助 {search_around} 插件全面搜索相关信息，涵盖饭店名称、详细地址、招牌特色菜品等。

### 技能 3: 实时掌握出行天气
利用 {DayWeather} 插件获取目的地出行期间的准确天气状况。

### 技能 4: 精细规划旅行费用预算
通过 {calculate} 插件进行精确的费用预算。

## 输出格式
旅行计划输出示例...

## 限制
专注提供与旅行规划紧密相关的信息，坚决拒绝回答与旅行规划无关的话题。

配置 Function Call：在使用智能体插件，要保证使用的被 {蓝色} 而且存在，不然找不到会报错。

至此一个基本完善的旅行助手智能体就基本完成。

自定义插件

为什么自定义插件：在 Coze 平台中，自定义插件是让你的 AI 智能体从通用工具升级为专属业务助手的核心手段。

满足个性化/私有场景的需求：官方和第三方插件是为了覆盖通用场景设计的，但很多业务或个人需求是独特的（如企业内部的 CRM、OA、订单系统等私有服务）。

对接私有系统与数据，实现业务闭环：自定义插件可以让 AI 安全地访问企业内部的数据库、业务系统，完成从查询到执行的全流程。避免将敏感数据发送到第三方插件服务，符合数据安全合规要求。

扩展能力边界，实现专属功能：当现有插件无法满足特定需求时，自定义插件可以突破限制。

提升安全性与可控性：严格控制数据流向和权限，避免敏感数据泄露；代码和逻辑，可审计、可追溯。

优化性能与成本：针对特定场景优化接口逻辑，减少中间环节，提升响应速度，按需扩展，避免功能冗余。

前置准备 API

在 Coze 平台上创建自定义插件，本质是将你自己的 API/服务封装成大模型可调用的工具。需要一个可公开访问的 API 接口，支持 GET/POST 等请求方式。若 API 需要认证，提前准备好密钥（Coze 会安全存储），返回格式为标准 JSON 结构字段含义清晰。

Coze 自定义插件

左侧导航栏点击「资源库」→ 选择右上角「+ 资源」→ 点击「插件」。插件类型配置项支持云端插件（运行在 Coze 云端，无需本地环境）或端插件。IDE 运行时可选 Python3（生态丰富）或 Node.js。插件工具创建方式可选择云侧插件 - 在 Coze IDE 中创建，核心选择比基于已有服务创建更简单，适合新手，无需自己部署 API，直接在 Coze 内置 IDE 中用代码实现功能。

点击确认之后进入工具页面，开始编写 Python 脚本，不熟悉的朋友可以直接使用 AI 生成。

发布插件：点击右上角的「发布」按钮，让插件正式生效，即可在你的智能体中调用。

Python3.0 脚本示例

Python 请求接口的脚本：注意脚本中仅配置了北京、天津城市编码，所以不支持其他城市天气查询。

# 导入 Coze 运行时所需的 Args 类，用于获取输入参数和日志记录器
from runtime import Args
# 导入 requests 库，用于发送 HTTP 请求（调用天气 API）
import requests

# 定义插件的主入口函数 handler；Coze 平台会自动调用此函数
def handler(args: Args):
    """
    天气查询插件：
    根据城市地址查询天气信息，比如输入'北京'，输出{ high:"高温 7℃", low:"低温 -1℃", weather:"晴", week:"星期二" }
    """
    # === 1. 解析输入 ===
    try:
        location = args.input.location.strip()
    except Exception:
        location = ""

    # === 2. 城市编码映射（仅北京、天津，内置）===
    city_code_map = {
        "北京": "101010100",
        "天津": "101030100"
    }
    city_code = city_code_map.get(location)

    if not city_code:
        args.logger.warning(f"Unsupported location: '{location}'")
        return {"high": None, "low": None, "weather": None, "week": None}

    # === 3. 调用天气 API ===
    url = f"http://t.weather.itboy.net/api/weather/city/{city_code}"
    try:
        response = requests.get(url, timeout=5)
        response.raise_for_status()
        data = response.json()

        if data.get("status") != 200:
            raise ValueError("Weather API returned non-200 status")

        forecast = data["data"]["forecast"][0]
        return {
            "high": forecast["high"],
            "low": forecast["low"],
            "weather": forecast["type"],
            "week": forecast["week"]
        }
    except Exception as e:
        args.logger.error(f"Weather query failed for '{location}': {e}")
        return {"high": None, "low": None, "weather": None, "week": None}

USE 自定义插件

如此就实现了让大模型拥有查询天气的功能。因为只有一个插件所以提示词不需要指定 {插件}。

LOL 攻略 Agent

先使用常规模型 + 提示词，看一下是否存在英雄信息。为了测试方便，可以手动选择历史版本的大模型信息，点击模型可以选择切换大模型 LLM。

Prompt 提示词：

# 角色 你叫小智，是一个英雄联盟游戏助手
## 技能
### 技能 1：问题理解与回复分析
1. 认真理解从知识库中召回的内容和用户输入的问题，判断召回的内容是否是用户问题的答案。
2. 如果你不能理解用户的问题，此时你需要追问用户，直到你确定已理解了用户的问题和需求。
### 技能 2：回答用户问题
1. 如果知识库中没有召回任何内容，你的话术可以参考'对不起，我已经学习的知识中不包含问题相关内容，暂时无法提供答案。'
2. 如果召回的内容与用户问题有关，你应该只提取知识库中和问题提问相关的部分，整理并总结、整合并优化从知识库中召回的内容。
## 限制
1. 禁止回答的问题：个人隐私信息、违法违规内容。
2. 你必须确保你的回答容易理解。
3. 你应该用与用户输入相同的语言回答。
4. 回答长度：不超过 300 字。
5. 一定要使用 Markdown 格式回复。

配置 Agent 知识库：上传 LOL 攻略文档至知识库，系统自动处理后可供智能体调用。