# 删除 Agent 接口文档

本文档描述用户删除平台 Agent 和自定义 Agent 的 API 接口。

---

## 目录

1. [通用说明](#通用说明)
2. [删除平台 Agent](#删除平台-agent)
3. [删除/删除自定义 Agent](#删除删除自定义-agent)

---

## 通用说明

### 认证方式

所有接口需要 Bearer Token 认证。

### 请求头

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `Authorization` | string | ✅ | Bearer Token，格式：`Bearer <access_token>` |
| `Content-Type` | string | ❌ | 无请求体时可省略 |

### 通用响应结构

**成功响应 (SuccessResponse)**

```json
{
  "success": true,
  "data": {},
  "message": "操作成功消息"
}
```

**错误响应**

```json
{
  "detail": {
    "error": "错误代码",
    "message": "错误描述",
    "detail": "详细错误信息"
  }
}
```

---

## 删除平台 Agent

删除用户正在运行的平台 Agent 实例，释放 Pod 配额，结算费用。

### 接口信息

| 项目 | 内容 |
|------|------|
| **URL** | `DELETE /api/user/platform-agents/{agent_name}` |
| **Method** | DELETE |
| **认证** | Bearer Token |

### 路径参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `agent_name` | string | ✅ | 平台 Agent 实例名称（Pod 名称） |

### 请求头

```http
DELETE /api/user/platform-agents/my-agent-instance-12345678 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

### 请求示例

```bash
curl -X DELETE "https://api.example.com/api/user/platform-agents/my-agent-instance-12345678" \
  -H "Authorization: Bearer <your_access_token>"
```

### 响应

#### 成功响应 (200 OK)

```json
{
  "success": true,
  "message": "Agent my-agent-instance-12345678 已删除"
}
```

#### 错误响应

**404 Not Found - Agent 不存在**

```json
{
  "detail": "Agent 不存在"
}
```

**500 Internal Server Error - 删除 Pod 失败**

```json
{
  "detail": {
    "error": "agent_stop_failed",
    "message": "删除失败: 无法连接到 Agent Manager",
    "detail": "Connection refused"
  }
}
```

**401 Unauthorized - 未认证**

```json
{
  "detail": "Not authenticated"
}
```

### 业务逻辑说明

1. 验证用户身份和权限
2. 查找用户拥有的指定平台 Agent
3. 调用 Agent Manager 删除 Kubernetes Pod
4. 结束计费记录，计算运行时长和费用
5. 释放租户的 Pod 配额（`pod_used - 1`）
6. 从数据库删除 Agent 记录
7. 返回成功消息

### 计费说明

- 计费单位：EU（Energy Unit）
- 计算方式：1 EU = 10 秒运行时间，不足 10 秒按 1 EU 计算
- 费率：平台 Agent 固定费率 $0.10/小时

---

## 删除/删除自定义 Agent

删除用户创建的自定义 Agent，释放 CPU/内存配额，结算费用。

### 接口信息

| 项目 | 内容 |
|------|------|
| **URL** | `DELETE /api/user/custom-agents/{name}` |
| **Method** | DELETE |
| **认证** | Bearer Token |

### 路径参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | string | ✅ | 自定义 Agent 名称 |

### 请求头

```http
DELETE /api/user/custom-agents/my-custom-mysql-agent HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

### 请求示例

```bash
curl -X DELETE "https://api.example.com/api/user/custom-agents/my-custom-mysql-agent" \
  -H "Authorization: Bearer <your_access_token>"
```

### 响应

#### 成功响应 (200 OK)

```json
{
  "success": true,
  "message": "自定义 Agent my-custom-mysql-agent 已删除",
  "data": {
    "quotaReleased": {
      "cpu": 0.5,
      "memory": 1.0
    }
  }
}
```

**响应字段说明**

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 操作是否成功 |
| `message` | string | 成功消息 |
| `data.quotaReleased.cpu` | number | 释放的 CPU 配额（核心数） |
| `data.quotaReleased.memory` | number | 释放的内存配额（GB） |

#### 错误响应

**404 Not Found - Agent 不存在或不属于当前用户**

```json
{
  "detail": "未找到 Agent my-custom-mysql-agent 或该 Agent 不属于您"
}
```

**500 Internal Server Error - 删除失败**

```json
{
  "detail": {
    "error": "delete_agent_failed",
    "message": "删除失败: Agent Manager 服务不可用",
    "detail": "Connection timeout"
  }
}
```

**401 Unauthorized - 未认证**

```json
{
  "detail": "Not authenticated"
}
```

### 业务逻辑说明

1. 验证用户身份和权限
2. 查找用户拥有的自定义 Agent 计费记录
3. 结束计费记录，计算运行时长和费用
4. 按资源使用量计算费用并扣除用户余额
5. 释放用户的 CPU/内存配额
6. 提交数据库更改
7. 调用 Agent Manager 删除 Kubernetes Pod
8. 返回成功消息和释放的配额信息

### 计费说明

- 计费单位：EU（Energy Unit）
- 计算方式：根据 CPU 核心数和内存大小，按运行时长计费
- 公式：`cost = calculate_agent_cost_by_resources(cpu_cores, memory_gb, duration_seconds)`

---

## 接口对比

| 特性 | 删除平台 Agent | 删除自定义 Agent |
|------|---------------|-----------------|
| **API 路径** | `/api/user/platform-agents/{agent_name}` | `/api/user/custom-agents/{name}` |
| **配额类型** | Pod 配额（`pod_used`） | CPU/内存配额 |
| **计费方式** | 固定费率 $0.10/小时 | 按资源使用量计费 |
| **返回数据** | 仅消息 | 消息 + 释放的配额详情 |

---

## 错误代码一览

| 错误代码 | HTTP 状态码 | 说明 |
|----------|-------------|------|
| `agent_stop_failed` | 500 | 删除平台 Agent 失败 |
| `delete_agent_failed` | 500 | 删除自定义 Agent 失败 |
| - | 404 | Agent 不存在或不属于当前用户 |
| - | 401 | 未认证或 Token 无效 |

---

## 接口定义来源

| 接口 | 文件位置 |
|------|----------|
| 删除平台 Agent | `services/mcp-server/app/routes/platform_agent_quota.py` 第 992-1093 行 |
| 删除自定义 Agent | `services/mcp-server/app/routes/user.py` 第 3180-3286 行 |

---

*文档生成时间：2026-01-14*