aiagent/docs/api-reference.md

# 🔌 API 参考文档

> **API Reference**

本文档描述了天工智能体平台后端 RESTful API 接口规范。所有 API 均通过 Nginx 反向代理暴露，前缀为 `/api/v1`。

> 💡 **交互式文档**：启动后端服务后，可访问 `http://localhost:8037/docs` 查看 Swagger UI 文档。

---

## 一、通用规范

### 基础 URL

```
生产环境：https://your-domain.com/api/v1
开发环境：http://localhost:8037/api/v1
```

### 认证方式

所有受保护的接口需在请求头中携带 JWT Token：

```http
Authorization: Bearer <access_token>
```

### 响应格式

```json
// 成功响应
{
    "code": 200,
    "message": "success",
    "data": { ... }
}

// 错误响应
{
    "code": 40001,
    "message": "用户不存在",
    "data": null
}
```

### 通用错误码

| 状态码 | 错误码 | 说明 |
|:------|:-------|:------|
| 200 | 200 | 请求成功 |
| 400 | 40000 | 请求参数错误 |
| 401 | 40100 | 未认证（Token 缺失或过期） |
| 403 | 40300 | 无权限访问 |
| 404 | 40400 | 资源不存在 |
| 500 | 50000 | 服务器内部错误 |

---

## 二、用户模块

### 2.1 用户注册

注册新用户账号。

```http
POST /api/v1/users/register
```

**请求体：**

| 参数 | 类型 | 必填 | 说明 |
|:-----|:-----|:-----|:------|
| `email` | string | ✅ | 邮箱地址 |
| `password` | string | ✅ | 密码（至少 8 位，含字母和数字） |
| `nickname` | string | ❌ | 用户昵称 |

**请求示例：**

```json
{
    "email": "user@example.com",
    "password": "Abc12345",
    "nickname": "张三"
}
```

**响应示例：**

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "id": 1,
        "email": "user@example.com",
        "nickname": "张三",
        "created_at": "2026-05-10T08:00:00Z"
    }
}
```

---

### 2.2 用户登录

获取 JWT 访问令牌。

```http
POST /api/v1/users/login
```

**请求体：**

| 参数 | 类型 | 必填 | 说明 |
|:-----|:-----|:-----|:------|
| `email` | string | ✅ | 邮箱地址 |
| `password` | string | ✅ | 密码 |

**响应示例：**

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIs...",
        "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
        "token_type": "bearer",
        "expires_in": 1800
    }
}
```

---

### 2.3 Token 刷新

使用 Refresh Token 获取新的 Access Token。

```http
POST /api/v1/users/refresh
```

**请求体：**

| 参数 | 类型 | 必填 | 说明 |
|:-----|:-----|:-----|:------|
| `refresh_token` | string | ✅ | 登录时获取的 Refresh Token |

**响应示例：**

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIs...",
        "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
        "token_type": "bearer",
        "expires_in": 1800
    }
}
```

---

### 2.4 获取当前用户信息

获取已登录用户的个人信息。

```http
GET /api/v1/users/me
```

**请求头：**
```http
Authorization: Bearer <access_token>
```

**响应示例：**

```json
{
    "code": 200,
    "message": "success",
    "data": {
        "id": 1,
        "email": "user@example.com",
        "nickname": "张三",
        "avatar": "https://...",
        "created_at": "2026-05-10T08:00:00Z"
    }
}
```

---

## 三、智能体模块

### 3.1 创建智能体

创建一个新的 AI 智能体。

```http
POST /api/v1/agents
```

**请求体：**

| 参数 | 类型 | 必填 | 说明 |
|:-----|:-----|:-----|:------|
| `name` | string | ✅ | 智能体名称 |
| `description` | string | ❌ | 智能体描述 |
| `prompt_template` | string | ✅ | 系统提示词模板 |
| `model_config` | object | ✅ | LLM 模型配置 |

**`model_config` 对象：**

| 参数 | 类型 | 必填 | 说明 |
|:-----|:-----|:-----|:------|
| `provider` | string | ✅ | 模型提供商：`openai` / `azure` / `local` |
| `model_name` | string | ✅ | 模型名称：`gpt-4o` / `gpt-3.5-turbo` |
| `temperature` | number | ❌ | 生成温度（默认 0.7） |
| `max_tokens` | integer | ❌ | 最大 Token 数（默认 2048） |

**请求示例：**

```json
{
    "name": "智能客服助手",
    "description": "用于解答常见产品问题",
    "prompt_template": "你是一个专业的客服助手...",
    "model_config": {
        "provider": "openai",
        "model_name": "gpt-4o",
        "temperature": 0.5,
        "max_tokens": 2048
    }
}
```

---

### 3.2 获取智能体列表

获取当前用户的所有智能体。

```http
GET /api/v1/agents?page=1&page_size=20

```

**查询参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|:-----|:-----|:-----|:-------|:------|
| `page` | integer | ❌ | 1 | 页码 |
| `page_size` | integer | ❌ | 20 | 每页条数（最大 100） |

---

### 3.3 获取智能体详情

```http
GET /api/v1/agents/{agent_id}
```

**路径参数：**

| 参数 | 类型 | 说明 |
|:-----|:-----|:------|
| `agent_id` | integer | 智能体 ID |

---

### 3.4 更新智能体

```http
PUT /api/v1/agents/{agent_id}
```

**请求体：**（部分更新）

| 参数 | 类型 | 必填 | 说明 |
|:-----|:-----|:-----|:------|
| `name` | string | ❌ | 智能体名称 |
| `description` | string | ❌ | 智能体描述 |
| `prompt_template` | string | ❌ | 系统提示词 |
| `model_config` | object | ❌ | 模型配置 |

---

### 3.5 删除智能体

```http
DELETE /api/v1/agents/{agent_id}
```

---

## 四、对话模块

### 4.1 创建对话会话

```http
POST /api/v1/conversations
```

**请求体：**

| 参数 | 类型 | 必填 | 说明 |
|:-----|:-----|:-----|:------|
| `agent_id` | integer | ✅ | 关联的智能体 ID |
| `title` | string | ❌ | 会话标题（可选） |

---

### 4.2 发送消息

向指定对话发送消息，支持流式响应（SSE）。

```http
POST /api/v1/conversations/{conversation_id}/messages
```

**请求体：**

| 参数 | 类型 | 必填 | 说明 |
|:-----|:-----|:-----|:------|
| `content` | string | ✅ | 用户消息内容 |

**流式响应（SSE）：**

```
data: {"type": "token", "content": "你好"}
data: {"type": "token", "content": "，"}
data: {"type": "token", "content": "请问有什么可以帮您？"}
data: {"type": "done"}
data: {"type": "error", "content": "..."}
```

---

### 4.3 获取对话历史

```http
GET /api/v1/conversations/{conversation_id}/messages?page=1&page_size=50
```

---

## 五、知识库模块

### 5.1 上传文档

```http
POST /api/v1/knowledge/documents/upload
```

**请求格式：** `multipart/form-data`

| 参数 | 类型 | 必填 | 说明 |
|:-----|:-----|:-----|:------|
| `file` | file | ✅ | 支持 PDF / TXT / Markdown |
| `agent_id` | integer | ✅ | 关联的智能体 ID |

---

### 5.2 文档检索

```http
POST /api/v1/knowledge/search
```

**请求体：**

| 参数 | 类型 | 必填 | 说明 |
|:-----|:-----|:-----|:------|
| `query` | string | ✅ | 检索关键词 |
| `agent_id` | integer | ✅ | 限定知识库范围 |
| `top_k` | integer | ❌ | 返回条数（默认 5） |

---

## 六、健康检查

```http
GET /api/v1/health
```

**响应：**

```json
{
    "status": "ok",
    "version": "1.0.0",
    "timestamp": "2026-05-10T08:00:00Z"
}
```

---

> 📎 **相关文档**：[快速开始指南](./quickstart.md) | [开发指南](./development-guide.md)