开发指南

本文介绍如何将 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 Agent
createWxMessageHandler - 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 || "deepseek-v4-flash",
    apiKey: process.env.TCB_API_KEY,
    configuration: {
      baseURL: `https://${process.env.TCB_ENV_ID}.api.tcloudbasegateway.com/v1/ai/cloudbase`,
    },
  });

  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. "继续"命令

用户可以发送"继续"获取上次未完成的回复。

前置准备​

1. 创建 Agent​

2. Agent 改造​

快速开始​

架构​

步骤 1: 安装​

步骤 2: 环境变量​

步骤 3: 创建基础 Agent​

步骤 4: 包装为 WeChatAgent​

配置项​

步骤 5: 注册路由​

createWxMessageHandler 功能​

支持的平台​

完整示例​

项目结构​

agent.js - 基础 Agent​

wechat-agent.js - 微信适配器​

index.js - 入口文件​

package.json​

配置微信平台​