AI 智能体从零搭建实战教程——扣子

本文面向第一次接触 AI 智能体的学习者。实战部分采用低代码智能体平台完成一个“星云智选产品顾问”，从需求分析、提示词、知识库、工作流、测试到发布全部走一遍。示例中的公司、产品、价格、政策、订单和联系方式均为虚构数据，可用于学习与演示。

一、先理解：智能体到底是什么

普通大模型更像“会回答问题的语言模型”，智能体则是在大模型基础上增加角色目标、知识、记忆、工具和流程，使它能够围绕任务持续做判断并执行动作。

二、为什么选择“产品顾问”作为练习案例

初学项目不应该一开始就涉及医疗、金融、真实个人信息或复杂外部系统。产品顾问场景同时包含知识问答、推荐、计算、记忆和安全控制，功能完整但风险较低，非常适合学习。

• 能练习知识库：产品参数、库存、售后政策都适合文档检索。
• 能练习工作流：报价计算具有明确输入和确定输出。
• 能练习记忆：用户预算和用途需要在多轮对话中保留。
• 能练习防幻觉：知识库没有的产品和价格必须明确说不知道。
• 能练习发布：最终可以在网页预览，也可作为 API 接入应用。

三、动手前先写需求，不要直接点“创建智能体”

一个常见错误是先进入平台随意添加节点，最后才思考要做什么。正确顺序是先写需求，再搭建。需求越清楚，提示词、知识库和工作流越容易设计。

四、准备账号、工作空间与测试文件

1. 登录低代码智能体平台并进入一个工作空间。工作空间用于统一管理智能体、知识库、工作流和团队成员。

2. 准备本文附带的“虚拟产品知识库.csv”和“虚拟售后与服务知识库.md”。

3. 保留“智能体测试问题与预期结果.csv”，搭建完成后用于测试。

4. 创建一个单独的学习项目，不要与正式项目或真实业务数据混用。

五、创建第一个低代码智能体

Coze（中文名：扣子）的官方网站是：主页 – 扣子或者扣子编程，你的 AI 开发伙伴， Vibe Coding 基础设施，自然语言对话开发智能体、工作流、网页应用、移动应用，一键部署上线

步骤 1：新建项目

1. 进入目标工作空间。

2. 点击“新建项目”。

3. 选择低代码模式中的“智能体开发”。

4. 项目名称填写“星云智选产品顾问”。

5. 项目描述填写“基于虚拟知识库提供产品咨询、售后说明和教学报价计算”。

不同版本的界面文字可能略有差异，但核心关系不变：工作空间中创建项目，项目中创建和编排智能体。

步骤 2：选择模型与基础参数

模型决定语言理解和生成能力。初学阶段优先选择平台提供的通用对话模型，不必一开始追求最贵或参数最大的模型。

六、系统提示词：先规定“是谁”，再规定“怎么做”

系统提示词是智能体的最高层说明。有效提示词通常包含角色、目标、知识来源、执行规则、拒答边界、输出格式和兜底策略。

七、搭建知识库：让智能体基于资料回答

1. 知识库解决什么问题

大模型不一定知道你的产品资料，即使知道，也可能已经过期。知识库通过检索增强生成（RAG）先从资料中找相关片段，再把片段交给模型组织回答。

2. 创建并导入知识库

1. 在项目资源或知识库入口中创建新的知识库。

选择创建扣子知识库

2. 上传“虚拟产品知识库.csv”。表格第一行是字段名，每一行代表一个产品。

然后下一步，下一步，等待数据处理，处理完成点击确认。

3. 上传“虚拟售后与服务知识库.md”。Markdown 中使用清晰标题拆分发货、退换货、保修和采购政策。

再次创建知识库

以下是“虚拟售后与服务知识库.md”，下载下来保存，上传

# 星云智选售后与服务知识库（虚拟数据）

> 本文档中的公司、产品、价格、联系方式和政策均为教学用途的虚构内容。

## 1. 发货政策
– 有货商品通常在付款后 24 小时内出库。
– 预售商品预计 7 至 15 个自然日内出库，具体以页面提示为准。
– 缺货商品暂不接受付款，可登记到货提醒。
– 单笔实付满 500 元免基础运费；不足 500 元收取 15 元基础运费。

## 2. 退换货政策
– 未激活、未损坏且包装完整的商品，可在签收后 7 天内申请无理由退货。
– 耳机等个人使用类商品拆封后，非质量问题不支持无理由退货。
– 因质量问题申请换货，需要提供订单号、故障描述和必要的图片或视频。
– 退款在仓库验收通过后 3 至 7 个工作日原路退回。

## 3. 保修政策
– 保修期以产品目录中的 warranty_months 为准。
– 人为进水、摔坏、私自拆机不属于免费保修范围。
– 保修申请需要提供虚拟订单号和产品编号。

## 4. 企业采购优惠
– 单一产品数量 10 至 29 件，商品小计享受 95 折。
– 单一产品数量 30 件及以上，商品小计享受 9 折。
– 折扣不与其他优惠叠加。
– 教学演示中的报价不构成真实商业报价。

## 5. 联系方式
– 虚拟客服邮箱：support@example.invalid
– 虚拟服务时间：工作日 09:00-18:00
– 以上联系方式不可用于真实联系。

点击下一步，等待数据处理完成后点击确认

精准解析”更适合：

• 扫描版 PDF
• 包含图片的说明书
• 图片中有文字
• 复杂表格文件
• 图文混排报告

4. 等待解析完成，检查是否存在乱码、空白文档或失败条目。

3. 切片与召回的关键知识

初学阶段不要频繁修改所有参数。先使用平台默认值，通过真实问题观察召回效果；确认问题后再调整切片、Top K 或文档结构。

4. 将知识库连接到智能体

1. 回到智能体编排页面。

2. 在中间的“知识”区域，点击表格后面“+”上传“星云智选产品知识库”，点击文本后面“+”上传“虚拟售后与服务知识库”

3. 让智能体“优先根据知识库回答”

在左侧“人设与回复逻辑”中，找到：

【知识要求】

把这一部分修改为下面内容：

【知识使用规则】

1. 当用户询问产品编号、产品名称、分类、价格、库存、核心特点、适用人群或保修期限时，必须优先查询“星云智选产品知识库”。

2. 当用户询问发货、运费、退换货、保修流程、企业采购或联系方式时，必须优先查询“虚拟售后与服务知识库”。

3. 回答中的价格、库存、保修期限和售后政策必须以知识库内容为准，不得自行猜测或补充知识库中不存在的数据。

4. 如果知识库没有查到明确答案，应直接说明：
“当前知识库中没有查到相关信息，请联系人工客服确认。”

5. 不要把知识库中不同产品的数据混合在一起。

为什么要这样写

只添加知识库，代表智能体“拥有资料”。

增加这段提示词，是告诉智能体：

什么问题查哪个知识库
回答应遵守什么规则
查不到时怎么处理

知识库负责提供事实，提示词负责约束模型如何使用这些事实。

4. 在预览对话中输入“P2002 的价格和保修期是多少？”

5. 预期回答应包含 1299 元和 18 个月，不应出现知识库之外的参数。

八、创建报价工作流：把确定性计算交给流程

价格计算不适合只让模型心算。模型擅长理解语言，但金额计算应尽量交给确定性工作流或代码。这样可以复测、审计和避免算错。

1. 进入资源库

点击“+资源”，点击“工作流”

2. 设置开始节点

击画布中的：

开始

右侧会出现参数配置区域。

开始节点可能默认有一个：

input

这个默认参数本次不需要。能删除时，点击它旁边的删除图标；不能删除时，也可以暂时保留，但后面不引用它。

添加第一个输入参数

点击：

＋ 添加参数

填写：

变量名：product_id
类型：String
描述：用户要购买的产品编号，例如 P2002
是否必填：开启

为什么类型是 String

产品编号是：

P1001
P2002

它不是拿来加减乘除的数字，所以使用字符串 String。

添加第二个输入参数

再次点击添加参数，填写：

变量名：quantity
类型：Number
描述：购买数量，必须是大于0的整数，例如12
是否必填：开启

有些界面可能提供：

Integer

有 Integer 时可以直接选择 Integer；只有 Number 时选择 Number，再在代码中检查它是否为整数。

最终开始节点

应该类似：

不要在开始节点添加：

unit_price
discount_rate
shipping_fee
final_total

3、添加代码节点

在“开始”和“结束”之间找到连线上的：

＋

点击后，在节点列表中寻找：

业务逻辑
→ 代码

点击“代码”。

如果不是在线上添加，也可以从底部节点面板中选择“代码”，然后拖到画布中。

把代码节点名称修改为：

查询产品并计算报价

画布应变成：

开始
↓
查询产品并计算报价
↓
结束

4、配置代码节点输入

点击代码节点。

在右侧找到：

输入

需要添加两个参数。

参数一

变量名：

product_id

变量值不要手动输入固定文字，要点击变量选择按钮，引用：

开始 → product_id

参数二

变量名：

quantity

变量值引用：

开始 → quantity

最终关系是：

代码节点 product_id ← 开始节点 product_id
代码节点 quantity ← 开始节点 quantity

这就是“节点之间通过变量传递数据”。

5、粘贴报价代码

代码语言选择：

JavaScript

删除默认示例代码，粘贴下面这份兼容当前扣子代码节点的代码：

async function main({ params }: Args): Promise<Output> {
const productId = String(params.product_id || "")
.trim()
.toUpperCase();

const quantity = Number(params.quantity);

// 教学用虚拟产品数据
const products: Record<string, any> = {
P1001: {
name: "星云轻办公笔记本 Air 14",
price: 4999,
stock: "有货"
},
P1002: {
name: "星云创作本 Pro 16",
price: 8999,
stock: "有货"
},
P1003: {
name: "星云迷你主机 Mini X",
price: 3299,
stock: "预售"
},
P2001: {
name: "星云降噪耳机 H5",
price: 699,
stock: "有货"
},
P2002: {
name: "星云会议麦克风 M2",
price: 1299,
stock: "有货"
},
P3001: {
name: "星云便携显示器 V15",
price: 1599,
stock: "缺货"
},
P3002: {
name: "星云护眼显示器 E27",
price: 1899,
stock: "有货"
},
P4001: {
name: "星云智能插座 S1",
price: 99,
stock: "有货"
}
};

// 1. 检查产品编号
if (!productId) {
return {
success: false,
message: "请输入产品编号，例如 P2002。",
product_id: "",
product_name: "",
quantity: 0,
unit_price: 0,
stock_status: "",
discount_rate: 0,
original_subtotal: 0,
discounted_subtotal: 0,
shipping_fee: 0,
final_total: 0,
final_total_text: "0.00",
data_notice: "以上为教学虚拟数据，不构成真实报价"
};
}

// 2. 检查数量
if (!Number.isInteger(quantity) || quantity <= 0) {
return {
success: false,
message: "购买数量必须是大于0的整数。",
product_id: productId,
product_name: "",
quantity: 0,
unit_price: 0,
stock_status: "",
discount_rate: 0,
original_subtotal: 0,
discounted_subtotal: 0,
shipping_fee: 0,
final_total: 0,
final_total_text: "0.00",
data_notice: "以上为教学虚拟数据，不构成真实报价"
};
}

// 3. 查找产品
const product = products[productId];

if (!product) {
return {
success: false,
message: `没有找到产品编号 ${productId}，请检查编号是否正确。`,
product_id: productId,
product_name: "",
quantity: quantity,
unit_price: 0,
stock_status: "",
discount_rate: 0,
original_subtotal: 0,
discounted_subtotal: 0,
shipping_fee: 0,
final_total: 0,
final_total_text: "0.00",
data_notice: "以上为教学虚拟数据，不构成真实报价"
};
}

// 4. 检查库存
if (product.stock === "缺货") {
return {
success: false,
message: `${product.name} 当前缺货，暂时无法报价。`,
product_id: productId,
product_name: product.name,
quantity: quantity,
unit_price: product.price,
stock_status: product.stock,
discount_rate: 0,
original_subtotal: 0,
discounted_subtotal: 0,
shipping_fee: 0,
final_total: 0,
final_total_text: "0.00",
data_notice: "以上为教学虚拟数据，不构成真实报价"
};
}

// 5. 计算折扣
let discountRate = 1;

if (quantity >= 30) {
discountRate = 0.9;
} else if (quantity >= 10) {
discountRate = 0.95;
}

// 6. 计算金额
const originalSubtotal = product.price * quantity;
const discountedSubtotal = originalSubtotal * discountRate;
const shippingFee = discountedSubtotal >= 500 ? 0 : 15;
const finalTotal = discountedSubtotal + shippingFee;

return {
success: true,
message: `${product.name} 购买 ${quantity} 件的最终金额为 ${finalTotal.toFixed(2)} 元。`,
product_id: productId,
product_name: product.name,
quantity: quantity,
unit_price: product.price,
stock_status: product.stock,
discount_rate: discountRate,
original_subtotal: Number(originalSubtotal.toFixed(2)),
discounted_subtotal: Number(discountedSubtotal.toFixed(2)),
shipping_fee: shippingFee,
final_total: Number(finalTotal.toFixed(2)),
final_total_text: finalTotal.toFixed(2),
data_notice: "以上为教学虚拟数据，不构成真实报价"
};
}

为什么产品数据暂时直接写在代码里

这是教学第一版，目的是先单独验证：

变量是否传递成功
代码是否计算正确
结束节点是否能拿到结果
智能体是否会调用工作流

如果一开始加入知识库检索，失败时很难判断到底是：

知识库没召回
字段没解析
代码错误
变量引用错误
智能体没调用工作流

先把确定性计算跑通，排错更简单。

6、配置代码节点输出

在代码节点下方找到：

输出

添加下面这些输出变量。

参数名必须与代码中 return 返回对象的名称完全一致，否则可能出现：

代码有返回值
但节点输出取不到值

官方文档也要求代码节点输出名称、类型与 return 对象保持一致。

更方便的方法

部分界面可以先点击代码节点的：

试运行

输入：

product_id：P2002
quantity：12

运行后，在“原始输出”附近寻找：

同步到输出
从运行结果生成输出
导入输出结构

点击后，平台会根据代码返回结果自动创建输出参数。

没有这个按钮时，就按照上面的表格手动添加。

7、配置结束节点

点击画布中的：

结束

选择返回方式：

返回变量

不要先使用“返回文本”。

因为返回变量可以生成结构化 JSON，后续智能体或 API 都能读取。工作流直接绑定智能体时，智能体模型会自动总结返回的 JSON，并以自然语言回复用户。

添加结束节点输出

建议添加以下变量：

success

引用：

查询产品并计算报价 → success

message

引用：

查询产品并计算报价 → message

product_id

引用：

查询产品并计算报价 → product_id

product_name

引用：

查询产品并计算报价 → product_name

quantity

引用：

查询产品并计算报价 → quantity

unit_price

引用：

查询产品并计算报价 → unit_price

discount_rate

引用：

查询产品并计算报价 → discount_rate

shipping_fee

引用：

查询产品并计算报价 → shipping_fee

final_total

引用：

查询产品并计算报价 → final_total

final_total_text

引用：

查询产品并计算报价 → final_total_text

data_notice

引用：

查询产品并计算报价 → data_notice

8、检查节点连线

最终画布必须是：

开始
│
▼
查询产品并计算报价
│
▼
结束

如果没有连线：

没有连线时，节点即使配置正确也不会执行。

9、独立试运行工作流

点击工作流页面右上角：

试运行

填写：

product_id：P2002
quantity：12

点击：

运行

成功节点通常会显示绿色边框，并且可以查看每个节点本次运行的输入与输出。

正确计算过程

单价：

1299

数量：

12

原价小计：

1299 × 12 = 15588

12件符合10～29件规则，所以打95折：

15588 × 0.95 = 14808.60

折后金额已超过500元：

运费 = 0

最终金额：

14808.60元

预期输出

应该类似：

{
"success": true,
"message": "星云会议麦克风 M2 购买 12 件的最终金额为 14808.60 元。",
"product_id": "P2002",
"product_name": "星云会议麦克风 M2",
"quantity": 12,
"unit_price": 1299,
"discount_rate": 0.95,
"shipping_fee": 0,
"final_total": 14808.6,
"final_total_text": "14808.60",
"data_notice": "以上为教学虚拟数据，不构成真实报价"
}

JSON 数值类型可能显示：

14808.6

而不是：

14808.60

它们数值相同。为了显示两位小数，代码额外返回了：

final_total_text = "14808.60"

10、再测试三种异常情况

不要只测试成功数据。

测试1：数量错误

product_id：P2002
quantity：0

预期：

购买数量必须是大于0的整数。

测试2：产品不存在

product_id：P9999
quantity：2

预期：

没有找到产品编号 P9999。

测试3：产品缺货

product_id：P3001
quantity：2

预期：

星云便携显示器 V15 当前缺货，暂时无法报价。

这三个测试都通过，说明输入校验、产品查询和库存判断都正常。

11、发布工作流

独立试运行成功后，点击右上角：

发布

按照页面提示确认发布。

这一步不能省略。要把资源库工作流添加到智能体，工作流需要已经创建并发布。

12、把工作流添加到智能体

回到你刚才的智能体标签页。

在中间“技能”区域找到：

工作流

你截图中“工作流”右侧有

＋

点击它。

在弹窗中选择：

我创建的

找到,勾选后点击：

确认

官方操作也是在智能体编排页面的“工作流”区域点击加号，然后选择已经发布的目标工作流。

工作流没有出现时

检查：

13、修改智能体提示词

在左侧“人设与回复逻辑”末尾添加：

【报价工作流调用规则】

1. 当用户明确询问购买某个产品若干件的总价、报价、折扣后金额或运费时，调用“星云智选报价计算”工作流。

2. 调用工作流时：
– product_id 填写用户提供的产品编号，例如 P2002；
– quantity 填写用户提供的购买数量，例如 12。

3. 用户没有提供产品编号时，先询问产品编号。

4. 用户没有提供购买数量时，先询问购买数量。

5. 不得自行猜测产品编号或购买数量。

6. 工作流返回 success=true 时，以工作流输出的单价、折扣率、运费和最终金额为准，不得重新心算或擅自修改结果。

7. 工作流返回 success=false 时，直接向用户说明 message 中的错误原因。

8. 报价末尾必须说明：
“以上为教学虚拟数据，不构成真实报价。”

开始节点的参数描述和是否必填会影响智能体如何从用户问题中提取参数；必填信息缺失时，工作流可能不会被正确触发。

14、在智能体中测试

在右侧“预览与调试”输

买12台P2002多少钱？

正确回答应包含：

产品：星云会议麦克风 M2
单价：1299元
数量：12
折扣：95折
运费：0元
最终金额：14808.60元
以上为教学虚拟数据，不构成真实报价。

检查是否调用工作流

回答生成后，在回复附近寻找：

调试
运行详情
调用详情
执行过程

打开后应该看到：

工作流：星云智选报价计算

输入：
product_id = P2002
quantity = 12

输出：
final_total = 14808.6
final_total_text = 14808.60

当前版本为什么暂时没有使用知识库取价格

在真正公司的系统中，一般这样分工：

知识库
→ 产品说明、售后政策、使用手册

数据库或业务API
→ 实时价格、实时库存、订单信息

工作流和代码
→ 折扣、运费、总价计算

知识库检索节点是根据用户输入召回最匹配的知识片段，并把结果列表传给后续节点；它很适合知识问答，但实时价格和库存通常更适合数据库或业务接口。

当前没有业务数据库和价格API，所以第一版用代码中的虚拟产品数据，优点是：

结果固定
容易复测
不会召回错产品
方便理解变量和代码节点

等这一版全部成功后，第二版再升级为：

开始节点
→ 知识库检索节点
→ 产品数据解析节点
→ 条件分支
→ 代码计算节点
→ 结束节点

当前先完成并验证这条最基础链路：

开始 → 代码 → 结束 → 试运行 → 发布 → 添加到智能体

九、配置记忆：让多轮对话保持上下文

记忆不是把所有聊天永久保存。它应该只保存完成任务需要的信息，并设置清晰范围。对于练习智能体，只需要在当前会话中记住预算、用途和偏好。

1. 启用会话上下文或记忆能力。

2. 规定可记忆字段：预算、用途、偏好产品类别。

3. 不要记忆密码、身份证号、银行卡号等敏感数据。

4. 测试“我的预算是 5000 元”后，再问“按刚才预算推荐”。

一、找到变量配置入口

回到“星云智选产品顾问”的智能体编排页面。

看页面中间区域，向下找到：

记忆
├─ 变量
├─ 数据库
└─ 长期记忆

在：

变量

这一行最右侧找到：

＋

点击这个加号。

打开的窗口通常叫：

编辑变量

或：

变量配置

二、选择“用户变量”

打开变量配置窗口后，一般会分成：

用户变量
系统变量

选择：

用户变量

不要在系统变量中找预算、用途。

系统变量是平台自动提供的信息，例如用户标识、位置、飞书群信息等；用户变量才是开发者自行定义，用于保存语言偏好、预算、用途等个性化信息。

三、创建第一个变量：预算

点击：

添加变量

或：

＋ 新增用户变量

填写如下内容。

变量名称

budget

变量名称建议使用英文。

不要写：

用户预算

后续在提示词或工作流中引用英文变量更方便。

描述

填写：

用户购买产品时的预算范围，例如5000元、3000到5000元。只保存用户主动提供的购买预算，不保存银行卡、账户余额或支付信息。

描述很重要。平台会根据名称和描述判断用户说的内容是否应该写入这个变量；准确的变量名称和描述有助于提高匹配准确度。

默认值

保持空白。

不要填写：

5000

否则没有提供预算的用户也可能被默认当成预算5000元。

数据类型

当前扣子的用户变量只支持：

String

所以预算也使用 String，不要寻找 Integer 或 Number。

保存后的内容可能是：

5000元
3000到5000元
不超过8000元

以后需要参与数值计算时，再在工作流中把字符串转换成数字。

启用变量

打开：

启用变量

如果窗口中还有“操作”列、复选框或“允许提示词访问”，也要勾选。

最终要达到两个效果：

变量已启用
允许在人设与提示词中访问

仅启用变量但不允许提示词访问时，它可能只能在工作流或插件中使用；允许提示词访问后，智能体可以在人设和回复逻辑中使用这个变量。

四、创建第二个变量：用途

再次点击添加变量。

变量名称

usage

描述

填写：

用户购买产品的主要用途或使用场景，例如日常办公、视频剪辑、编程学习、在线会议、通勤或家庭影音。

默认值

保持空白。

类型

String

状态

启用变量：开启
提示词访问：开启

五、创建第三个变量：偏好产品类别

再次新增变量。

变量名称

preferred_category

描述

填写：

用户偏好的产品类别，例如笔记本电脑、显示器、耳机、会议设备、迷你主机或智能家居。

默认值

保持空白。

类型

String

状态

启用变量：开启
提示词访问：开启

六、最终变量配置

最终应该有三个用户变量：

不要创建下面这些变量：

password
id_card
bank_card
payment_password
account_balance
phone_password

当前练习只保存完成产品推荐所必需的信息。

七、在人设与回复逻辑中加入记忆规则

关闭变量窗口，回到左侧：

人设与回复逻辑

在现有提示词末尾追加：

【用户偏好变量使用规则】

当前可使用的用户变量：

1. budget
含义：用户购买产品时提供的预算范围。

2. usage
含义：用户购买产品的主要用途或使用场景。

3. preferred_category
含义：用户偏好的产品类别。

【记录规则】

1. 只有当用户主动、明确提供预算时，才记录或更新 budget。

2. 只有当用户主动说明使用场景时，才记录或更新 usage。

3. 只有当用户主动说明偏好的产品类别时，才记录或更新 preferred_category。

4. 用户提供新的预算、用途或产品类别时，以最新内容为准。

5. 不得自行推测用户没有明确提供的信息。

6. 不得把用户的一次随意提问错误地当成长期偏好。例如用户询问某款耳机，不代表用户一定偏好耳机。

7. 不得记录密码、身份证号、银行卡号、验证码、账户余额、家庭住址等敏感信息。

8. 如果用户主动发送敏感信息，应提醒用户不要在对话中提供该信息，不得将其保存到变量中。

【推荐规则】

1. 用户要求产品推荐时，优先参考 budget、usage 和 preferred_category。

2. 某个变量为空时，不得自行猜测，可以询问用户是否愿意补充。

3. 推荐结果必须来自“星云智选产品知识库”。

4. 推荐时应说明产品名称、价格、核心特点、适用场景以及是否符合用户预算。

5. 如果没有符合全部条件的产品，应明确说明哪个条件无法满足，不得虚构产品。

6. 在回答中不要直接显示变量名 budget、usage、preferred_category，应使用自然语言表达。

八、测试第一轮：设置预算

在右侧“预览与调试”中，建议先新建一轮对话。

输入：

我的预算是5000元。

智能体可能回答：

好的，我会按照5000元左右的预算为你推荐产品。请问主要用于什么场景？

平台会自动识别与已启用变量相匹配的内容，并写入相应用户变量。用户后续提供新值时，变量也可以自动更新为最新内容。

接着输入：

主要用于日常办公和轻度编程。

预期：

usage = 日常办公和轻度编程

再输入：

我更倾向于笔记本电脑。

预期：

preferred_category = 笔记本电脑

九、测试第二轮：使用刚才的信息推荐

继续在同一个右侧对话中输入：

按照刚才的预算和用途推荐一款产品。

智能体应该结合：

budget = 5000元
usage = 日常办公和轻度编程
preferred_category = 笔记本电脑

查询产品知识库。

根据当前虚拟产品数据，比较合适的结果是：

星云轻办公笔记本 Air 14
价格：4999元
特点：1.25kg、14英寸2.5K屏、16GB+512GB
适合：学生、日常办公、轻度编程
库存：有货

回答大致应该是：

根据你5000元左右的预算，以及日常办公、轻度编程和笔记本电脑的偏好，推荐“星云轻办公笔记本 Air 14”。

价格：4999元
核心特点：1.25kg轻量机身、14英寸2.5K屏、16GB内存和512GB存储
适用场景：日常办公、学习和轻度编程
库存状态：有货

该产品价格在你的预算范围内，使用场景也比较符合。

十、查看变量是否真的保存

在智能体编排页面右上角或右侧预览区域上方，寻找：

记忆

或英文：

Memory

点击后选择：

变量

官方文档说明，可以从智能体编排页面右上角进入“记忆 → 变量”，查看当前用户的变量值。

正常应该看到：

budget：5000元
usage：日常办公和轻度编程
preferred_category：笔记本电脑

如果没有立即出现：

十一、测试变量更新

继续输入

我的预算改成9000元。

然后输入：

现在按照新的预算推荐。

系统应把：

budget = 5000元

更新为

budget = 9000元

用户变量在用户提供新数据时可以自动更新为最新值。

这时可能推荐：

星云创作本 Pro 16
价格：8999元

十二、测试缺少信息时是否会追问

新建一轮没有偏好信息的测试，输入：

帮我推荐一款产品。

合理回答应该是：

可以，请告诉我以下信息：

1. 预算范围；
2. 主要用途；
3. 偏好的产品类别。

而不是直接随意推荐。

十三、长期记忆现在要不要开启

当前阶段建议先保持关闭。

你的需求是只控制：

预算
用途
偏好产品类别

用户变量已经足够。

变量只能记录开发者定义的字段；长期记忆会从对话中自动提取、总结和积累更广泛的个性化信息。对于强调“只保存必要信息”的练习，用户变量更容易控制。

以后需要测试跨长时间的个性化体验，例如：

用户喜欢轻薄设备
用户不喜欢入耳式耳机
用户经常购买办公产品

再考虑开启长期记忆。

开启长期记忆后，智能体会自动记录用户画像和关键记忆点；若同时开启“支持在Prompt中调用”，智能体可以在对话中直接召回这些记忆。

十四、真正只想在当前会话记住怎么办

如果你的要求严格是：

关闭当前对话或新建会话后，就不要再记得预算。

那么不要创建用户变量，也不要开启长期记忆。

只需要在同一轮对话中测试：

用户：我的预算是5000元。

用户：用于办公和轻度编程。

用户：按照刚才的预算推荐。

模型会根据当前对话历史理解“刚才的预算”。

但是新建对话后，它就不会再保留这些信息。

因此两种方案要区分：

只在当前对话有效
→ 不配置变量，不开启长期记忆

跨会话保留三个固定字段
→ 创建 budget、usage、preferred_category 用户变量

自动积累更广泛的用户画像
→ 开启长期记忆

十、工具与插件：什么时候应该调用外部能力

知识库回答“已经写在资料里的内容”；工具处理“需要实时访问或执行动作的内容”。例如实时天气、订单状态、数据库查询、邮件发送和工单创建。

扣子里的“插件”和“工具”不是完全相同的概念：

插件 = 一组相关的外部能力
工具 = 插件中的某一个具体 API 操作

例如一个“物流服务插件”中可以包含：

物流服务插件
├─ 查询物流状态工具
├─ 查询预计送达时间工具
└─ 申请物流催单工具

智能体真正执行的是某个工具，也就是调用某个 API。一个插件可以包含多个工具。

一、先判断该用知识库、工作流还是插件

可以使用下面这个判断方法。

最简单的判断口诀：

固定资料 → 知识库
确定性计算和流程 → 工作流
实时数据或执行动作 → 插件/API

扣子官方也把知识库用于文档和表格检索，把插件定义为通过 API 连接外部平台和服务，把工作流用于实现多步骤逻辑。

二、先做一个简单、安全的插件练习

建议先添加一个实时天气查询插件。

天气插件与产品顾问业务没有直接关系，但非常适合学习，因为：

• 数据是实时的；
• 不涉及真实订单；
• 不需要上传知识文档；
• 可以清楚观察智能体什么时候调用插件；
• 通常不涉及危险的写入操作。

练习完成后，可以把天气插件删除，避免产品顾问拥有无关能力。

三、在当前智能体页面添加插件

你现在的智能体编辑页面中间有：

编辑
└─ 技能
├─ 插件
└─ 工作流

你的 quote_calculator 已经在“工作流”下面。

第1步：找到“插件”

在中间编辑区域找到：

技能
→ 插件

“插件”这一行最右边有：

＋

点击这个加号。

官方当前的操作也是：

智能体编排页面
→ 技能
→ 插件
→ 点击加号

然后从插件商店或当前工作空间中选择已经发布的插件工具。

第2步：搜索天气插件

进入“添加插件”窗口后，在搜索框输入：

天气

页面中可能出现多个插件。具体名称会随商店内容变化，优先选择带有下面标识的插件：

官方
免费

暂时不要选择：

三方、付费

因为部分付费插件会产生调用费用，而且添加三方付费插件后，智能体可能无法发布到某些公共渠道。

第3步：展开插件，而不是直接添加整个插件

点击目标天气插件后，通常会展开里面的工具，例如：

天气插件
├─ 查询实时天气
├─ 查询未来天气
└─ 查询空气质量

只添加一个最基础的工具，例如：

查询实时天气

点击该工具右边的：

添加

官方文档说明，在添加插件页面需要先展开插件，再对某个具体工具点击“添加”。

为什么只添加一个工具

这是“最小权限”原则。

你现在只需要验证：

智能体能否调用外部实时服务

就只添加“查询实时天气”，不必把空气质量、历史天气、灾害预警等全部添加。

添加的工具越多，大模型选择错误工具的可能性也越高。

第4步：确认插件已经添加

返回智能体编排页面后，中间区域应出现类似：

插件
└─ 查询实时天气

也可能显示插件名称，展开后才看到工具名称。

这表示智能体现在具备了调用天气 API 的能力。

四、在人设与回复逻辑中写明调用规则

只添加插件还不够。

插件表示智能体“拥有工具”；提示词负责告诉智能体：

• 什么情况下使用；
• 需要什么参数；
• 缺少参数怎么办；
• 不该什么时候调用。

在左侧“人设与回复逻辑”末尾加入：

【天气插件调用规则】

1. 当用户明确询问某个城市或地区的实时天气、温度、
天气状况、风力或是否下雨时，调用天气查询工具。

2. 用户没有提供城市或地区时，先询问用户所在城市，
不得自行猜测用户位置。

3. 用户只是进行普通问候、产品咨询、售后咨询或报价计算时，
不得调用天气插件。

4. 天气数据必须以插件返回结果为准，
不得根据模型自身知识猜测实时天气。

5. 插件调用失败或没有返回有效结果时，应明确说明：
“暂时没有查询到实时天气信息，请稍后重试。”

6. 不得把用户输入的城市保存为长期偏好，
除非用户明确要求保存。

官方建议在人设与回复逻辑中明确插件的使用场景，以减少模型随机判断造成的不正确调用。

五、在右侧预览与调试中测试

测试之前模型的当前时间需要打开

测试1：参数完整

在右侧输入：

查询成都今天的实时天气。

智能体应当调用天气工具，然后返回实时结果。

不要要求答案必须与某个固定温度一致，因为实时天气会变化。

重点观察：

是否调用了天气插件
传入的城市是否为成都
是否使用插件结果回答

测试2：参数缺失

输入：

今天的天气怎么样？

因为没有城市，正确行为应该是追问：

请告诉我需要查询哪个城市或地区的天气。

直接绑定智能体的插件会由智能体从用户问题中提取必要参数；如果缺少必填参数，智能体应继续追问，直到获得完整参数。

测试3：不该调用插件的情况

输入：

P2002 的价格是多少？

这时应查询产品知识库，不应调用天气插件。

再输入：

买12台P2002多少钱？

这时应调用：

quote_calculator

不应调用天气插件。

这一步是在测试“工具路由”：

天气问题 → 天气插件
产品资料 → 产品知识库
售后规则 → 售后知识库
报价计算 → quote_calculator

六、查看插件是否真的被调用

智能体回答完成后，在回答卡片下方或预览区域右上角寻找：

调试
运行详情
调用详情

进入调试信息后，应能看到类似：

调用工具：查询实时天气

输入：
city = 成都

输出：
天气状况 = …
温度 = …
风力 = …

页面具体字段取决于插件本身。

你需要确认的是：

用户自然语言
→ 智能体提取城市
→ 调用天气工具
→ 工具返回实时数据
→ 智能体组织回答

七、真实物流查询为什么不能使用知识库

例如用户问：

订单 X202607170001 到哪里了？

物流状态可能是：

10:00 已揽收
12:30 运输中
16:00 到达转运中心
第二天 09:00 派送中

如果把物流状态上传到知识库，知识库很快就会过期。

正确架构应该是：

用户
↓
智能体
↓
物流查询插件
↓
公司后端物流API
↓
物流服务商API或订单系统
↓
返回最新物流状态

知识库负责固定规则，例如：

什么情况下可以催单
预计多久发货
运费规则是什么

插件负责实时信息，例如：

包裹当前在哪
是否已经签收
预计什么时候送达

八、真实业务插件怎么创建

这一部分需要有一个真正可访问的 API。

没有 API 时，不能凭空实现“真实订单查询”。插件只是调用 API 的外壳，不会自动产生订单数据。

具体操作见链接https://blog.csdn.net/2601_95045387/article/details/162974001?fromshare=blogdetail&sharetype=blogdetail&sharerId=162974001&sharerefer=PC&sharesource=2601_95045387&sharefrom=from_link

九、创建自定义物流插件的详细流程

十一、测试：智能体“能回答”不等于“可用”

至少从准确性、流程、边界、多轮和稳定性五个方面测试。本文附带了 10 条虚拟测试问题，可以作为第一版回归测试集。

推荐的测试记录表

十二、调试常见问题与处理方法

十三、发布前检查与版本管理

• 名称、头像、简介和开场白已经填写。
• 知识库文件无真实个人信息、密钥或公司秘密。
• 系统提示词中没有真实 Token、密码和联系方式。
• 核心测试集全部执行并记录结果。
• 工作流错误分支和空输入已经测试。
• 发布说明写清本版本新增内容和已知限制。
• 保留旧版本，出现问题时能够回滚。

十四、发布与 API 接入的基本思路

完成测试后，可以发布到平台提供的可用渠道。用于学习时，先选择平台内预览或网页渠道；需要接入自有网站、APP 或后端时，再使用官方 API 或 SDK。

• 为每个用户生成稳定的会话标识，避免不同用户上下文混淆。
• 设置超时、重试和异常提示。
• 记录请求编号、耗时、工作流调用和错误，但不要记录不必要的敏感内容。
• 对公开接口配置鉴权、频率限制和成本上限。

十五、智能体关键知识清单

附录 A：虚拟产品数据预览

附录 B：报价计算示例

参考资料

• 扣子官方文档：搭建 AI 助手智能体、低代码工作流、工作流与对话流、知识库、插件。
• 扣子官方开发文档：API 概述、Python/Node.js/Java SDK 快速开始。
• 官方文档入口：https://www.coze.cn/open/docs

说明：低代码平台的菜单名称、模型列表和节点配置会随版本更新。本文强调的是可迁移的方法：先定义任务和边界，再配置提示词、知识、流程、工具、测试和发布。