# 智能搜索AI Agent API接口文档

## 基础信息

- **服务名称**: Intelligent Search AI Agent
- **版本**: 1.0.0
- **基础URL**: `域名`
- **Content-Type**: `application/json`

---

## 核心接口

### 执行搜索

#### POST /search

执行智能搜索，根据查询返回答案和相关来源。

**请求参数**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| query | string | 是 | 搜索查询 |
| llm_api_key | string | 是 | LLM API密钥（用户的API密钥） |
| user_id | string | 否 | 用户ID（用于计费回调） |

**请求示例**:
```json
{
  "query": "什么是人工智能？",
  "llm_api_key": "your-llm-api-key",
  "user_id": "user123"
}
```

**响应示例**:
```json
{
  "query": "什么是人工智能？",
  "answer": "人工智能（AI）是计算机科学的一个分支，致力于创建能够执行通常需要人类智能的任务的系统...",
  "sources": [
    {
      "index": 1,
      "title": "人工智能 - 维基百科",
      "url": "https://zh.wikipedia.org/wiki/人工智能"
    },
    {
      "index": 2,
      "title": "什么是AI？",
      "url": "https://example.com/ai-introduction"
    }
  ],
  "confidence": "high",
  "iterations": 2,
  "total_sources": 5,
  "search_queries": [
    "什么是人工智能",
    "AI定义"
  ],
  "timestamp": "2024-01-01T00:00:00.000000"
}
```

**响应字段说明**:

| 字段 | 类型 | 说明 |
|------|------|------|
| query | string | 原始查询 |
| answer | string | 生成的答案内容（Markdown格式） |
| sources | array | 来源列表 |
| sources[].index | integer | 来源索引 |
| sources[].title | string | 来源标题 |
| sources[].url | string | 来源URL |
| confidence | string | 置信度："high" / "medium" / "low" |
| iterations | integer | 迭代次数 |
| total_sources | integer | 参考来源总数 |
| search_queries | array[string] | 使用的搜索查询列表 |
| timestamp | string | 时间戳（ISO格式） |

**错误响应**:

400 Bad Request（参数错误）:
```json
{
  "detail": "llm_api_key 是必须的参数"
}
```

500 Internal Server Error（服务器错误）:
```json
{
  "detail": "搜索失败: {错误详情}"
}
```

---

### 聊天接口

#### POST /chat

聊天接口，是 `/search` 接口的别名，功能和参数完全相同。

**请求参数**: 与 `/search` 接口相同

**请求示例**: 与 `/search` 接口相同

**响应示例**: 与 `/search` 接口相同

---

## 其他接口

### 健康检查

#### GET /health

检查服务健康状态。

**请求示例**:
```
GET /health
```

**响应示例**:
```json
{
  "status": "healthy",
  "pod_name": "search-agent",
  "template_type": "search_agent",
  "configured": true,
  "llm_base_url": "https://api.example.com",
  "llm_model": "xchat52",
  "timestamp": "2024-01-01T00:00:00.000000"
}
```

---

### 获取状态

#### GET /status

获取服务状态信息。

**请求示例**:
```
GET /status
```

**响应示例**:
```json
{
  "status": "running",
  "pod_name": "search-agent",
  "template_type": "search_agent",
  "configured": true,
  "timestamp": "2024-01-01T00:00:00.000000"
}
```

---

## 使用说明

**重要提示**：
- 用户只需要传递 `query` 和 `llm_api_key` 参数
- `llm_base_url`、`llm_model` 等配置参数已通过环境变量在部署时配置，**不需要**在请求中传递
- `user_id` 为可选参数，用于计费回调

**请求参数说明**：
- `query` - 搜索查询内容（必填）
- `llm_api_key` - 用户的LLM API密钥（必填）
- `user_id` - 用户ID（可选）

---

## 错误码说明

| HTTP状态码 | 说明 |
|-----------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 500 | 服务器内部错误 |