taiji-AI-PAD/Docs/项目文档/删除Agent接口文档.md

删除 Agent 接口文档

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

---

目录

1. 通用说明
2. 删除平台 Agent
3. 删除/删除自定义 Agent

---

通用说明

认证方式

所有接口需要 Bearer Token 认证。

请求头

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

通用响应结构

成功响应 (SuccessResponse)

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

错误响应

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

---

删除平台 Agent

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

接口信息

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

路径参数

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

请求头

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

请求示例

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

响应

成功响应 (200 OK)

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

错误响应

404 Not Found - Agent 不存在

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

500 Internal Server Error - 删除 Pod 失败

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

401 Unauthorized - 未认证

{
  "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 名称

请求头

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

请求示例

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

响应

成功响应 (200 OK)

{
  "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 不存在或不属于当前用户

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

500 Internal Server Error - 删除失败

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

401 Unauthorized - 未认证

{
  "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