基于微信小程序业务，在EdgeOne Makers上部署一个智能处理交易投诉Agent

大家好，我是小悟

假设你已经有一个正在运营的微信小程序商城。用户可以在线选购商品、查看订单、申请售后、提交投诉。随着订单量增长，微信交易保障体系下的投诉单也会随之增多。你会发现，商家每天都会面对大量重复但又不能忽视的投诉处理任务：

• 用户投诉「未收到货」，需要及时回应并协商和解
• 平台要求商家补充凭证，提交发货的相关资料
• 平台判定商责后，需要提交退款凭证并确认收货状态
• 对平台判定有异议时，要在规定时限内提交申诉材料
• 投诉状态流转复杂——待回应、待补证、待退款、待申诉——人工处理极易漏单或超时

这些问题如果全部依赖运营人员逐条登录微信公众平台后台处理，不仅效率低，还容易因为不熟悉投诉流程规则而错失回应时机、导致平台介入判责。更好的做法，是在现有商家管理后台里增加一个交易投诉处理 Agent，让它能理解每条投诉的状态和内容，也能在商家确认意愿后，调用微信官方的投诉处理接口完成操作。这样一来，Agent 不只是一个对话窗口，而是连接微信交易投诉体系、商家后台和运营人员的智能操作入口。

概览

整个方案推荐的架构如下：

商家管理后台（通过 iframe 或 web-view 嵌入 Agent） → EdgeOne Makers Agent（AI 对话 + Function Calling） → REST API 代理层（AccessToken 管理 + 微信 API 封装） → 微信投诉处理官方接口

具体来说：

1. 商家管理后台单向嵌入 Agent

商家后台只需要加载 Agent 项目提供的 embed.js 或通过 iframe 嵌入 widget 页面，即可在页面右下角呈现投诉处理助手的对话入口。小程序端可通过 <web-view> 组件承载。

2. Agent 通过 API 调用后端

当商家询问「有哪些待处理投诉」「帮我查一下投诉单 #12345」「同意这个投诉的和解」时，Agent 根据 api-schema.json 中定义的 6 个工具，调用后端的 REST API。后端负责管理微信 AccessToken 的获取与刷新，并将请求转发给微信官方投诉处理接口，最后将结果返回给 Agent。

EdgeOne Makers 的优势在这里也比较明显：Agent 运行时、模型接入、工具调用、对话记忆和可观测能力由平台托管；后端只需要专注微信 API 的鉴权与封装，不需要从零搭建 Agent 基础设施。

3. 实现效果

最终开发完的 Agent，能通过自然语言对话，在商家确认后直接完成以下操作：

除了嵌入小程序商家后台，当然也可以直接独立访问。

一、体验模板

基于 EdgeOne Makers 提供的现成模板，我们可以快速起步实现改造。首先，克隆 EdgeOne Makers 的 AI Chat Assistant 模板：

git clone https://github.com/TencentEdgeOne/AI-Chat-Assistant.git complaint-agent
cd complaint-agent
npm install
npm run dev

这个模板已经提供了：

• 聊天窗口 Widget（支持完整页面和嵌入模式）
• embed.js 嵌入脚本（一行代码接入任意网站）
• iframe 隔离运行（不侵入宿主页面样式）
• Agent 对话接口（SSE 流式响应 + 会话记忆）
• API Schema 工具调用机制（Function Calling）
• EdgeOne AI Gateway 模型调用能力（支持混元、DeepSeek 等模型）
• 对话存储和会话管理能力

借助 Makers，您可以直接跳过底层构建。从模板启动后，基础对话与运行环境即刻生效，让开发者能全力投入业务逻辑梳理与提示词打磨。

二、配置 Agent 角色

Agent 项目根目录下的 ai-chat-assistant.config.json 是核心配置文件。我们需要把名称、欢迎语、推荐问题和系统提示词调整为投诉处理场景：

{
  "name": "投诉处理助手",
  "welcome": "你好，我可以帮你查询投诉详情、回应投诉、补充凭证、提交退款凭证和发起申诉。",
  "suggestedQuestions": [
    "有哪些待处理的投诉？",
    "帮我查询投诉单详情",
    "如何回应用户投诉？"
  ],
  "systemPrompt": "你是微信小程序交易投诉处理助手。你的职责是帮助商家高效处理微信交易保障体系下的投诉单。\n\n## 投诉状态说明\n投诉单有以下几个关键状态，请根据状态引导商家选择对应操作：\n- 状态 201：待商家回应——请引导商家确认是「同意和解」还是「拒绝和解」，然后调用 respond_complaint\n- 状态 106：待商家补充凭证——请引导商家提供文字说明或上传图片凭证，然后调用 supply_proof\n- 状态 206：待商家上传退款凭证——请确认是否涉及退货（需确认收货状态和退货单号），然后调用 submit_refund_proof\n- 状态 401：待商家申诉——请引导商家提供申诉理由和凭证，然后调用 submit_appeal\n\n## 行为准则\n1. 涉及投诉回应、退款、申诉等操作时，必须先向商家确认意愿，不要自行决定\n2. 所有接口调用前，先通过 query_complaint_detail 获取投诉单最新状态，避免误操作\n3. 提交凭证时，文字内容(content)和图片凭证(mediaIdList)至少传一个\n4. 回复要简洁、准确、可执行，不要编造数据\n5. 如果接口返回错误，向商家清晰说明错误原因和下一步建议"
}

systemPrompt 设计要点

系统提示词中包含：① Agent 角色定位 ② 可用工具列表及使用场景 ③ 投诉处理流程 ④ 安全规则（操作前确认） ⑤ 错误处理策略。这些信息让 AI 在 function calling 时能正确选择工具并组装参数。

应避免 Prompt 承载过重的业务逻辑。应该让 API 工具承担具体的数据查询与业务动作。但把投诉状态码的含义和操作指引写进系统提示词，可以大幅提高 Agent 对投诉场景的理解准确度——它能自动识别投诉当前处于哪个阶段，主动引导商家选择正确的操作。

提示：Makers 默认提供的会话记忆能力在这种投诉处理场景尤其重要。商家可能先问「有哪些投诉」，再指定某一条查详情，最后要求回应——同一会话中的连续上下文让 Agent 不需要每一轮都重新确认投诉单号，能有效提升操作效率。

三、确认后端业务 API

Agent 要能处理真实的微信投诉，需要调用后端的 REST API。这个后端在 Agent 和微信官方接口之间扮演了两个关键角色：

• AccessToken 管理器：自动获取、缓存、定时刷新微信 AccessToken（提前 5 分钟刷新，40001 错误自动重试），所有接口调用前自动附上有效 Token
• 接口代理层：将 Agent 的通用 REST 请求翻译成微信官方 API 要求的参数格式，处理错误码转换，屏蔽微信 API 的复杂性

后端需要实现以下 6 个端点：

所有接口调用均指向商家自有的后端服务，Agent 并不接管数据主权。这不仅确保了业务逻辑的一致性，更完整继承了原有的身份认证、权限管控及操作审计能力。

涉及微信 Secret 和 AccessToken 的代码全部放在后端，不要暴露到前端或 Agent 的环境变量中。Agent 通过 DATA_API_KEY 鉴权访问后端，而微信的 AppSecret 只有后端知道。这样即使 Agent 的部署环境被意外访问，微信的核心凭证也不会泄露。

四、编写 api-schema.json

Agent 的调用范围受限于 api-schema.json的显式声明。这一机制使得业务系统无需重构成专用框架，仅需通过 Schema 描述既有 HTTP 接口，即可实现 Agent 的即插即用。

为投诉处理场景定义 6 个工具：

{
  "tools": [
    {
      "name": "list_pending_complaints",
      "description": "查询当前待商家处理的投诉列表。返回每个投诉单的编号、时间、类型、内容、状态。当商家询问「有哪些投诉」或「待处理投诉」时调用此工具。",
      "endpoint": "GET /api/complaints/pending",
      "parameters": {}
    },
    {
      "name": "query_complaint_detail",
      "description": "查询指定投诉单的完整详情，包括投诉内容、投诉人信息、商品信息、交易金额、投诉进度历史、退货信息等。当商家提供投诉单号或指定某个投诉时调用。",
      "endpoint": "GET /api/complaints/{complaintOrderId}",
      "parameters": {
        "complaintOrderId": { "type": "string", "description": "投诉单ID", "required": true }
      }
    },
    {
      "name": "respond_complaint",
      "description": "商家回应投诉，同意或拒绝和解。bussiHandle=1表示同意和解，bussiHandle=2表示拒绝和解。执行前需向商家确认意愿。",
      "endpoint": "POST /api/complaints/respond",
      "parameters": {
        "complaintOrderId": { "type": "number", "description": "投诉单号", "required": true },
        "content": { "type": "string", "description": "回应的文字内容（与mediaIdList二选一）" },
        "mediaIdList": { "type": "array", "items": { "type": "string" }, "description": "图片凭证ID列表（与content二选一）" },
        "bussiHandle": { "type": "number", "description": "操作类型：1=同意和解，2=拒绝和解", "required": true }
      }
    },
    {
      "name": "supply_proof",
      "description": "商家补充凭证，向平台提交补充证明材料。适用于投诉状态为「待商家补充凭证」(106)的情况。content和mediaIdList至少传一个。",
      "endpoint": "POST /api/complaints/proof",
      "parameters": {
        "complaintOrderId": { "type": "number", "description": "投诉单号", "required": true },
        "content": { "type": "string", "description": "补充说明的文字内容（与mediaIdList二选一）" },
        "mediaIdList": { "type": "array", "items": { "type": "string" }, "description": "图片凭证ID列表（与content二选一）" }
      }
    },
    {
      "name": "submit_refund_proof",
      "description": "商家提交退款凭证，用于平台判定商责后提交处理凭证。如果涉及退货，需确认是否已收货(acceptReturn)并提供退货单号(returnId)。returnId可通过查询投诉单详情接口获取。",
      "endpoint": "POST /api/complaints/refund",
      "parameters": {
        "complaintOrderId": { "type": "number", "description": "投诉单号", "required": true },
        "content": { "type": "string", "description": "退款说明文字（与mediaIdList二选一）" },
        "mediaIdList": { "type": "array", "items": { "type": "string" }, "description": "退款凭证图片ID列表（与content二选一）" },
        "acceptReturn": { "type": "number", "description": "是否确认收货：1=确认收货，0=拒绝收货（退货状态下必填）" },
        "returnId": { "type": "number", "description": "退货单号，通过查询投诉单详情接口获取（退货状态下必填）" }
      }
    },
    {
      "name": "submit_appeal",
      "description": "商家发起申诉，对平台判定结果提出异议。适用于申诉状态为「待商家申诉」(401)的情况。content和mediaIdList至少传一个。",
      "endpoint": "POST /api/complaints/appeal",
      "parameters": {
        "complaintOrderId": { "type": "number", "description": "投诉单号", "required": true },
        "content": { "type": "string", "description": "申诉理由文字（与mediaIdList二选一）" },
        "mediaIdList": { "type": "array", "items": { "type": "string" }, "description": "申诉凭证图片ID列表（与content二选一）" }
      }
    }
  ]
}

description 字段是模型进行工具路由（Tool Routing）的核心依据。清晰、精确的描述语能显著降低幻觉调用风险——确保 Agent 仅在业务状态匹配时触发接口，并避免在关键交互节点遗漏必要的操作流程。

五、配置 Agent 访问后端 API

Agent 项目需要知道后端服务的地址和鉴权方式：

DATA_API_BASE_URL=https://complaint-api.yourcompany.com/api
DATA_API_KEY=your-secure-api-key-change-this

当 Agent 调用工具时，会把 api-schema.json 里的 endpoint 拼接到 DATA_API_BASE_URL 后面。例如：

// Agent 内部实际调用的完整 URL：
GET  https://complaint-api.yourcompany.com/api/complaints/pending
GET  https://complaint-api.yourcompany.com/api/complaints/WX20240628001
POST https://complaint-api.yourcompany.com/api/complaints/respond

所有请求的 HTTP 头中自动携带：

Authorization: Bearer your-secure-api-key-change-this
Content-Type: application/json

后端会在每个请求中校验这个 API Key，只有匹配时才放行。这种设计的好处是：Agent 侧的部署环境即使被意外访问，暴露的也只是 Agent 的 API Key，而不是微信小程序的 AppSecret 或 AccessToken。微信核心凭证始终在后端的内存和定时任务中管理，不会流出。

六、准备环境变量

生产环境上线前，请确保已为 Agent 和后端申请持久化的域名。切勿直接使用 Makers 自带的临时预览地址（时效仅 3 小时），以免因域名过期导致服务中断。

建议为 Agent 准备一个稳定的自定义域名，例如：

https://complaint-agent.yourcompany.com

登录 EdgeOne Makers 平台，进入左侧导航栏的 「Models」 模块，切换至 「API Key」 选项卡并点击 「创建 API Key」。请为其设定一个便于识别的名称；若 Agent 需长期运行，过期时间请务必选择“永不过期”。创建成功后，系统生成的 sk-xxx...字符串即为 AI_GATEWAY_API_KEY。

返回 「快速开始」 选项卡，在页面下方的示例代码中，提取 baseURL字段后的链接地址，此即 AI_GATEWAY_BASE_URL。

本模板默认配置模型为 deepseek-v4-flash。如需切换至腾讯混元 3.0，请前往 「模型与密钥」 选项卡查询，其模型 ID 为 @makers/hy3-preview，对应环境变量 AI_GATEWAY_MODEL。

最终，请在 Agent 项目中配置以下环境变量：

AI_GATEWAY_API_KEY=sk-xxx......xxx
AI_GATEWAY_BASE_URL=https://ai-gateway.edgeone.link/v1
AI_GATEWAY_MODEL=@makers/hy3-preview
DATA_API_BASE_URL=https://complaint-api.yourcompany.com/api
DATA_API_KEY=your-secure-api-key-change-this

其中：

• DATA_API_BASE_URL：Agent 用来调用后端实现投诉处理能力
• DATA_API_KEY：后端鉴权密钥，需与后端的 complaint.api-key 配置一致
• AI_GATEWAY 相关：Agent 用来调用 AI 大模型

后端也需要相应的环境变量（通过 application.yml 注入）：

wechat:
  appid: wx你的小程序AppID
  secret: 你的小程序Secret
complaint:
  api-key: your-secure-api-key-change-this
edgeone:
  agent-url: https://complaint-agent.yourcompany.com/ai-chat-assistant

七、部署上线

1. 把代码推上去

部署到 EdgeOne Makers 最简单的办法是走 Git。先把整个 Agent 项目初始化并推送到代码仓库：

git init
git add .
git commit -m "微信小程序交易投诉处理 Agent"
git remote add origin https://github.com/你的账号/你的仓库.git
git push -u origin main

部署前需要配置加速区域：如果区域包含中国大陆，腾讯云账号必须完成实名认证，且仅支持已完成 ICP 备案的自定义域名；如果没有中国大陆访问需求，选择「全球可用区（不含中国大陆）」即可。

在部署确认页的环境变量中输入第六步中准备好的 5 个变量，点击「开始部署」，等待构建完成。

2. 挂上自己的域名

由于 Makers 默认分配的预览域名仅具 3 小时临时有效性，建议配置自定义域名以保障服务连续性。请进入项目左侧 「域名管理」 并点击 「添加自定义域名」。

配置过程包含以下两个关键环节：

• CNAME 接入：若域名托管于腾讯云，可直接一键解析；否则需在域名服务商控制台手动添加 CNAME 记录。
• SSL 证书配置：EdgeOne 支持免费证书的自动申请、续签与部署，同时也允许直接托管您现有的腾讯云 SSL 证书。

配置生效后，即可通过该自定义域名（如 https://complaint-agent.yourcompany.com）安全访问 Agent 服务。

3. 运行状态

Agent 上线之后，一个不能忽视的问题出现了：你怎么知道它是不是按你期望的方式在工作？

普通的后端服务出了问题，你通常能看接口日志、查错误堆栈、监控响应时间。但 Agent 的工作链路长得多：用户发一句话 → 模型理解意图 → 决定调用哪个工具 → 工具返回数据 → 模型组织回答。这中间任何一环出了偏差，你只看最后那句回复是判断不出原因的。

Makers 内置的观测面板就是来解决这个问题的。在项目的左侧菜单展开「Agent」一栏，能看到 Metrics 和 Traces 两个视图。

Metrics 给你一个全局视角：Agent 总共被调了多少次、模型被调了多少次、平均响应耗时多少、Token 消耗量有没有异常增长、有没有出现报错。适合每天扫一眼，确认服务整体是否健康。

Traces 则深入到每一次对话的细粒度链路。任意一条对话记录点开，都能看到完整的调用链——这轮对话里模型被请求了几次、分别调了哪个工具、工具入参长什么样、返回了什么数据、每一步花了多少毫秒。如果某一步报错了，错误信息和对应的节点一目了然。

4. 版本管理和快速回滚

Agent 是需要持续打磨的——提示词要调、Schema 要修、甚至可能换个模型试试效果。但每一次改动都等于一次上线，可能会有新问题。

Makers 的构建部署页记录了每一次构建的版本。如果新版本上线后发现 Agent 的回复质量变差，或者某个接口开始报错，可以直接在构建记录里找到上一个稳定的版本，点击回滚——服务会立刻切回到上一个版本的代码。运营人员那边完全无感，等排查完新版本的问题，修好之后再重新发布，也不会影响已经回滚的线上服务。

触发新构建的方式有两种。如果你走的是 Git 仓库模式，每次往 main 分支 push 新代码，Makers 会自动感知并开始构建，不需要手动操作。如果代码是本地直接上传到 Makers 的，那就需要去构建部署页手动点击新建部署，上传新的代码包。

这种设计让 Agent 变成一个可以持续迭代的活系统，而不是一次部署之后就不敢再碰的静态产物。

5. 接入微信小程序商家后台

Agent 部署完成后，接入现有微信小程序商家管理后台非常简单。有两种方式：

Web 端后台 — iframe 嵌入

<iframe
  src="https://complaint-agent.yourcompany.com/widget"
  width="420"
  height="700"
  frameborder="0"
  allow="clipboard-write">
</iframe>

小程序端 — web-view 组件

<web-view
  src="https://complaint-agent.yourcompany.com/widget"
  bindmessage="onAgentMessage">
</web-view>

或者使用 embed.js 浮动按钮方式（Web 端）：

<script src="https://complaint-agent.yourcompany.com/embed.js" async></script>

关于会话 ID：如果希望同一个商家在不同页面和设备上保持同一段对话，可以在加载 embed.js 或设置 iframe URL 时传入预先生成的 conversationId 作为参数。Makers 的会话管理会自动维持上下文。

最后

回头来看，整个方案没有对现有的小程序业务做任何伤筋动骨的改造。微信的投诉接口该怎么用还怎么用，小程序前端该怎么运行还怎么运行，商家后台的数据和权限体系纹丝不动。Agent 被设计成一个轻量的外挂层——它通过后端的安全代理去触碰微信接口，通过 embed.js 嵌入到运营人员日常工作的界面里，通过自然语言对话来消除投诉处理中的机械操作。

对于已经有一套成熟微信小程序业务的团队来说，这种方式提供了几个实实在在的好处：一是改造成本低，不需要重构已有的任何系统；二是边界分明，Agent 出了问题不会影响核心交易流程，核心系统改了也不会波及 Agent；三是安全可控，微信的 AppSecret 始终锁在 J后端的围墙内。

这也恰好是 EdgeOne Makers 这种平台最有价值的地方：它不限制你用什么语言写业务后端，不强制你用某一家模型供应商，也不会要求你一定要使用某个 Agent 框架。它把 Agent 开发中最磨人的那些环节——模型调用、工具触发、上下文记忆、沙箱运行、调用链追踪和持续部署——全部做成了平台能力。留给开发者的，是真正值得花时间思考的事情：业务场景怎么被 AI 理解得更好、运营人员最难受的操作步骤到底是什么、怎样让 Agent 不只是"能调用接口"，而是"知道什么时候该调用哪个接口"。

谢谢你看我的文章，既然看到这里了，如果觉得不错，随手点个赞、转发、在看三连吧，感谢感谢。那我们，下次再见。

您的一键三连，是我更新的最大动力，谢谢

山水有相逢，来日皆可期，谢谢阅读，我们再会

我手中的金箍棒，上能通天，下能探海