# AI Agent Manager API 文档

## 概述

AI Agent Manager 是一个基于 FastAPI 构建的 Kubernetes AI Agent 管理服务。该服务提供 RESTful API 接口，用于在 Kubernetes 集群中创建、删除、查询和管理 AI Agent Pod。

### 基本信息

| 项目 | 值 |
|------|-----|
| 服务名称 | AI Agent Manager |
| 版本 | 1.0.0 |
| 基础URL | `http://<host>:<port>` |
| 默认端口 | 8000 |
| 内容类型 | `application/json` |

### 环境变量配置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `NAMESPACE` | `ai-agents` | AI Agent 部署的 Kubernetes 命名空间 |
| `KUBECONFIG_PATH` | `None` | kubeconfig 文件路径（可选） |
| `SERVICE_HOST` | `0.0.0.0` | 服务监听地址 |
| `SERVICE_PORT` | `8000` | 服务监听端口 |

---

## API 端点

### 1. 健康检查

检查服务运行状态。

**请求**

```
GET /
```

**响应**

```json
{
  "service": "AI Agent Manager",
  "status": "running",
  "namespace": "ai-agents"
}
```

**cURL 示例**

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

---

### 2. 列出所有模板

获取所有可用的 Agent 模板及其所需参数。

**请求**

```
GET /templates
```

**成功响应 (200)**

```json
{
  "templates": [
    {
      "template": "echo_agent",
      "port": null,
      "env_info": {}
    },
    {
      "template": "jina_search_agent",
      "port": 8080,
      "env_info": {
        "required": {
          "JINA_API_KEY": "Jina API密钥，从 https://jina.ai/ 获取"
        },
        "optional": {
          "SERVICE_PORT": "HTTP服务端口，默认8080",
          "SERVICE_HOST": "HTTP服务监听地址，默认0.0.0.0"
        }
      }
    },
    {
      "template": "mysql_agent",
      "port": null,
      "env_info": {
        "required": {
          "MYSQL_HOST": "MySQL数据库主机地址",
          "MYSQL_USER": "MySQL用户名",
          "MYSQL_PASSWORD": "MySQL密码",
          "MYSQL_DATABASE": "MySQL数据库名",
          "OPENAI_API_KEY": "OpenAI API密钥"
        },
        "optional": {
          "MYSQL_PORT": "MySQL端口，默认3306"
        }
      }
    }
  ],
  "count": 7
}
```

**cURL 示例**

```bash
curl -X GET "http://localhost:8000/templates"
```

---

### 3. 获取模板详情

获取指定模板的详细信息，包括所需环境变量。

**请求**

```
GET /templates/{template_name}
```

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `template_name` | string | 是 | 模板名称 |

**成功响应 (200)**

```json
{
  "template": "jina_search_agent",
  "port": 8080,
  "env_info": {
    "required": {
      "JINA_API_KEY": "Jina API密钥，从 https://jina.ai/ 获取"
    },
    "optional": {
      "SERVICE_PORT": "HTTP服务端口，默认8080",
      "SERVICE_HOST": "HTTP服务监听地址，默认0.0.0.0"
    }
  }
}
```

**错误响应**

| 状态码 | 说明 |
|--------|------|
| 404 | 模板不存在 |

**cURL 示例**

```bash
curl -X GET "http://localhost:8000/templates/jina_search_agent"
```

---

### 4. 创建 Agent

创建一个新的 AI Agent Pod。

**请求**

```
POST /agents
```

**请求头**

```
Content-Type: application/json
```

**请求体参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 是 | Agent 名称，长度 1-63 字符 |
| `template` | string | 是 | 模板类型（见模板列表） |
| `config` | object | 否 | 配置信息（见下表） |

**config 配置参数**

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `replicas` | integer | 1 | 副本数量 |
| `cpu_request` | string | `100m` | CPU 请求量 |
| `cpu_limit` | string | `500m` | CPU 限制量 |
| `memory_request` | string | `128Mi` | 内存请求量 |
| `memory_limit` | string | `512Mi` | 内存限制量 |
| `env` | object | `{}` | 自定义环境变量 |

**请求体示例（带环境变量）**

```json
{
  "name": "my-jina-agent",
  "template": "jina_search_agent",
  "config": {
    "cpu_request": "100m",
    "cpu_limit": "500m",
    "memory_request": "128Mi",
    "memory_limit": "512Mi",
    "env": {
      "JINA_API_KEY": "your-jina-api-key"
    }
  }
}
```

**成功响应 (200) - HTTP服务类型Agent**

```json
{
  "name": "my-jina-agent",
  "namespace": "ai-agents",
  "status": "Pending",
  "created_at": "2025-12-31T01:00:00.000000+00:00",
  "template": "jina_search_agent",
  "service_port": 8080,
  "access_info": {
    "note": "Pod IP将在Pod运行后可用，请通过 /agents/{name}/status 获取",
    "port": 8080,
    "endpoints": {
      "root": "http://<pod_ip>:8080/",
      "health": "http://<pod_ip>:8080/health"
    }
  }
}
```

**成功响应 (200) - 普通Agent**

```json
{
  "name": "my-echo-agent",
  "namespace": "ai-agents",
  "status": "Pending",
  "created_at": "2025-12-31T01:00:00.000000+00:00",
  "template": "echo_agent"
}
```

**错误响应**

| 状态码 | 说明 |
|--------|------|
| 400 | 无效的模板类型 |
| 500 | 服务器内部错误 |

**cURL 示例**

```bash
# 创建 Jina Search Agent（带环境变量）
curl -X POST "http://localhost:8000/agents" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-jina-agent",
    "template": "jina_search_agent",
    "config": {
      "env": {
        "JINA_API_KEY": "your-jina-api-key"
      }
    }
  }'

# 创建 MySQL Agent
curl -X POST "http://localhost:8000/agents" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-mysql-agent",
    "template": "mysql_agent",
    "config": {
      "env": {
        "MYSQL_HOST": "mysql.example.com",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "password",
        "MYSQL_DATABASE": "mydb",
        "OPENAI_API_KEY": "sk-xxx"
      }
    }
  }'
```

---

### 5. 删除 Agent

删除指定的 AI Agent Pod。

**请求**

```
DELETE /agents/{agent_name}
```

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `agent_name` | string | 是 | 要删除的 Agent 名称 |

**成功响应 (200)**

```json
{
  "status": "success",
  "message": "Pod my-jina-agent 已删除"
}
```

**cURL 示例**

```bash
curl -X DELETE "http://localhost:8000/agents/my-jina-agent"
```

---

### 6. 获取 Agent 状态

获取指定 Agent 的详细状态信息，包括访问URL和资源使用情况（CPU、内存）。

**请求**

```
GET /agents/{agent_name}/status
```

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `agent_name` | string | 是 | Agent 名称 |

**成功响应 (200) - HTTP服务类型Agent（运行中）**

```json
{
  "name": "my-jina-agent",
  "namespace": "ai-agents",
  "status": "Running",
  "template": "jina_search_agent",
  "created_at": "2025-12-31T01:00:00.000000+00:00",
  "node": "aks-nodepool1-12345678-vmss000000",
  "pod_ip": "10.244.0.15",
  "resources": {
    "requests": {
      "cpu": "100m",
      "memory": "128Mi"
    },
    "limits": {
      "cpu": "500m",
      "memory": "512Mi"
    },
    "usage": {
      "cpu": "50m",
      "memory": "64Mi",
      "available": true
    }
  },
  "service_port": 8080,
  "access_url": "http://10.244.0.15:8080",
  "endpoints": {
    "root": "http://10.244.0.15:8080/",
    "health": "http://10.244.0.15:8080/health"
  },
  "conditions": [
    {
      "type": "Ready",
      "status": "True",
      "reason": null
    }
  ]
}
```

**resources 字段说明**

| 字段 | 说明 |
|------|------|
| `requests` | 资源请求配额（Pod 启动时保证的资源） |
| `limits` | 资源限制配额（Pod 可使用的最大资源） |
| `usage` | 实际资源使用情况（需要集群安装 metrics-server） |

**usage 字段说明**

| 字段 | 类型 | 说明 |
|------|------|------|
| `cpu` | string | 当前 CPU 使用量（如 "50m" 表示 50 毫核） |
| `memory` | string | 当前内存使用量（如 "64Mi" 表示 64 MiB） |
| `available` | boolean | 资源使用数据是否可用 |
| `reason` | string | 如果 `available` 为 false，说明原因 |

**注意**: 实际资源使用量（`usage`）需要 Kubernetes 集群安装 [metrics-server](https://github.com/kubernetes-sigs/metrics-server)。如果未安装，`usage.available` 为 `false`，并在 `usage.reason` 中说明原因。

**状态值说明**

| 状态 | 说明 |
|------|------|
| `Pending` | Pod 已被接受，但容器尚未创建 |
| `Running` | Pod 已绑定到节点，所有容器已创建 |
| `Succeeded` | Pod 中所有容器已成功终止 |
| `Failed` | Pod 中所有容器已终止，至少一个容器失败 |
| `Unknown` | 无法获取 Pod 状态 |

**cURL 示例**

```bash
curl -X GET "http://localhost:8000/agents/my-jina-agent/status"
```

---

### 7. 获取 Agent 资源使用情况

获取指定 Agent 的 CPU 和内存资源配置信息。

**请求**

```
GET /agents/{agent_name}/metrics
```

**成功响应 (200)**

```json
{
  "name": "my-jina-agent",
  "requests": {
    "cpu": "100m",
    "memory": "128Mi"
  },
  "limits": {
    "cpu": "500m",
    "memory": "512Mi"
  }
}
```

**cURL 示例**

```bash
curl -X GET "http://localhost:8000/agents/my-jina-agent/metrics"
```

---

### 8. 列出所有 Agent

获取所有 AI Agent 的列表，支持按模板类型过滤。

**请求**

```
GET /agents
```

**查询参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `template` | string | 否 | 按模板类型过滤 |

**成功响应 (200)**

```json
{
  "agents": [
    {
      "name": "my-jina-agent",
      "status": "Running",
      "template": "jina_search_agent",
      "created_at": "2025-12-31T01:00:00.000000+00:00",
      "pod_ip": "10.244.0.15"
    }
  ],
  "count": 1
}
```

**cURL 示例**

```bash
# 列出所有 Agent
curl -X GET "http://localhost:8000/agents"

# 按模板类型过滤
curl -X GET "http://localhost:8000/agents?template=jina_search_agent"
```

---

## 模板类型说明

### echo_agent

简单的回显 Agent，用于测试和演示。

- **镜像**: `agnettaiji.azurecr.io/ai-agents/echo-agent:latest`
- **用途**: 测试、演示、健康检查
- **所需环境变量**: 无

### chat_agent

聊天对话 Agent，支持对话交互。

- **镜像**: `agnettaiji.azurecr.io/ai-agents/chat-agent:latest`
- **用途**: 对话系统、客服机器人
- **所需环境变量**: 无

### code_agent

代码生成 Agent，支持代码相关任务。

- **镜像**: `agnettaiji.azurecr.io/ai-agents/code-agent:latest`
- **用途**: 代码生成、代码审查、代码解释
- **所需环境变量**: 无

### search_agent

搜索 Agent。

- **镜像**: `agnettaiji.azurecr.io/ai-agents/search-agent:latest`
- **用途**: 搜索功能
- **所需环境变量**: 无

### jina_search_agent

使用 Jina Reader API 获取网站内容的 HTTP 服务 Agent。

- **镜像**: `agnettaiji.azurecr.io/ai-agents/jina-search-agent:latest`
- **服务端口**: 8080
- **用途**: 网站内容抓取、网页转文本
- **所需环境变量**:
  | 变量名 | 必填 | 说明 |
  |--------|------|------|
  | `JINA_API_KEY` | 是 | Jina API密钥 |
  | `SERVICE_PORT` | 否 | HTTP服务端口，默认8080 |
  | `SERVICE_HOST` | 否 | HTTP服务监听地址，默认0.0.0.0 |

- **Agent API端点**:
  - `GET /` - 服务信息和所需参数
  - `GET /health` - 健康检查
  - `POST /search` - 搜索网站内容
  - `GET /fetch?url=<url>` - 快速获取网站内容

### mysql_agent

MySQL 数据库查询 Agent，使用 LangChain 实现。

- **镜像**: `agnettaiji.azurecr.io/ai-agents/mysql-agent:latest`
- **用途**: MySQL 数据库自然语言查询
- **所需环境变量**:
  | 变量名 | 必填 | 说明 |
  |--------|------|------|
  | `MYSQL_HOST` | 是 | MySQL数据库主机地址 |
  | `MYSQL_USER` | 是 | MySQL用户名 |
  | `MYSQL_PASSWORD` | 是 | MySQL密码 |
  | `MYSQL_DATABASE` | 是 | MySQL数据库名 |
  | `OPENAI_API_KEY` | 是 | OpenAI API密钥 |
  | `MYSQL_PORT` | 否 | MySQL端口，默认3306 |

### postgresql_agent

PostgreSQL 数据库查询 Agent，使用 LangChain 实现。

- **镜像**: `agnettaiji.azurecr.io/ai-agents/postgresql-agent:latest`
- **用途**: PostgreSQL 数据库自然语言查询
- **所需环境变量**:
  | 变量名 | 必填 | 说明 |
  |--------|------|------|
  | `POSTGRES_HOST` | 是 | PostgreSQL数据库主机地址 |
  | `POSTGRES_USER` | 是 | PostgreSQL用户名 |
  | `POSTGRES_PASSWORD` | 是 | PostgreSQL密码 |
  | `POSTGRES_DATABASE` | 是 | PostgreSQL数据库名 |
  | `OPENAI_API_KEY` | 是 | OpenAI API密钥 |
  | `POSTGRES_PORT` | 否 | PostgreSQL端口，默认5432 |

---

## 完整使用流程示例

### 场景：创建并使用 Jina Search Agent

```python
import requests
import time

BASE_URL = "http://localhost:8000"

# 1. 查看模板所需参数
print("=== 查看模板信息 ===")
response = requests.get(f"{BASE_URL}/templates/jina_search_agent")
template_info = response.json()
print(f"所需环境变量: {template_info['env_info']}")

# 2. 创建 Agent
print("\n=== 创建 Agent ===")
response = requests.post(
    f"{BASE_URL}/agents",
    json={
        "name": "my-jina-agent",
        "template": "jina_search_agent",
        "config": {
            "env": {
                "JINA_API_KEY": "your-jina-api-key"
            }
        }
    }
)
create_result = response.json()
print(f"创建结果: {create_result}")

# 3. 等待 Agent 运行
print("\n=== 等待 Agent 启动 ===")
for i in range(30):
    response = requests.get(f"{BASE_URL}/agents/my-jina-agent/status")
    status = response.json()
    if status.get("status") == "Running":
        print(f"Agent 已启动!")
        print(f"访问地址: {status.get('access_url')}")
        break
    print(f"当前状态: {status.get('status')}, 等待中...")
    time.sleep(2)

# 4. 调用 Agent 服务
if status.get("access_url"):
    agent_url = status["access_url"]
    
    # 查看 Agent 信息
    print("\n=== Agent 服务信息 ===")
    response = requests.get(f"{agent_url}/")
    print(response.json())
    
    # 搜索网站内容
    print("\n=== 搜索网站内容 ===")
    response = requests.post(
        f"{agent_url}/search",
        json={"url": "https://www.example.com"}
    )
    print(response.json())

# 5. 删除 Agent
print("\n=== 删除 Agent ===")
response = requests.delete(f"{BASE_URL}/agents/my-jina-agent")
print(response.json())
```

---

## 错误处理

### 通用错误响应格式

```json
{
  "detail": "错误描述信息"
}
```

### HTTP 状态码

| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## OpenAPI/Swagger 文档

FastAPI 自动生成交互式 API 文档：

- **Swagger UI**: `http://localhost:8000/docs`
- **ReDoc**: `http://localhost:8000/redoc`
- **OpenAPI JSON**: `http://localhost:8000/openapi.json`

---

## 注意事项

1. **Agent 名称规范**: 名称必须符合 Kubernetes 命名规范（小写字母、数字、连字符，长度 1-63）
2. **资源配额**: 请根据实际需求配置 CPU 和内存，避免资源浪费或不足
3. **命名空间**: 所有 Agent 默认部署在 `ai-agents` 命名空间
4. **镜像拉取**: 需要配置 ACR 密钥（`acr-secret`）才能拉取私有镜像
5. **网络访问**: 服务默认监听所有网络接口（0.0.0.0），生产环境请注意安全配置
6. **环境变量安全**: 敏感信息（如 API 密钥）应通过安全方式传递，避免在日志中暴露
7. **资源监控**: 获取 Agent 实际 CPU/内存使用量需要集群安装 [metrics-server](https://github.com/kubernetes-sigs/metrics-server)。安装命令：
   ```bash
   kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
   ```