# AI 智能体接入指南

> 集成 OpenClaw AI Agent，实现知识库问答、工作流触发与多模型切换。

## 🧠 什么是 AI 智能体？

AI 智能体（AI Agent）是 Websopy 平台的核心能力，它能：

- 🤖 基于自然语言理解用户意图
- 📚 连接你的知识库进行精准问答
- 🔗 触发业务工作流执行自动化任务
- 🔄 在多个 AI 模型间智能切换

## 📋 前提条件

- 已完成 [快速上手](./quickstart.md)
- 已开通 AI 功能（控制台 → 开发者中心 → AI 功能）

## 🚀 接入步骤

### 第一步：安装 AI SDK

```bash
npm install @websopy/ai-sdk
```

### 第二步：初始化 Agent

```typescript
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']
})
```

### 第三步：创建会话

```typescript
// 创建新的对话会话
const session = await agent.createSession({
  userId: 'user-123',
  // 关联知识库（可选）
  knowledgeBaseId: 'kb-abc456',
  // 会话元数据
  metadata: {
    source: 'website',
    language: 'zh-CN'
  }
})

console.log('会话 ID:', session.id)
```

### 第四步：发送消息

```typescript
// 发送用户消息
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）

对于需要实时反馈的场景，使用流式输出：

```typescript
const stream = await agent.sendMessageStream(session.id, {
  content: '写一篇关于 AI 的博客文章'
})

for await (const chunk of stream) {
  process.stdout.write(chunk.content)
}
```

## 📚 知识库集成

### 创建知识库

```typescript
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'
  }
})
```

### 关联知识库问答

```typescript
const response = await agent.sendMessage(session.id, {
  content: '你们的退款政策是什么？',
  // 强制从知识库检索
  retrieveFrom: 'kb-abc456',
  // 检索参数
  retrievalConfig: {
    topK: 5,          // 返回前 5 条相关片段
    scoreThreshold: 0.7  // 相似度阈值
  }
})
```

## 🔧 工作流触发

AI Agent 可以根据对话内容自动触发业务工作流：

```typescript
// 配置意图识别和触发
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)
})
```

## 🔄 多模型切换

### 手动切换

```typescript
// 切换到指定模型
await agent.switchModel(session.id, 'claude-3')

const response = await agent.sendMessage(session.id, {
  content: '解释量子计算原理'
})
```

### 自动路由

根据任务类型自动选择最优模型：

```typescript
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'] }
    ]
  }
})
```

## 📊 高级配置

### 对话上下文管理

```typescript
// 设置上下文窗口大小
agent.setContextWindow(session.id, {
  maxMessages: 50,      // 保留最近 50 条消息
  maxTokens: 8000       // 最大 token 数
})

// 手动添加系统提示
agent.addSystemPrompt(session.id, {
  role: 'system',
  content: '你是一个专业的客服助手，说话风格友好、专业。'
})
```

### 错误处理与重试

```typescript
const response = await agent.sendMessage(session.id, {
  content: '复杂问题...'
}, {
  // 重试配置
  retry: {
    maxAttempts: 3,
    delayMs: 1000,
    backoff: 'exponential'
  },
  // 超时配置（毫秒）
  timeout: 30000
})
```

## 🧪 完整示例

```typescript
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: 知识库检索不到相关内容？

1. 检查文档是否已成功上传和向量化
2. 调整 `scoreThreshold` 降低阈值
3. 尝试增加 `topK` 获取更多候选

---

**上一步：** [5 分钟快速上手](./quickstart.md)  
**下一步：** [私有化部署完全指南](./deployment.md)