快速开始
本文介绍如何将 Agent 对接到微信平台（小程序、公众号、企业微信），实现在微信生态中使用 AI Agent。
前置准备
1. 创建 Agent
首先需要在云开发控制台创建一个 Agent：
- 进入云开发控制台
- 选择「AI」
- 点击「创建 Agent」
- 选择「已有服务」或「新建服务」
- 完成创建，获得 Agent ID（格式：
agent-xxx）
2. Agent 改造
为了支持微信平台对接，需要对 Agent 进行改造，使其能够处理微信平台的消息格式。
快速开始
@cloudbase/agent-adapter-wx 负责接收微信平台回调数据，转换为 AG-UI 协议发送到 Agent，并将 Agent 响应发送回微信平台。
导出：
WeChatAgent- Agent 适配器，包装任意 AG-UI AgentcreateWxMessageHandler- Express 路由处理器
架构
┌─────────────────┐ ┌─────────────────────────┐ ┌─────────────────┐
│ 微信服务器 │────▶│ createWxMessageHandler │────▶│ WeChatAgent │
└─────────────────┘ └─────────────────────────┘ └────────┬────────┘
│
▼
┌─────────────────┐
│ Base Agent │
│ (AG-UI) │
└─────────────────┘
步骤 1: 安装
pnpm add @cloudbase/agent-adapter-wx
步骤 2: 环境变量
# 必需：CloudBase 环境 ID
ENV_ID=your-cloudbase-env-id
# 可选
LOG_LEVEL=info
ENABLE_CORS=true
步骤 3: 创建基础 Agent
创建任意符合 AG-UI 协议的 Agent。以下示例使用 LangChain，你也可以使用其他框架：
import { LangchainAgent } from "@cloudbase/agent-adapter-langchain";
import { createAgent as createLangchainAgent } from "./agent.js";
import { v4 as uuidv4 } from "uuid";
const createAgent = ({ request }) => {
const lcAgent = createLangchainAgent();
return {
agent: new LangchainAgent({ agent: lcAgent }).use((input, next) => {
return next.run(
typeof input.threadId === "string"
? input
: { ...input, threadId: uuidv4() }
);
}),
};
};
步骤 4: 包装为 WeChatAgent
WeChatAgent 包装任意 AG-UI Agent，提供以下功能：
- 消息发送 - 将 Agent 响应自动发送到微信（异步模式）
- 历史记录 - 自动保存用户输入和 AI 回复到 CloudBase 数据库
- 重试处理 - 处理微信 11 秒重试逻辑
- "继续"命令 - 支持用户发送"继续"获取上次回复
import { WeChatAgent, WeChatHistoryManager } from '@cloudbase/agent-adapter-wx';
function createWxAgent({ request, options }) {
const { agent: baseAgent } = createAgent({ request });
return {
agent: new WeChatAgent({
agentId: options?.agentId || 'my-wechat-bot',
agent: baseAgent,
wechatConfig: {
sendMode: 'aitools',
context: {
extendedContext: {
envId: process.env.ENV_ID,
accessToken: request.headers.authorization,
}
}
},
historyManager: new WeChatHistoryManager({
envId: process.env.ENV_ID,
})
})
};
}
配置项
| 配置项 | 类型 | 说明 |
|---|---|---|
agentId | string | Bot 标识，用于路由和历史记录隔离 |
agent | AbstractAgent | 任意 AG-UI 兼容的 Agent |
sendMode | 'aitools' | 消息发送模式（云函数环境） |
historyManager | WeChatHistoryManager | 聊天历史存储（CloudBase 数据库） |
步骤 5: 注册路由
需要同时注册两个路由：
import express from "express";
import { createWxMessageHandler } from '@cloudbase/agent-adapter-wx';
const app = express();
app.use(express.json());
app.post('/wx-send-message', createWxMessageHandler(createWxAgent));
app.post('/v1/aibot/bots/:agentId/wx-send-message', createWxMessageHandler(createWxAgent));
app.listen(9000);
createWxMessageHandler 功能
- 微信回调数据解析与校验
- 平台识别（小程序 / 公众号 / 企业微信）
- 同步/异步回复模式处理
- 语音消息转文字
支持的平台
| 平台 | 枚举值 | 回复模式 |
|---|---|---|
| 微信小程序 | WXMiniapp | 始终异步 |
| 微信服务号 | WXService | 同步（已认证）/ 异步（未认证） |
| 微信订阅号 | WXSubscription | 同步（已认证）/ 异步（未认证） |
| 企业微信客服 | WXCustomerService | 始终异步 |
完整示例
项目结构
my-wechat-agent/
├── index.js # 入口文件
├── agent.js # Agent 逻辑
├── wechat-agent.js # 微信适配器
└── package.json # 依赖配置
agent.js - 基础 Agent
import { createAgent as createLangchainAgent } from "langchain";
import { MemorySaver } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";
import { clientTools } from "@cloudbase/agent-adapter-langchain";
const checkpointer = new MemorySaver();
export function createLcAgent() {
const model = new ChatOpenAI({
model: process.env.TCB_AI_MODEL || "hunyuan-turbos-latest",
apiKey: process.env.TCB_API_KEY,
configuration: {
baseURL: `https://${process.env.TCB_ENV_ID}.api.tcloudbasegateway.com/v1/ai/hunyuan-exp/v1`,
},
});
return createLangchainAgent({
model,
checkpointer,
middleware: [clientTools()],
});
}
wechat-agent.js - 微信适配器
import { LangchainAgent } from "@cloudbase/agent-adapter-langchain";
import { WeChatAgent, WeChatHistoryManager } from '@cloudbase/agent-adapter-wx';
import { createLcAgent } from "./agent.js";
import { v4 as uuidv4 } from "uuid";
export function createWxAgent({ request, options }) {
// 创建基础 Agent
const lcAgent = createLcAgent();
const baseAgent = new LangchainAgent({ agent: lcAgent }).use((input, next) => {
return next.run(
typeof input.threadId === "string"
? input
: { ...input, threadId: uuidv4() }
);
});
// 包装为微信 Agent
return {
agent: new WeChatAgent({
agentId: options?.agentId || 'agent-xxx',
agent: baseAgent,
wechatConfig: {
sendMode: 'aitools',
context: {
extendedContext: {
envId: process.env.ENV_ID,
accessToken: request.headers.authorization,
}
}
},
historyManager: new WeChatHistoryManager({
envId: process.env.ENV_ID,
})
})
};
}
index.js - 入口文件
import express from "express";
import { createWxMessageHandler } from '@cloudbase/agent-adapter-wx';
import { createWxAgent } from './wechat-agent.js';
const app = express();
app.use(express.json());
// 注册微信消息处理路由
app.post('/wx-send-message', createWxMessageHandler(createWxAgent));
app.post('/v1/aibot/bots/:agentId/wx-send-message', createWxMessageHandler(createWxAgent));
// 云函数入口
export const main = app;
// 本地开发
if (process.env.NODE_ENV !== 'production') {
app.listen(9000, () => {
console.log('Server running on http://localhost:9000');
});
}
package.json
{
"name": "my-wechat-agent",
"version": "1.0.0",
"type": "module",
"main": "index.js",
"dependencies": {
"@cloudbase/agent-adapter-wx": "latest",
"@cloudbase/agent-adapter-langchain": "latest",
"langchain": "latest",
"@langchain/openai": "latest",
"@langchain/langgraph": "latest",
"express": "latest",
"uuid": "latest"
}
}
配置微信平台
完成代码改造后，需要在微信平台进行配置。根据不同的微信平台类型，配置方式有所不同：
📄️ 对接公众号
配置微信公众号（服务号/订阅号）接入 Agent
📄️ 对接小程序客服
配置微信小程序客服接入 Agent
📄️ 对接企微客服
配置企业微信客服接入 Agent
📄️ 对接微信服务器
配置微信服务器接入 Agent
功能特性
1. 自动消息发送
Agent 响应会自动发送到微信平台，无需手动调用发送接口。
2. 聊天历史管理
所有对话历史自动保存到 CloudBase 数据库，支持：
- 用户输入记录
- AI 回复记录
- 会话上下文保持
3. 重试处理
自动处理微信 11 秒重试逻辑：
- 首次请求：返回"正在处理"
- 重试请求：返回实际回复或继续等待
4. "继续"命令
用户可以发送"继续"获取上次未完成的回复。