6.0 KiB
6.0 KiB
AI 智能体接入指南
集成 OpenClaw AI Agent，实现知识库问答、工作流触发与多模型切换。
🧠 什么是 AI 智能体？
AI 智能体（AI Agent）是 Websopy 平台的核心能力，它能：
- 🤖 基于自然语言理解用户意图
- 📚 连接你的知识库进行精准问答
- 🔗 触发业务工作流执行自动化任务
- 🔄 在多个 AI 模型间智能切换
📋 前提条件
- 已完成 快速上手
- 已开通 AI 功能（控制台 → 开发者中心 → AI 功能）
🚀 接入步骤
第一步：安装 AI SDK
npm install @websopy/ai-sdk
第二步：初始化 Agent
import { AIAgent } from '@websopy/ai-sdk'
const agent = new AIAgent({
apiKey: process.env.WEBSOPY_API_KEY,
// 选择默认模型
defaultModel: 'gpt-4',
// 可用模型列表
models: ['gpt-4', 'claude-3', 'gemini-pro']
})
第三步：创建会话
// 创建新的对话会话
const session = await agent.createSession({
userId: 'user-123',
// 关联知识库（可选）
knowledgeBaseId: 'kb-abc456',
// 会话元数据
metadata: {
source: 'website',
language: 'zh-CN'
}
})
console.log('会话 ID:', session.id)
第四步：发送消息
// 发送用户消息
const response = await agent.sendMessage(session.id, {
content: '我想了解你们的产品价格',
// 可选：附加参数
context: {
userPlan: 'free',
priority: 'normal'
}
})
console.log('AI 回复:', response.content)
console.log('使用模型:', response.model)
console.log('置信度:', response.confidence)
第五步：流式响应（SSE）
对于需要实时反馈的场景，使用流式输出：
const stream = await agent.sendMessageStream(session.id, {
content: '写一篇关于 AI 的博客文章'
})
for await (const chunk of stream) {
process.stdout.write(chunk.content)
}
📚 知识库集成
创建知识库
const kb = await agent.createKnowledgeBase({
name: '产品文档',
description: '公司产品相关文档',
// 向量化模型
embeddingModel: 'text-embedding-3-small'
})
// 上传文档
await agent.uploadDocument(kb.id, {
file: './docs/product-guide.pdf',
// 文档元数据
metadata: {
category: 'documentation',
version: '2.0'
}
})
关联知识库问答
const response = await agent.sendMessage(session.id, {
content: '你们的退款政策是什么？',
// 强制从知识库检索
retrieveFrom: 'kb-abc456',
// 检索参数
retrievalConfig: {
topK: 5, // 返回前 5 条相关片段
scoreThreshold: 0.7 // 相似度阈值
}
})
🔧 工作流触发
AI Agent 可以根据对话内容自动触发业务工作流：
// 配置意图识别和触发
await agent.setIntentHandler(session.id, {
intents: [
{
name: 'create_order',
patterns: ['下单', '购买', '创建订单'],
action: 'trigger_workflow',
workflowId: 'wf-order-create'
},
{
name: 'cancel_subscription',
patterns: ['取消订阅', '退订'],
action: 'trigger_workflow',
workflowId: 'wf-subscription-cancel'
}
]
})
// 处理工作流结果
agent.onWorkflowComplete((result) => {
console.log('工作流完成:', result.workflowId)
console.log('结果:', result.output)
})
🔄 多模型切换
手动切换
// 切换到指定模型
await agent.switchModel(session.id, 'claude-3')
const response = await agent.sendMessage(session.id, {
content: '解释量子计算原理'
})
自动路由
根据任务类型自动选择最优模型：
const agent = new AIAgent({
apiKey: process.env.WEBSOPY_API_KEY,
// 配置自动路由
autoRoute: {
enabled: true,
rules: [
{ task: 'coding', models: ['gpt-4', 'claude-3'] },
{ task: 'creative', models: ['gpt-4', 'gemini-pro'] },
{ task: 'analysis', models: ['claude-3', 'gpt-4'] }
]
}
})
📊 高级配置
对话上下文管理
// 设置上下文窗口大小
agent.setContextWindow(session.id, {
maxMessages: 50, // 保留最近 50 条消息
maxTokens: 8000 // 最大 token 数
})
// 手动添加系统提示
agent.addSystemPrompt(session.id, {
role: 'system',
content: '你是一个专业的客服助手，说话风格友好、专业。'
})
错误处理与重试
const response = await agent.sendMessage(session.id, {
content: '复杂问题...'
}, {
// 重试配置
retry: {
maxAttempts: 3,
delayMs: 1000,
backoff: 'exponential'
},
// 超时配置（毫秒）
timeout: 30000
})
🧪 完整示例
import { AIAgent } from '@websopy/ai-sdk'
async function main() {
const agent = new AIAgent({
apiKey: process.env.WEBSOPY_API_KEY,
defaultModel: 'gpt-4'
})
// 创建会话
const session = await agent.createSession({
userId: 'user-123',
knowledgeBaseId: 'kb-product-docs'
})
// 对话循环
const messages = [
'你好，我想了解一下企业版的功能',
'支持私有化部署吗？',
'好的，我想试用一下'
]
for (const msg of messages) {
const response = await agent.sendMessage(session.id, {
content: msg
})
console.log(`\n👤 用户: ${msg}`)
console.log(`🤖 AI: ${response.content}`)
}
}
main()
❓ 常见问题
Q: 如何查看 API 调用量？
在控制台 → 开发者中心 → AI 功能，可以查看详细的使用统计。
Q: 支持哪些 Embedding 模型？
目前支持：
text-embedding-3-small（推荐，速度快）text-embedding-3-large（高精度）text-embedding-ada-002（兼容性）
Q: 知识库检索不到相关内容？
- 检查文档是否已成功上传和向量化
- 调整
scoreThreshold降低阈值 - 尝试增加
topK获取更多候选