假设你已经有一个正在运行的电商网站。用户可以浏览商品、加入购物车、登录账号、查看订单，并完成下单。随着业务逐渐完善，用户会开始提出大量重复但又很重要的问题：
●这件商品是什么材质？
●订单什么时候发货？
●能不能退货？
●帮我确认收货。
●能不能帮我下单某个商品？
这些问题如果全部依赖人工客服，不仅效率低，回复口径也难统一。更好的做法，是在现有网站里增加一个电商客服 Agent，让它能理解页面内容，也能在授权后访问网站已有的业务接口。这样一来，Agent 不只是一个聊天窗口，而是连接商品、购物车、订单和售后流程的智能入口。
概览
整个方案推荐的架构是：
具体来说：
1.网站单向嵌入 Agent
网站只需要加载 Agent 项目提供的 embed.js，右下角就会出现客服入口。
网站 -> 加载 Agent embed.js
2.Agent 通过 API 调用业务数据
当用户询问商品、订单、退货、购物车等问题时，Agent 根据 api-schema.json 中定义的工具，调用电商网站的 API，再基于返回的数据回答用户或辅助操作。
EdgeOne Makers 的优势在这里也比较明显：Agent 运行时、模型接入、工具调用、对话记忆和可观测能力由平台托管，电商网站只需要负责自己已有的业务接口，不需要从零搭一套 Agent 基础设施。
Agent -> 调用网站 API
3.实现效果
最终开发完的 Agent 能实现以下能力效果。例如，理解用户意图推荐指定商品：
帮助客户下单：
查询订单状态：
协助退换货：
Step 1 · 体验模板
基于 EdgeOne Makers 提供的现成模板，我们可以快速起步实现改造。首先，下载 EdgeOne Makers 的 AI Chat Assistant 模板。
这个模板已经提供了：
●聊天窗口 Widget
●embed.js 嵌入脚本
●iframe 隔离运行
●页面内容提取
●Agent 对话接口
●API Schema 工具调用机制
●EdgeOne AI Gateway 模型调用能力
●对话存储和会话管理能力
这也是使用 Makers 的直接收益：从模板开始部署后，聊天窗口、模型网关、Agent 运行时和基础会话能力已经就绪，开发者主要调整业务提示词和工具接口即可。
Step 2 · 配置 Agent 角色
Agent 项目中通常会有一个配置文件，例如：
ai-chat-assistant.config.json
可以把名称、欢迎语、推荐问题和系统提示词调整为电商客服场景：
{
“name”: “电商客服 Agent”,
“welcome”: “你好，我可以帮你介绍商品、查询订单、处理退货和引导下单。”,
“suggestedQuestions”: [
“有哪些商品？”,
“帮我查询订单状态”,
“退货政策是什么？”,
“帮我把商品加入购物车”
],
“systemPrompt”: “你是一个电商网站的客服 Agent。回答要简洁、准确。涉及订单、购物车、退货和结账时，优先调用已定义的工具接口，不要编造数据。”
}
这里不需要把所有业务逻辑都写进 Prompt。真正的数据查询和业务动作应该通过 API 工具完成。
Makers 默认提供的会话记忆能力适合这种客服场景：同一个会话可以保持连续上下文，用户先问商品、再问订单、再要求退货时，Agent 不需要每一轮都从零理解对话，能有效提升客户体验。
Step 3 · 确认网站业务 API
Agent 要能回答真实业务问题，需要调用电商网站已有的业务 API。以电商网站为例，通常会用到这些接口：
能力 接口 说明
商品列表 GET /api/products 返回商品名称、价格、材质、图片、系列和描述
售后政策 GET /api/policies 返回退货、配送、支付等政策
当前用户订单 GET /api/my-orders 根据登录 token 查询当前用户订单
指定订单查询 GET /api/order-status 通过订单号和邮箱查询订单
加入购物车 POST /api/cart 将商品加入当前用户购物车
发起结账 POST /api/checkout 进入网站已有结账流程
申请退货 POST /api/request-return 进入网站已有售后流程
更新订单状态 POST /api/update-order-status 调用网站已有订单状态流转能力
这些接口仍然属于电商网站本身，Agent 只是调用它们。这样可以复用网站原有的数据库、订单系统、购物车系统和鉴权逻辑。
需要注意的是：涉及用户数据的接口必须校验登录态。不要把后端密钥暴露到前端，也不要让 Agent 绕过网站权限直接操作用户数据。
Step 4 · 编写 api-schema.json
Agent 不会自动调用任意接口。它只能调用 api-schema.json 里明确声明的工具。
这一步是 Makers 易上手的关键：业务系统不需要改成某个专用框架，只要把已有 HTTP API 用 Schema 描述清楚，Agent 就可以在对话中按需调用。
可以为电商场景定义这些工具： [
{
"name": "list_products",
"description": "List available ecommerce products. Use this when users ask what products are available or need product recommendations.",
"method": "GET",
"endpoint": "/api/products"
},
{
"name": "get_policies",
"description": "Get store policies, including return, shipping and after-sales rules.",
"method": "GET",
"endpoint": "/api/policies"
},
{
"name": "list_my_orders",
"description": "List orders for the currently signed-in user. Use this before asking for order number when the user is logged in.",
"method": "GET",
"endpoint": "/api/my-orders"
},
{
"name": "add_to_cart",
"description": "Add a product to the signed-in user's cart after the user clearly asks to buy or add it.",
"method": "POST",
"endpoint": "/api/cart"
},
{
"name": "start_checkout",
"description": "Start checkout after the user confirms they want to place the order.",
"method": "POST",
"endpoint": "/api/checkout"
},
{
"name": "request_return",
"description": "Request a return for one of the signed-in user's orders.",
"method": "POST",
"endpoint": "/api/request-return"
},
{
"name": "update_order_status",
"description": "Update order status through the ecommerce site's existing order workflow.",
"method": "POST",
"endpoint": "/api/update-order-status"
}
]
description 很重要。它决定模型什么时候应该调用某个工具。描述越清楚，Agent 越不容易乱调接口或漏调接口。
Step 5 · 配置 Agent 访问网站 API
Agent 项目需要知道电商网站 API 的根地址：
DATA_API_BASE_URL=https://shop.example.com
当 Agent 调用工具时，会把 api-schema.json 里的 endpoint 拼接到这个地址后面，例如：
https://shop.example.com/api/products
https://shop.example.com/api/my-orders
如果接口需要鉴权，可以让 Agent 请求时带上：
Authorization: Bearer
网站嵌入脚本可以从当前登录态中读取用户 token，并传给 Agent iframe。Agent 再用这个 token 调用网站 API。
这样用户登录后，Agent 就可以直接查询“我的订单”，而不是每次都要求用户输入订单号和邮箱。
Step 6 · 准备环境变量
上线前建议先为网站和 Agent 分别准备好稳定域名。尤其是 Agent 项目，Makers 默认提供的预览域名通常有 3 小时时效限制，因此不建议直接使用 Makers 的临时预览域名做进一步操作。
建议为 Agent 先准备一个稳定的自定义域名，例如：
https://chat.example.com
然后在电商网站项目的环境变量中新增下列变量，使网站能加载 Agent：
VITE_AI_ASSISTANT_URL=https://chat.example.com
APP_URL=https://shop.example.com
如果网站 API 本身还依赖数据库、支付、订单系统或其他后端服务，如 supabase，对应环境变量按网站原有部署要求保持即可。
后续在电商网站的代码中只需要增加：
或者前端加载：
const script = document.createElement(“script”);
script.src = `${import.meta.env.VITE_AI_ASSISTANT_URL}/embed.js`;
script.async = true;
document.body.appendChild(script);
即可出现客服窗口。
然后需要获取 Agent 项目所需的模型基础变量。首先是调用平台自带模型网关的 API Key。回到 EdgeOne Makers 平台，选择「Models」，点击左侧的「API Key」选项卡，然后点击「创建 API Key」按钮。
自定一个名称，并设置过期时间，如果你的 Agent 准备长期在线，可以选择默认的永不过期。
创建完成后，你会获得一串”sk-xxx……xxx”的 Key，对应的就是 AI_GATEWAY_API_KEY 这个环境变量。请复制并妥善保管。出于安全原因，API Key 界面上不会再次显示，丢失后需重新创建。
然后点击左侧的「快速开始」选项卡。
下滑，在第四步 创建并运行脚本的第 5 行有一个 baseURL，引号里的值就是 AI 网关的地址，对应的就是 AI_GATEWAY_BASE_URL 这个环境变量，我们复制下来。
（可选）模板默认提供的模型是 deepseek-v4-flash。如果你想更换其他模型的话，可以在「模型与密钥」选项卡里，查看 AI_GATEWAY_MODEL 这个变量对应的模型 ID。例如，如果你想使用腾讯混元3.0模型，则变量名则为 @makers/hy3-preview。除了平台内置模型，你也可以接入第三方模型，只需要点击列表右侧的添加，并填入该模型的 API Key 即可获取对应的模型 ID 变量值。
Agent 项目的环境变量需要填入：
AI_GATEWAY_API_KEY=sk-xxx
AI_GATEWAY_BASE_URL=https://ai-gateway.edgeone.link/v1
AI_GATEWAY_MODEL=@makers/hy3-preview
DATA_API_BASE_URL=https://shop.example.com
其中：
●DATA_API_BASE_URL：Agent 用来调用网站 API 实现能力。
●AI_GATEWAY 相关：用来调用模型。
现在，部署所需的基础环境变量就已经准备好了。
Step 7 · 部署上线
1. 代码上传
现在，可以把在本地的 Agent 代码上传托管到 Makers 平台上，这里有两种方式可以选：
1.1 代码仓库上传
你已经有了代码仓库，比如 Github，最省事的方式就是先上传到仓库中，这里我们选择新建一个仓库：
git add .
git commit -m “feat: build photography agent”
git push
等上传完以后，回到 Makers 的控制台，选择「项目」标签，点击「导入 Git 仓库」。
第一次使用需要绑定对应的仓库平台。我们以 Github 为例，点击「Github」。
这里会弹出一个弹窗，登录 Github 账号，安装 EO Pages，默认会授权访问所有仓库，你也可以修改为只允许访问指定仓库。然后点击「Install」。
这样，就授权完成了。可以在仓库列表中选择刚才上传好的仓库。
默认选择的是仓库的 main 分支，如果打算托管特定的分支也可以手动搜索修改。
然后根据自身需求选择加速区域。需要注意的是，如果加速区域保包含中国大陆，则腾讯云账号必须完成实名认证，且仅支持完成 ICP 备案的自定义域名绑定。如果您没有提供中国大陆区域访问的需求，可以选择全球可用区（不含中国大陆）。
点击环境变量，在这里填入我们上面提到的几个变量名和变量值。
AI_GATEWAY_API_KEY=sk-xxx
AI_GATEWAY_BASE_URL=https://ai-gateway.edgeone.link/v1
AI_GATEWAY_MODEL=@makers/hy3-preview
DATA_API_BASE_URL=https://shop.example.com
如果你的 Agent 运行需要额外的环境变量，可以在这里一并填入。
填写完成后点击「开始部署」，接下来等待部署完成即可。
部署成功后，就可以点击右上角「预览」按钮，获取临时预览链接。
1.2 Workbuddy上传
如果你是在 Workbuddy 上开发，那么可以安装我们提供的 Skill：
npx skills add TencentEdgeOne/edgeone-makers-tools
这个 Skill 会先检查你有没有装 EdgeOne CLI，没有的话自动帮你配置。接着，它会问你两个问题：你用的是腾讯云国内站账号还是国际站账号，以及你打算怎么登录。
通常情况下，Workbuddy 会在浏览器中弹出腾讯云登录页，完成授权即可。如果你在特殊环境或者浏览器没法弹出，则会切换到 Token 登录模式，可以自行在 Makers 控制台的设置中生成 API Token，粘贴回来即完成授权。
登录完成后，需要手动在项目设置页里上传环境变量，并再重新部署一次。
部署成功后，就可以点击项目右上角「预览」按钮，获取临时预览链接。
2. 自定义域名
为保障内容合规，默认域名链接仅提供3小时限时预览，这个时候可以先对 Agent 做快速的正常运行测试。如果有对外提供访问或者长期使用的打算，建议及时添加自定义域名以确保服务持续可用。
点击「自定义域名」，或者直接点击左边的「域名管理」选项卡，就能来到域名管理页面。在这里能看到 EdgeOne 提供的默认临时域名。
点击「添加自定义域名」按钮，可以绑定你自己拥有的域名。
添加完域名后，需要手动调整域名的 CNAME 解析和配置 HTTPS。
如果你的域名注册在腾讯云的话，可以一键添加 CNAME 解析，等待一分钟即可生效。或者去你所使用的域名控制台手动修改解析。
HTTPS 配置则需要进一步操作。点击 HTTPS 配置列的「配置」按钮，再点击「边缘 HTTPS 证书」方框里的「配置」。
EdgeOne 提供了两种配置方式。第一种是针对没有证书但想实现 HTTPS 访问的用户。选择「申请免费证书」，EdgeOne 提供可自动申请、自动续签、自动部署的免费证书。
第二种则适用于已有 SSL 证书的用户。选择「申请 SSL 托管证书」可以将托管在腾讯云内的 SSL 的证书部署至 EdgeOne。
完成这两项配置后，就可以通过你的自定义域名访问了。
3. 观测能力
Agent 部署上线以后，另一个很重要的问题是：它到底有没有按预期运行？
普通 Web 应用出问题时，我们通常还能看接口日志、错误堆栈、请求耗时。但 Agent 应用的执行链路更长：用户发起一次对话后，模型可能会先理解问题，再调用工具，工具返回结果后模型再继续组织回答。如果中间某一步表现异常，只看最终回复很难判断问题出在哪里。
Makers 提供的观测能力，解决的就是这个问题。它会自动记录 Agent 的运行过程，不需要开发者从零搭一套日志系统。无论是在本地调试，还是部署到线上，都可以通过观测面板看到 Agent 的调用情况。
我们可以在 Makers 平台中点击要查看的项目，在左侧标签中展开「Agent」，可以看到Metrics 和 Traces 两个观测面板。
Metrics 更适合看整体状态。比如 Agent 一共被调用了多少次、模型调用了多少次、平均耗时是多少、Token 消耗情况如何、有没有出现错误。它适合用来判断服务整体是否正常：是不是调用量上来了、是不是某个阶段变慢了、是不是 Token 消耗异常。
而 Traces 则更适合看单次执行细节。
每一次 Agent 请求都会形成一条完整的调用链。展开后可以看到这次请求里模型调用了几次、调用了哪些工具、工具入参是什么、返回了什么、每一步耗时多久。如果某一步报错，也可以直接在对应节点看到错误信息。有了观测能力，开发者就不是靠猜来修 Agent，而是能沿着链路定位问题。对于 MVP 来说，这一点很重要：早期用户反馈往往很碎，只有把运行链路看清楚，才能判断是 Prompt 要改、工具要改，还是外部依赖要替换。
4. 构建版本
在构建部署页，你可以管理所有托管代码的版本，点击「更多」按钮还可以实现版本回滚。迭代过程中的每一次改动都有可能引入新问题，Makers 的构建版本和回滚能力，可以让开发者在新版本异常时先恢复到上一个稳定版本，再慢慢排查原因。这样 Agent 可以持续迭代，但线上服务不至于因为一次改动导致长时间不可用。
假设你对 Agent 代码进行了调整，想要同步到平台构建新版本，有两种方法能实现。
4.1 自动触发
如果你的代码托管在代码仓库，并且是使用代码仓库上传的形式部署的。那么只要再次往仓库的 main 分支推送新版本代码，Makers 平台会自动触发新建部署，无需额外操作。
4.2 手动构建
如果你的代码是本地上传，那么构建新版本时，需要进入项目的构建部署页。
点击「新建部署」按钮，上传新的代码文件或文件夹，再点击「开始部署」即可完成构建。
结语
通过这种方式，我们没有重写电商网站，也没有把 Agent 强行塞进原有业务代码里。网站仍然负责商品、购物车、订单、账户中心和后端数据同步；Agent 则作为一个独立的客服入口，通过 embed.js 方式接入页面，并通过 API Schema 调用网站业务接口。最终得到的是一个可以承接真实业务的电商客服 Agent：它能介绍商品、回答政策、查询订单、辅助加入购物车、引导下单，也能帮助用户申请退货或确认收货。
对于已有 web 项目来说，这是一条改造成本较低、边界清晰、也更容易部署和维护的接入路径。这也正是 Makers 的价值所在。它没有把开发者锁定在某一种框架、语言或模型里，而是把模型接入、工具调用、上下文记忆、沙箱运行、观测排查和部署上线这些通用能力提前打通。开发者真正需要关注的，是自己的业务场景：业务该如何被客户理解，客户访问时最关心哪些细节，怎样让推荐结果既符合偏好，又能服务实际的转化。
