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：

Authorization: Bearer <access_token>

响应格式

// 成功响应
{
    "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 用户注册

注册新用户账号。

POST /api/v1/users/register

请求体：

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

请求示例：

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

响应示例：

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

---

2.2 用户登录

获取 JWT 访问令牌。

POST /api/v1/users/login

请求体：

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

响应示例：

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

---

2.3 Token 刷新

使用 Refresh Token 获取新的 Access Token。

POST /api/v1/users/refresh

请求体：

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

响应示例：

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

---

2.4 获取当前用户信息

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

GET /api/v1/users/me

请求头：

Authorization: Bearer <access_token>

响应示例：

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

---

三、智能体模块

3.1 创建智能体

创建一个新的 AI 智能体。

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）

请求示例：

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

---

3.2 获取智能体列表

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

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

查询参数：

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

---

3.3 获取智能体详情

GET /api/v1/agents/{agent_id}

路径参数：

参数	类型	说明
agent_id	integer	智能体 ID

---

3.4 更新智能体

PUT /api/v1/agents/{agent_id}

请求体：（部分更新）

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

---

3.5 删除智能体

DELETE /api/v1/agents/{agent_id}

---

四、对话模块

4.1 创建对话会话

POST /api/v1/conversations

请求体：

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

---

4.2 发送消息

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

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 获取对话历史

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

---

五、知识库模块

5.1 上传文档

POST /api/v1/knowledge/documents/upload

请求格式： multipart/form-data

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

---

5.2 文档检索

POST /api/v1/knowledge/search

请求体：

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

---

六、健康检查

GET /api/v1/health

响应：

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

---

📎 相关文档：快速开始指南 | 开发指南