企业微信 AI Bot

企业微信 AI Bot 使用企业微信的流式API，为用户提供打字机效果的实时对话体验。

为什么选择 AI Bot

AI Bot vs 传统应用

特性	AI Bot (推荐)	传统应用
响应方式	逐字流式显示⚡	一次性返回全部
用户体验	打字机效果，实时反馈	等待时间较长
配置复杂度	简单	中等

推荐使用 AI Bot 提供更好的用户体验！

前置要求

1. 创建企业微信 AI Bot

登录企业微信管理后台：

应用管理 → AI Bot → 创建 AI Bot
填写信息：
- Bot 名称：例如 "智能助手"
- Bot 简介：功能说明
- 可见范围：选择使用人员
创建成功

2. 获取配置参数

在 AI Bot 详情页获取：

参数	说明	示例
AI Bot ID (aibot_id)	Bot 唯一标识	`aibXXXXXXXXXXXXXXX`
Token	回调验证Token	自定义8-32位字符串
EncodingAESKey	消息加解密密钥	43位Base64字符串

可选配置

如需获取用户姓名、部门等详细信息，还需配置：

企业ID (corp_id)
企业密钥 (corp_secret)

创建 Application

1. 进入应用管理

Agent System → 应用管理 → 创建应用

2. 填写基础信息

应用名称：wework_aibot_assistant（系统标识符）
显示名称：智能助手（用户可见名称）
描述：简要说明功能

3. 选择平台类型

选择：企业微信 (AI Bot) 🤖

4. 选择 Orchestrator

从下拉列表选择已创建的 Orchestrator。

提醒

必须先创建 Orchestrator。如果列表为空，请前往 Orchestrator 教程。

5. 配置 AI Bot 参数

必填参数

字段	说明
AI Bot ID (aibot_id)	从企业微信获取的 Bot ID
回调Token (token)	自定义字符串（8-32位）
EncodingAESKey	43位加解密密钥

EncodingAESKey 生成

在企业微信后台点击"随机生成"按钮获取43位密钥。

可选参数（用于获取用户信息）

字段	说明	用途
企业ID (corp_id)	企业唯一标识	调用API获取用户信息
企业密钥 (corp_secret)	应用密钥	获取用户姓名、部门等
API地址 (api_base_url)	可选，私有化部署时填写	默认使用公有云

上下文增强

配置 corp_id 和 corp_secret 后，系统会自动获取用户的姓名、部门等信息，并注入到 Agent 的上下文中，可在系统提示词中使用 {{user_name}}、{{user_department}} 等变量。

高级选项

欢迎语：用户首次对话时的开场白
启用流式回复：默认开启，提供打字机效果
启用模板卡片：使用企业微信卡片样式

6. 保存应用

点击创建，系统自动生成回调地址。

配置企业微信

1. 复制回调地址

在应用卡片中找到回调地址，点击复制📋：

https://your-domain.com/api/agent-system/callback/wework-aibot/{application_id}

2. 配置 AI Bot

返回企业微信 AI Bot 详情页：

回调配置 → 设置回调
填写：
- URL：粘贴回调地址
- Token：与 Sira AI 配置一致
- EncodingAESKey：与 Sira AI 配置一致
保存

3. 验证配置

企业微信会发送验证请求：

✅ 验证成功：提示"配置成功"
❌ 验证失败：
- 检查回调地址是否可公网访问
- 确认 Token 和密钥一致
- 查看 Sira AI 后台日志

HTTPS 必需

回调地址必须是 HTTPS 并支持公网访问。

流式响应流程

为什么 AI Bot 走 Redis Stream

企业微信 AI Bot 的回调机制要求：每次刷新调用必须在 5 秒 内返回当前累积内容，否则会断开。所以 AI Bot 渠道必须把编排器输出实时写到 Redis Stream，由刷新回调按需拉取——而不能直接 SSE 流给企微。

平台另外还有一条更高性能的"直接 yield 模式"（execute_streaming_direct），用于 OpenAI / LangGraph 兼容 API 这类长连接 SSE 客户端，相比 Redis 中转节省约 50% 延迟。两条路径在同一引擎里共存，按调用方自动选择，详见 API Service。

消息流转

mermaid

sequenceDiagram
    participant U as 用户
    participant W as 企业微信
    participant S as Sira AI
    participant R as Redis Stream
    participant O as Orchestrator

    U->>W: 发送消息
    W->>S: POST 回调 (加密)
    S->>S: 解密消息
    S->>O: 启动流式执行
    O->>R: 写入流式内容

    loop 流式刷新
        W->>S: 请求刷新 (msgtype=stream)
        S->>R: 读取累积内容
        R-->>S: 返回当前内容
        S->>S: 加密响应
        S-->>W: 返回流式内容
        W-->>U: 逐字显示
    end

    O->>R: 写入 done 标记
    W->>S: 最后一次刷新
    S-->>W: finish=true
    W-->>U: 显示完成

响应格式

初始响应（启动流式）：

json

{
  "msgtype": "stream",
  "stream": {
    "id": "session_id",
    "finish": false,
    "content": ""
  }
}

刷新响应（返回累积内容）：

json

{
  "msgtype": "stream",
  "stream": {
    "id": "session_id",
    "finish": false,
    "content": "已累积的完整内容..."
  }
}

完成响应：

json

{
  "msgtype": "stream",
  "stream": {
    "id": "session_id",
    "finish": true,
    "content": "完整回复内容"
  }
}

测试 AI Bot

1. 添加可见范围

在企业微信 AI Bot 详情页：

可见范围 → 添加成员
将自己添加进去

2. 发送测试消息

在企业微信客户端：

打开工作台
找到刚创建的 AI Bot
发送："你好"

3. 查看效果

正常情况下，应该看到：

AI 回复逐字显示（打字机效果）
流畅的对话体验

4. 调试问题

如无响应，检查：

应用是否激活
Orchestrator 和 Agent 是否正常
查看日志：docker compose logs backend | grep "AI Bot"

多模态支持

AI Bot 原生支持图片和文件：

支持的消息类型：

文本消息
图片消息（企业微信图片、微盘图片）
文本中的图片链接（自动检测）
混合消息（图文混排）

使用要求：

Agent 使用支持 Vision 的模型（如 GPT-4o、Claude 3）
查看多模态文档了解详情

上下文增强

配置 corp_id 和 corp_secret 后，系统会自动获取用户信息并注入上下文：

可用变量

变量	说明	示例
`{{user_id}}`	用户ID	zhangsan
`{{user_name}}`	用户姓名	张三
`{{user_department}}`	所属部门	研发部
`{{user_position}}`	职位	工程师
`{{chat_type}}`	聊天类型	single / group

在系统提示词中使用

markdown

你是企业客服助手。

当前用户信息：
- 姓名：{{user_name}}
- 部门：{{user_department}}
- 职位：{{user_position}}

请根据用户身份提供个性化服务。

详见模板变量文档。

常见问题

回调验证失败

排查：

回调地址是否支持 HTTPS
Token 和 EncodingAESKey 是否一致（注意43位长度）
查看日志：docker compose logs backend | grep "AI Bot回调验证"

消息无响应

排查：

应用是否激活
Orchestrator 是否正确配置
Agent 的 LLM 模型是否正常
查看流式执行日志

流式显示不正常

可能原因：

网络延迟导致刷新间隔过长
Redis Stream 未正确写入
企业微信客户端版本过低

解决：

检查网络连接
查看 Redis 日志
升级企业微信客户端至最新版

图片消息无法识别

排查：

确认 Agent 使用的模型支持 Vision（如 GPT-4o）
检查图片是否可访问（企业微信图片需要通过 media_id 下载）
查看多模态文档

下一步

多模态支持 - 处理图片和文件
模板变量 - 动态上下文注入
Orchestrator 配置 - 编排多 Agent 协作
Agent 配置 - 优化 Agent 行为

相关文档：

企业微信 AI Bot ​

为什么选择 AI Bot ​

前置要求 ​

1. 创建企业微信 AI Bot ​

2. 获取配置参数 ​

创建 Application ​

1. 进入应用管理 ​

2. 填写基础信息 ​

3. 选择平台类型 ​

4. 选择 Orchestrator ​

5. 配置 AI Bot 参数 ​

必填参数 ​

可选参数（用于获取用户信息） ​

高级选项 ​

6. 保存应用 ​

配置企业微信 ​

1. 复制回调地址 ​

2. 配置 AI Bot ​

3. 验证配置 ​

流式响应流程 ​

消息流转 ​

响应格式 ​

测试 AI Bot ​

1. 添加可见范围 ​

2. 发送测试消息 ​

3. 查看效果 ​

4. 调试问题 ​

多模态支持 ​

上下文增强 ​

可用变量 ​

在系统提示词中使用 ​

常见问题 ​

回调验证失败 ​

消息无响应 ​

流式显示不正常 ​

图片消息无法识别 ​

下一步 ​

企业微信 AI Bot

为什么选择 AI Bot

前置要求

1. 创建企业微信 AI Bot

2. 获取配置参数

创建 Application

1. 进入应用管理

2. 填写基础信息

3. 选择平台类型

4. 选择 Orchestrator

5. 配置 AI Bot 参数

必填参数

可选参数（用于获取用户信息）

高级选项

6. 保存应用

配置企业微信

1. 复制回调地址

2. 配置 AI Bot

3. 验证配置

流式响应流程

消息流转

响应格式

测试 AI Bot

1. 添加可见范围

2. 发送测试消息

3. 查看效果

4. 调试问题

多模态支持

上下文增强

可用变量

在系统提示词中使用

常见问题

回调验证失败

消息无响应

流式显示不正常

图片消息无法识别

下一步