705 lines
15 KiB
Markdown
705 lines
15 KiB
Markdown
# 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
|
||
```
|