zhanggangyong/agent_management
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
agent_management/plans/API_DOCUMENTATION.md
T
Ubuntu 23116e9086 init
2026-01-05 12:44:28 +00:00

15 KiB
Raw Permalink Blame History

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 /

响应

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

cURL 示例

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

2. 列出所有模板

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

请求

GET /templates

成功响应 (200)

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

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

3. 获取模板详情

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

请求

GET /templates/{template_name}

路径参数

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

成功响应 (200)

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

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 {} 自定义环境变量

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

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

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

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

# 创建 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)

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

cURL 示例

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（运行中）

{
  "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。如果未安装，usage.available 为 false，并在 usage.reason 中说明原因。

状态值说明

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

cURL 示例

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

7. 获取 Agent 资源使用情况

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

请求

GET /agents/{agent_name}/metrics

成功响应 (200)

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

cURL 示例

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

8. 列出所有 Agent

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

请求

GET /agents

查询参数

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

成功响应 (200)

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

# 列出所有 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

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())

错误处理

通用错误响应格式

{
  "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。安装命令： 
    kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
Reference in New Issue View Git Blame Copy Permalink