# FastAPI ADK Project API 文档

本文档详细描述了 FastAPI ADK Project 提供的所有 API 端点，包括健康检查和代理服务相关的接口。

## 基础信息

- **Base URL**: `http://localhost:8000/api/v1`
- **API 文档**: 
  - Swagger UI: `http://localhost:8000/docs`
  - ReDoc: `http://localhost:8000/redoc`
- **Version**: 0.1.0

## 1. 健康检查端点

### 1.1 基础健康检查

**GET** `/health/`

执行基础的健康检查以确认服务是否运行正常。

#### 请求示例

```bash
curl -X GET "http://localhost:8000/api/v1/health/"
```

#### 响应字段说明

- **status**: 响应状态 ("success" 表示正常)
- **data**: 返回的数据
  - **status**: 服务状态 ("healthy" 表示正常)
  - **service**: 服务名称
  - **database**: 数据库连接状态
- **message**: 响应消息
- **status_code**: 状态码 (200 表示正常)
- **trace_id**: 追踪ID，用于问题排查

#### 成功响应示例

```json
{
  "status": "success",
  "data": {
    "status": "healthy",
    "service": "fastapi-adk-project",
    "database": "connected"
  },
  "message": null,
  "status_code": 200,
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

#### 客户端使用示例 (Python)

```python
import httpx

response = httpx.get("http://localhost:8000/api/v1/health/")
health_status = response.json()
if health_status["status"] == "success":
    print("服务运行正常")
else:
    print("服务存在问题")
```

### 1.2 详细健康检查

**GET** `/health/detailed`

执行详细的健康检查，包括所有依赖服务的状态。

#### 请求示例

```bash
curl -X GET "http://localhost:8000/api/v1/health/detailed"
```

#### 响应字段说明

- **status**: 响应状态 ("success" 表示正常)
- **data**: 返回的数据
  - **status**: 整体服务状态
  - **service**: 服务名称
  - **timestamp**: 检查时间戳
  - **services**: 各服务状态详情，包括：
    - **database**: 数据库状态
    - **redis**: Redis状态
    - **kafka**: Kafka状态
- **message**: 响应消息
- **status_code**: 状态码 (200 表示正常)
- **trace_id**: 追踪ID，用于问题排查

#### 成功响应示例

```json
{
  "status": "success",
  "data": {
    "status": "healthy",
    "service": "fastapi-adk-project",
    "timestamp": "2023-01-01T00:00:00Z",
    "services": {
      "database": {
        "status": "healthy"
      },
      "redis": {
        "status": "healthy"
      },
      "kafka": {
        "status": "healthy"
      }
    }
  },
  "message": null,
  "status_code": 200,
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

#### 依赖服务故障响应示例

当依赖服务出现故障时，详细健康检查会在 `data` 中标记对应服务为 `unhealthy`，但HTTP响应状态码仍为200：

```json
{
  "status": "success",
  "data": {
    "status": "unhealthy",
    "service": "fastapi-adk-project",
    "timestamp": "2023-01-01T00:00:00Z",
    "services": {
      "database": {
        "status": "healthy"
      },
      "redis": {
        "status": "unhealthy",
        "error": "Redis connection refused"
      },
      "kafka": {
        "status": "unhealthy",
        "error": "Kafka broker not available"
      }
    }
  },
  "message": null,
  "status_code": 200,
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

#### 客户端使用示例 (Python)

```python
import httpx

response = httpx.get("http://localhost:8000/api/v1/health/detailed")
detailed_status = response.json()
```

## 2. 代理服务端点

### 2.1 运行代理

**POST** `/agents/run`

运行指定的代理并传递输入数据。

#### 请求体参数

| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| user_id | string | 是 | 用户ID |
| session_id | string | 是 | 会话ID |
| agent_name | string | 是 | 代理名称 |
| content | string | 是 | 输入文本 |
| data | object | 否 | 额外输入数据，用于数据预处理 |

#### 请求示例

**基础请求示例：**

```bash
curl -X POST "http://localhost:8000/api/v1/agents/run" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user123",
    "session_id": "session456",
    "agent_name": "hello_world_agent",
    "content": "Hello, world!"
  }'
```

**含 data 的请求示例（触发数据预处理）：**

```bash
curl -X POST "http://localhost:8000/api/v1/agents/run" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user123",
    "session_id": "session456",
    "agent_name": "text_modifier_agent",
    "content": "请处理这段文本",
    "data": {
      "test": {
        "text": "这是需要预处理的测试数据"
      }
    }
  }'
```

#### data 字段说明

当请求中包含 `data` 字段时，会触发数据预处理流程：

| 字段路径 | 类型 | 描述 |
|----------|------|------|
| data | object | 额外输入数据容器 |
| data.test | object | 测试预处理器数据（目前仅支持 test 类型） |
| data.test.text | string | 待预处理的文本内容 |

**预处理流程说明：**
1. 当 `data.test` 存在时，会调用 `TestPreprocessor` 对 `data.test.text` 进行预处理
2. 预处理结果会保存到制品服务中，供后续处理使用
3. 请求完成后会自动清理临时制品

#### 响应字段说明

- **status**: 响应状态 ("success" 或 "failed")
- **data**: 返回的数据
  - **response**: 代理的响应文本
- **message**: 响应消息
- **status_code**: HTTP 状态码 (200 表示正常)
- **trace_id**: 追踪ID，用于问题排查

#### 成功响应示例

```json
{
  "status": "success",
  "data": {
    "response": "Hello, World! You said: Hello, world!"
  },
  "message": "Agent executed successfully",
  "status_code": 200,
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

#### 错误响应示例

当代理不存在时：

```json
{
  "status": "failed",
  "data": null,
  "message": "Agent 'nonexistent_agent' not found",
  "status_code": 404,
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

当请求参数验证失败时：

```json
{
  "status": "failed",
  "data": null,
  "message": "请求参数验证失败",
  "status_code": 422,
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

当服务器内部错误发生时：

```json
{
  "status": "failed",
  "data": null,
  "message": "服务暂时不可用，请稍后再试",
  "status_code": 500,
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

| 状态码 | 描述 |
|--------|------|
| 404 | 代理未找到 |
| 422 | 请求参数验证失败 |
| 500 | 内部服务器错误 |

### 2.2 获取代理信息

**GET** `/agents/{agent_name}`

获取特定代理的信息。

#### 路径参数

| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| agent_name | string | 是 | 代理名称 |

#### 请求示例

```bash
curl -X GET "http://localhost:8000/api/v1/agents/hello_world_agent"
```

#### 响应字段说明

- **status**: 响应状态 ("success" 表示正常)
- **data**: 返回的数据
  - **name**: 代理名称
  - **description**: 代理描述
  - **model**: 使用的模型（如果有的话）
  - **tools**: 使用的工具列表（如果有的话）
- **message**: 响应消息
- **status_code**: HTTP 状态码 (200 表示正常)
- **trace_id**: 追踪ID，用于问题排查

#### 成功响应示例

```json
{
  "status": "success",
  "data": {
    "name": "hello_world_agent",
    "description": "A simple agent that responds with 'Hello, World!' and echoes the input.",
    "model": "Unknown",
    "tools": []
  },
  "message": "成功获取agent hello_world_agent的信息",
  "status_code": 200,
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

#### 错误响应示例

当代理不存在时：

```json
{
  "status": "failed",
  "data": null,
  "message": "Agent 'nonexistent_agent' not found",
  "status_code": 404,
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

当服务器内部错误发生时：

```json
{
  "status": "failed",
  "data": null,
  "message": "服务暂时不可用，请稍后再试",
  "status_code": 500,
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

| 状态码 | 描述 |
|--------|------|
| 404 | 代理未找到 |
| 500 | 内部服务器错误 |

### 2.3 列出所有代理

**GET** `/agents/`

列出所有可用的代理。

#### 请求示例

```bash
curl -X GET "http://localhost:8000/api/v1/agents/"
```

#### 响应字段说明

- **status**: 响应状态 ("success" 表示正常)
- **data**: 返回的数据
  - **agents**: 代理字典，键为代理名称，值为代理信息
- **message**: 响应消息
- **status_code**: HTTP 状态码 (200 表示正常)
- **trace_id**: 追踪ID，用于问题排查

#### 成功响应示例

```json
{
  "status": "success",
  "data": {
    "agents": {
      "hello_world_agent": {
        "name": "hello_world_agent",
        "description": "A simple agent that responds with 'Hello, World!' and echoes the input.",
        "model": "Unknown",
        "tools": []
      }
    }
  },
  "message": "成功获取所有agents",
  "status_code": 200,
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

#### 错误响应示例

当服务器内部错误发生时：

```json
{
  "status": "failed",
  "data": null,
  "message": "服务暂时不可用，请稍后再试",
  "status_code": 500,
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

## 3. 代理管理器环境适配

### 3.1 运行器选择策略

代理管理器根据运行环境自动选择适当的运行器实现：

- **生产环境**（ENVIRONMENT=production）：使用 [ProductionRunner](file:///Users/nic/workspace/projects/cgb_mac_project/fastapi-adk-project/app/agent_studio/runners.py#L67-L114)，提供完整的 Redis 支持以确保数据持久性、状态一致性和高可用性
- **开发和测试环境**（ENVIRONMENT=development 或 testing）：使用 [InMemoryRunner](file:///Users/nic/workspace/projects/cgb_mac_project/fastapi-adk-project/app/agent_studio/runners.py#L15-L65)，简化开发和测试流程，减少对外部服务的依赖

#### 环境配置

通过 `ENVIRONMENT` 环境变量设置运行环境：

```bash
# 设置为生产环境
ENVIRONMENT=production

# 设置为开发环境
ENVIRONMENT=development

# 设置为测试环境
ENVIRONMENT=testing
```

在生产环境中，代理管理器会使用 Redis 作为会话和内存服务的后端，确保代理状态的持久化和跨实例共享。在开发和测试环境中，使用内存运行器可简化配置并加快启动速度。

## 4. 统一响应格式

所有API响应都遵循统一的格式：

```json
{
  "status": "success",
  "data": {},
  "message": "响应消息",
  "status_code": 200,
  "trace_id": "追踪ID，用于问题排查"
}
```

## 5. 错误处理

所有错误响应遵循统一格式：

```json
{
  "status": "failed",
  "data": null,
  "message": "错误描述信息",
  "status_code": 400,
  "trace_id": "追踪ID，用于问题排查"
}
```

服务通过统一的异常处理框架捕获各类异常，并将其转换为标准响应格式。常见的HTTP状态码：
- **200**: 请求成功
- **400**: 请求参数错误（业务校验失败）
- **404**: 资源未找到
- **422**: 请求参数验证失败（Pydantic 校验错误）
- **500**: 服务器内部错误
- **503**: 外部服务不可用（Redis、Kafka 等连接失败）

## 6. 认证与授权

当前版本API不需要认证。

## 7. 限流与配额

目前未实施API限流策略，在高负载情况下可能会考虑添加请求频率限制。

## 8. 版本控制

API版本通过URL路径控制：`/api/v1/`，未来版本升级将通过更新版本号实现向后兼容。