Application 接入指南

Application（应用）是用户与 AI 系统交互的入口。本指南详细讲解如何配置 4 种平台的 Application。

Application 是什么？

Application 连接用户和 Orchestrator：

用户 → Application (平台适配) → Orchestrator (编排) → Agent (执行) → LLM

支持的平台

平台是插件化的——核心代码不变，新增渠道只需安装对应包。当前支持：

平台	说明	适用场景	流式支持
企业微信 AI Bot	企业微信 2023+ 新 API	企业内部使用	✅ Redis Stream 模式
企业微信 (Plugin)	wecom Channel Plugin（WebSocket 长连接）	企业内部使用	✅
企业微信传统应用	企业微信旧版回调	兼容旧系统	❌ 不支持
飞书机器人 🆕	Lark / Feishu 自建机器人	飞书生态用户	⚠️ 缓冲后单次推送
钉钉机器人（已启用）	钉钉企业机器人（Stream 长连接，标准版 / 专属钉）	钉钉生态用户	✅
微信客服 🆕	微信客服 API	客服 / 公众号场景	⚠️ 客服转人工口径
Web Chat Client	独立 Web 聊天界面	公开访问、嵌入网站	✅ 直接 yield 模式
OpenAI 兼容 API	`/v1/chat/completions`	开发者集成 / SDK	✅ 直接 yield 模式
LangGraph 兼容 API 🆕	`/assistants/.../runs/stream`	LangGraph SDK / LangSmith	✅ 直接 yield 模式
Webhook 触发器 🆕	`/api/applications/{id}/webhook`	外部系统 HTTP POST 触发工作流	— 即发即忘（异步）

"直接 yield 模式" 比 "Redis Stream 模式" 延迟约低 50%。AI Bot 因为受 5 秒回调超时约束必须走 Redis Stream，其他渠道走直接 yield。详见 API Service。

**企业微信当前推荐用 wecom Plugin（WebSocket 长连接）**接入；旧的回调 / AI Bot 模式仍保留兼容。

Webhook 触发器：外部系统发一次 HTTP POST 即可触发背后的工作流。默认即发即忘（异步），加 ?wait=true 可同步等待结果；调用须带 X-Webhook-Secret 头鉴权，并可选开启 HMAC 签名校验（高安全）。Secret 由后端自动生成、可轮换，用户不手填。

⚠️ Webhook / 钉钉 / 飞书等异步投递失败的任务会落到失败队列(DLQ)（操作手册 01-agent-system §1.1.6 / 页面 /agent-system/dlq），可在那里查看错误详情并手动重试 / 放弃。

渠道总览与跨渠道用户解析见渠道接入。

Application 的作用

平台适配：处理不同平台的消息格式
会话管理：管理用户会话和上下文
认证授权：控制访问权限
流式响应：实时推送 AI 回复
多模态处理：处理文本、图片等内容

企业微信 AI Bot

概述

企业微信 2023+ 推出的新一代 AI Bot API，支持流式响应和打字机效果。

优势：

✅ 流式响应（打字机效果）
✅ 图文混排
✅ 原生体验好
✅ 企业内部安全

限制：

❌ 需要企业微信2023+
❌ 需要开通AI Bot权限

前置准备

1. 企业微信要求

企业微信版本 ≥ 4.0
企业认证（完成实名认证）
开通 AI Bot API 权限

2. 创建应用

在企业微信管理后台：

进入 应用管理 → 自建
点击 创建应用
填写应用信息：
- 应用名称：客服助手
- 应用logo：上传图片
- 可见范围：选择部门/成员
获取应用配置：
- Corp ID：企业ID（在"我的企业"中查看）
- Agent ID：应用ID（应用详情页）
- Agent Secret：应用密钥（应用详情页）

3. 配置回调

在应用管理页面：

点击 接收消息 → 设置API接收

填写配置：

yaml

URL: https://your-domain.com/api/wxwork/aibot/callback
Token: 随机生成（32位字符串）
EncodingAESKey: 随机生成（43位字符串）

点击保存
测试回调（企业微信会发送验证请求）

4. 开启 AI Bot API

在应用管理页面：

找到 AI能力
开启 智能问答
选择 自定义接入

创建 Application

步骤 1：进入 Application 管理

点击 Agent System → Applications
点击 创建 Application

步骤 2：选择平台

选择：WeChat Work AI Bot

步骤 3：配置基本信息

yaml

名称: wework_customer_service
显示名称: 企微客服助手
描述: 企业微信AI客服
平台: wework_aibot
Orchestrator: 选择已创建的 Orchestrator

步骤 4：配置平台参数

yaml

Corp ID: ww1234567890abcdef
Agent ID: 1000002
Agent Secret: xxx_secret_xxx
Token: xxx_callback_token_xxx
Encoding AES Key: xxx_aes_key_xxx

步骤 5：保存并启用

点击保存
状态切换为启用

测试

方法 1：企业微信测试

在企业微信中找到应用
发送测试消息："你好"
观察AI实时回复（打字机效果）

方法 2：日志查看

bash

# 查看后端日志
docker logs backend | grep wxwork

# 查看回调请求
[INFO] 收到企业微信消息: user_id=xxx, message=你好
[INFO] 路由到 Orchestrator: wework_customer_service
[INFO] 流式推送: 10 chunks
[INFO] 响应完成: 耗时 3.2s

多模态支持

发送图片

用户操作：

在企业微信对话框点击"+"
选择"图片"
发送图片
（可选）输入文字说明

系统处理：

yaml

1. 接收图片消息:
   - 获取 MediaID
   - 下载图片（调用企业微信API）
   - 解密图片

2. 构建 multimodal_content:
   text: 用户输入的文字（如有）
   image_urls: [下载后的图片URL]

3. 传递给 Orchestrator:
   - multimodal_content 包含图片信息
   - Agent 使用 Vision 模型分析

示例对话：

用户: [发送架构图] "帮我分析这个系统架构"
AI: 正在分析图片...
    这是一个微服务架构，包含以下组件：
    1. API网关...
    2. 服务注册中心...
    3. ...

常见问题

Q1: 回调验证失败

排查步骤：

确认 URL 可公网访问
检查 Token 和 EncodingAESKey 配置正确
查看企业微信管理后台的错误信息
查看后端日志

bash

# 测试回调URL
curl -X GET "https://your-domain.com/api/wxwork/aibot/callback?msg_signature=xxx&timestamp=xxx&nonce=xxx&echostr=xxx"

Q2: 消息发送失败

常见原因：

Agent Secret 错误
Agent ID 错误
用户不在应用可见范围
企业微信API限流

解决方案：

bash

# 测试API访问
curl -X POST "https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=xxx" \
  -d '{"touser":"xxx", "msgtype":"text", "agentid":1000002, "text":{"content":"test"}}'

Q3: 流式响应不工作

检查清单：

[ ] Redis 正常运行
[ ] AI Bot API 已开启
[ ] 企业微信版本 ≥ 4.0
[ ] 后端日志无错误

Q4: 图片分析失败

常见原因：

Agent 未配置 VISION 模型类型
图片下载失败
图片格式不支持

解决方案：

检查 Agent 配置：model_types: [LLM, VISION]
查看后端日志确认图片下载成功
测试图片URL可访问性

企业微信传统应用

概述

企业微信旧版应用回调模式，不支持流式响应。

优势：

✅ 兼容旧版企业微信
✅ 配置简单
✅ 稳定可靠

限制：

❌ 不支持流式响应
❌ 用户体验较差（等待时间长）
❌ 建议升级到 AI Bot

创建步骤

配置与 AI Bot 类似，但：

yaml

平台选择: wework_traditional

配置差异:
  - 无需开启 AI Bot API
  - 回调URL: /api/wxwork/traditional/callback
  - 不支持流式响应

响应方式

yaml

AI Bot (流式):
  用户: "介绍一下产品"
  AI: "这" → "款" → "产品" → ... (逐字显示)

传统应用 (非流式):
  用户: "介绍一下产品"
  AI: ... 等待 5 秒 ...
      "这款产品是..." (一次性显示完整响应)

Web Chat Client

概述

独立的 Web 聊天界面，可嵌入网站或作为独立页面。

优势：

✅ 流式响应
✅ 公开访问（无需企业微信）
✅ 可自定义样式
✅ 可嵌入网站

适用场景：

官网客服
产品咨询
技术支持
演示和测试

创建步骤

步骤 1：创建 Application

yaml

平台: webclient
名称: web_customer_service
显示名称: 在线客服

平台配置:
  自动生成访问令牌: ✓

步骤 2：获取访问链接

保存后，系统自动生成：

访问链接: http://localhost:3000/app-chat/{token}
Token: abc123xyz...

步骤 3：访问测试

在浏览器打开访问链接：

http://localhost:3000/app-chat/abc123xyz

看到聊天界面 → 输入消息 → 观察流式响应

界面配置

自定义标题和欢迎语

yaml

配置:
  标题: 在线智能客服
  欢迎语: 您好！我是智能客服助手，有什么可以帮您？
  占位符: 请输入您的问题...

样式自定义（高级）

编辑前端代码：

typescript

// frontend-nextjs/src/app/app-chat/[token]/page.tsx

export default function ChatPage({ params }: { params: { token: string } }) {
  return (
    <div className="custom-chat-container">
      {/* 自定义聊天界面 */}
    </div>
  );
}

嵌入网站

方法 1：iframe 嵌入

html

<iframe
  src="http://localhost:3000/app-chat/abc123xyz"
  width="400"
  height="600"
  frameborder="0"
></iframe>

方法 2：弹窗模式

html

<button onclick="openChat()">联系客服</button>

<script>
function openChat() {
  window.open(
    'http://localhost:3000/app-chat/abc123xyz',
    'chat',
    'width=400,height=600'
  );
}
</script>

方法 3：组件集成

typescript

import ChatWidget from '@/components/ChatWidget';

export default function HomePage() {
  return (
    <div>
      <ChatWidget token="abc123xyz" />
    </div>
  );
}

多模态支持

发送图片链接

用户在输入框输入图片URL：

用户: "分析图片 http://example.com/chart.png"
系统: 自动检测图片URL
     → 构建 multimodal_content
     → 传递给支持 Vision 的 Agent
     → 返回图片分析结果

图片检测规则

支持的格式：

yaml

直接URL:
  http://example.com/image.jpg
  https://cdn.example.com/image.png

Markdown:
  ![图片](http://example.com/image.jpg)

HTML:
  <img src="http://example.com/image.jpg">

安全配置

CORS 配置

后端配置允许的域名：

python

# backend-python-mvp/app/main.py

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:3000",
        "https://your-domain.com"
    ],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Token 安全

yaml

Token 特点:
  - 随机生成（UUID）
  - 绑定 Application
  - 可随时重新生成
  - 无需额外认证

建议:
  - 定期更换 Token
  - 不要在公开场所泄露
  - 可为不同场景生成多个 Token

常见问题

Q1: 流式响应不显示

检查清单：

[ ] 浏览器支持 EventSource（现代浏览器都支持）
[ ] 查看浏览器 Console 是否有错误
[ ] 查看 Network 标签，SSE 连接是否建立
[ ] 后端 Redis 是否正常

Q2: Token 失效

原因：

Application 被删除
Token 被重新生成

解决：

使用新的访问链接

Q3: 跨域问题

错误：

Access to XMLHttpRequest at 'http://localhost:8000/api/...'
from origin 'http://localhost:3000' has been blocked by CORS policy

解决：配置后端 CORS（见上文"安全配置"）

OpenAI API

概述

提供兼容 OpenAI API 的接口，方便开发者集成。

优势：

✅ 标准化接口
✅ 兼容 OpenAI SDK
✅ 流式响应支持
✅ 易于集成

适用场景：

应用集成
第三方工具
自定义客户端
批量处理

创建步骤

步骤 1：创建 Application

yaml

平台: api_service
名称: api_customer_service
显示名称: API服务

平台配置:
  API Key 前缀: app-  # 自动生成 app-xxx

步骤 2：获取 API Key

保存后，系统生成：

API Key: app-1234567890abcdef

⚠️ 重要：保存 API Key，后续无法查看。

API 使用

Endpoint

POST /api/agent-system/openai/chat/completions

请求示例

Python (OpenAI SDK)：

python

from openai import OpenAI

client = OpenAI(
    api_key="app-1234567890abcdef",
    base_url="http://localhost:8000/api/agent-system/openai"
)

response = client.chat.completions.create(
    model="default",  # 固定值，实际模型由 Agent 配置决定
    messages=[
        {"role": "user", "content": "你好"}
    ],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

curl：

bash

curl -X POST http://localhost:8000/api/agent-system/openai/chat/completions \
  -H "Authorization: Bearer app-1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [
      {"role": "user", "content": "你好"}
    ],
    "stream": true
  }'

Node.js：

javascript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'app-1234567890abcdef',
  baseURL: 'http://localhost:8000/api/agent-system/openai',
});

async function chat() {
  const stream = await client.chat.completions.create({
    model: 'default',
    messages: [{ role: 'user', content: '你好' }],
    stream: true,
  });

  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content || '');
  }
}

chat();

多模态支持

发送图片

python

response = client.chat.completions.create(
    model="default",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What's in this image?"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "http://example.com/image.jpg"
                    }
                }
            ]
        }
    ]
)

高级功能

会话管理

使用 user 字段标识用户：

python

response = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "我叫张三"}],
    user="user_12345"  # 用户标识
)

# 后续对话
response = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "我叫什么名字？"}],
    user="user_12345"  # 同一用户，能记住上下文
)

自定义参数

python

response = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "写一首诗"}],
    temperature=0.9,  # 创造性
    max_tokens=500,   # 最大长度
    top_p=1.0
)

API 文档

访问自动生成的 API 文档：

http://localhost:8000/docs

在 Swagger UI 中测试 API：

点击 /api/agent-system/openai/chat/completions
点击 Try it out
填写请求参数
点击 Execute

常见问题

Q1: 认证失败

错误：

json

{"detail": "Invalid API key"}

排查：

检查 API Key 是否正确
检查 Authorization Header 格式：Bearer app-xxx
确认 Application 已启用

Q2: 流式响应解析

Python：

python

# ✅ 正确
for chunk in response:
    print(chunk.choices[0].delta.content, end="")

# ❌ 错误（会等待全部完成）
print(response.choices[0].message.content)

JavaScript：

javascript

// ✅ 正确
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

// ❌ 错误
const response = await stream;  // 流不能 await

Q3: 模型参数不生效

OpenAI API 的某些参数会被 Agent 配置覆盖：

yaml

优先级:
  Agent 配置 > API 请求参数

示例:
  Agent temperature: 0.3
  API temperature: 0.9
  → 实际使用: 0.3 (Agent 配置优先)

平台选择指南

使用场景对比

场景	推荐平台	理由
企业内部客服	企业微信 AI Bot	员工已有企业微信，原生体验好
官网客服	Web Client	公开访问，可嵌入网站
开发者集成	OpenAI API	标准化接口，易于集成
兼容旧系统	企业微信传统应用	兼容旧版企业微信
多平台部署	全部	一个 Orchestrator 配置多个 Application

功能对比

功能	企微AI Bot	企微传统	Web Client	OpenAI API
流式响应	✅	❌	✅	✅
多模态	✅	✅	✅	✅
公开访问	❌	❌	✅	✅
企业安全	✅	✅	⚠️	⚠️
易于集成	⚠️	⚠️	✅	✅
自定义UI	❌	❌	✅	✅

成本对比

yaml

企业微信 AI Bot:
  优点: 无额外成本（已有企业微信）
  缺点: 需要企业微信权限

Web Client:
  优点: 无需第三方平台
  缺点: 需要维护前端

OpenAI API:
  优点: 标准化，易于集成
  缺点: 需要开发客户端

多平台部署

一个 Orchestrator，多个 Application

yaml

场景: 客服系统

Orchestrator: customer_service
  - Agent: customer_service_agent
  - 模式: Single

Applications:
  1. wework_aibot_app (企业微信 AI Bot)
     → 企业内部员工使用

  2. web_client_app (Web Client)
     → 官网访客使用

  3. api_service_app (OpenAI API)
     → 第三方系统集成

优势:
  - 统一的 AI 能力
  - 集中管理和优化
  - 降低维护成本

配置示例

yaml

# Orchestrator（共享）
Orchestrator ID: orch-customer-service
Type: SINGLE
Agent: customer_service_agent

# Application 1: 企业微信
Platform: wework_aibot
Config:
  corp_id: ww123
  agent_id: 1000002

# Application 2: Web
Platform: webclient
Config:
  token: web-abc123

# Application 3: API
Platform: api_service
Config:
  api_key: app-xyz789

监控和分析

查看使用统计

进入 Agent System → Applications，点击 Application 查看：

总对话数
活跃用户数
平均响应时间
Token 消耗
错误率

日志查看

bash

# 查看 Application 日志
docker logs backend | grep "application_id=xxx"

# 查看特定用户会话
docker logs backend | grep "session_id=xxx"

# 查看错误日志
docker logs backend | grep ERROR | grep application

性能优化

1. Redis 配置

yaml

确保 Redis:
  - 内存充足（建议 4GB+）
  - 持久化配置（AOF/RDB）
  - 连接池配置合理

2. 并发控制

yaml

限制并发会话数:
  - 防止资源耗尽
  - 保证服务质量
  - 建议: 单Application限制100-500并发

3. 超时配置

yaml

合理设置超时:
  - SSE连接超时: 300秒
  - LLM响应超时: 60秒
  - 数据库查询超时: 10秒

故障排查

通用排查流程

yaml

1. 检查 Application 状态:
   - 是否启用
   - 配置是否正确

2. 检查 Orchestrator:
   - 是否存在
   - Agent 是否正常

3. 检查日志:
   - 后端日志
   - Redis 日志
   - 平台回调日志

4. 测试连接:
   - 数据库连接
   - Redis 连接
   - 第三方API

常见问题

所有平台通用

Q: 响应慢

yaml

排查:
  - 检查 LLM API 延迟
  - 检查 Redis 性能
  - 检查网络延迟
  - 优化 Agent 提示词（减少输出长度）

Q: Token 消耗大

yaml

优化:
  - 使用更便宜的模型
  - 限制历史消息长度
  - 优化提示词
  - 清理不必要的工具调用

Q: 流式中断

yaml

排查:
  - 检查 Redis Stream
  - 检查网络稳定性
  - 检查 LLM API 稳定性
  - 增加重试机制

安全最佳实践

1. 访问控制

yaml

企业微信:
  - 限制应用可见范围
  - 定期审查访问权限

Web Client:
  - 定期更换 Token
  - 设置访问频率限制
  - 考虑添加验证码

OpenAI API:
  - 保护 API Key 安全
  - 使用 IP 白名单
  - 监控异常调用

2. 数据安全

yaml

敏感信息处理:
  - 不在日志中记录用户隐私
  - 加密存储认证信息
  - 定期清理历史会话

企业合规:
  - 遵守数据保护法规（GDPR等）
  - 明确数据保留策略
  - 提供数据导出/删除功能

3. 防滥用

yaml

限流策略:
  - 单用户 QPS 限制
  - 单Application 并发限制
  - Token 每日调用限制

异常检测:
  - 监控异常高频调用
  - 识别恶意请求模式
  - 自动封禁异常来源

下一步

掌握 Application 配置后，继续学习：

MCP 工具使用 - 增强 Agent 的外部能力
完整使用场景 - 端到端实战案例
日志查看 - 排查与审计

💡 提示：

一个 Orchestrator 可以配置多个 Application
根据用户群体选择合适的平台
定期监控 Application 的使用情况
注意保护 Token 和 API Key 安全

Application 接入指南 ​

Application 是什么？ ​

支持的平台 ​

Application 的作用 ​

企业微信 AI Bot ​

概述 ​

前置准备 ​

1. 企业微信要求 ​

2. 创建应用 ​

3. 配置回调 ​

4. 开启 AI Bot API ​

创建 Application ​

步骤 1：进入 Application 管理 ​

步骤 2：选择平台 ​

步骤 3：配置基本信息 ​

步骤 4：配置平台参数 ​

步骤 5：保存并启用 ​

测试 ​

方法 1：企业微信测试 ​

方法 2：日志查看 ​

多模态支持 ​

发送图片 ​

常见问题 ​

Q1: 回调验证失败 ​

Q2: 消息发送失败 ​

Q3: 流式响应不工作 ​

Q4: 图片分析失败 ​

企业微信传统应用 ​

概述 ​

创建步骤 ​

响应方式 ​

Web Chat Client ​

概述 ​

创建步骤 ​

步骤 1：创建 Application ​

步骤 2：获取访问链接 ​

步骤 3：访问测试 ​

界面配置 ​

自定义标题和欢迎语 ​

样式自定义（高级） ​

嵌入网站 ​

方法 1：iframe 嵌入 ​

方法 2：弹窗模式 ​

方法 3：组件集成 ​

多模态支持 ​

发送图片链接 ​

图片检测规则 ​

安全配置 ​

CORS 配置 ​

Token 安全 ​

常见问题 ​

Q1: 流式响应不显示 ​

Q2: Token 失效 ​

Q3: 跨域问题 ​

OpenAI API ​

概述 ​

创建步骤 ​

步骤 1：创建 Application ​

步骤 2：获取 API Key ​

API 使用 ​

Endpoint ​

请求示例 ​

多模态支持 ​

发送图片 ​

高级功能 ​

会话管理 ​

自定义参数 ​

API 文档 ​

常见问题 ​

Q1: 认证失败 ​

Q2: 流式响应解析 ​

Q3: 模型参数不生效 ​

平台选择指南 ​

使用场景对比 ​

功能对比 ​

成本对比 ​

多平台部署 ​

一个 Orchestrator，多个 Application ​

配置示例 ​

监控和分析 ​

Application 接入指南

Application 是什么？

支持的平台

Application 的作用

企业微信 AI Bot

概述

前置准备

1. 企业微信要求

2. 创建应用

3. 配置回调

4. 开启 AI Bot API

创建 Application

步骤 1：进入 Application 管理

步骤 2：选择平台

步骤 3：配置基本信息

步骤 4：配置平台参数

步骤 5：保存并启用

测试

方法 1：企业微信测试

方法 2：日志查看

多模态支持

发送图片

常见问题

Q1: 回调验证失败

Q2: 消息发送失败

Q3: 流式响应不工作

Q4: 图片分析失败

企业微信传统应用

概述

创建步骤

响应方式

Web Chat Client

概述

创建步骤

步骤 1：创建 Application

步骤 2：获取访问链接

步骤 3：访问测试

界面配置

自定义标题和欢迎语

样式自定义（高级）

嵌入网站

方法 1：iframe 嵌入

方法 2：弹窗模式

方法 3：组件集成

多模态支持

发送图片链接

图片检测规则

安全配置

CORS 配置

Token 安全

常见问题

Q1: 流式响应不显示

Q2: Token 失效

Q3: 跨域问题

OpenAI API

概述

创建步骤

步骤 1：创建 Application

步骤 2：获取 API Key

API 使用

Endpoint

请求示例

多模态支持

发送图片

高级功能

会话管理

自定义参数

API 文档

常见问题

Q1: 认证失败

Q2: 流式响应解析

Q3: 模型参数不生效

平台选择指南

使用场景对比

功能对比

成本对比

多平台部署

一个 Orchestrator，多个 Application

配置示例

监控和分析