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

15 KiB
Raw 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