taiji-AI-PAD/API_DOCUMENTATION.md

AI Agent Manager API 文档

📋 目录

• 概述
• 快速开始
• 核心概念
• API 端点
• 数据模型
• 使用示例
• 错误处理
• 最佳实践

---

概述

AI Agent Manager 是一个基于 Kubernetes 的 AI Agent 生命周期管理服务，提供完整的 Agent 创建、部署、监控和删除功能。

核心特性

• ✅ 独立命名空间: 每个 Agent 部署在独立的 Kubernetes 命名空间中
• ✅ 自动外网访问: 自动创建 LoadBalancer Service 和 Azure DNS 记录
• ✅ 多框架支持: 支持 MCP、A2A、API 三种框架类型
• ✅ 资源监控: 实时监控 Agent 资源使用情况
• ✅ 模板管理: 预定义的 Agent 模板，快速部署

技术栈

• Web 框架: FastAPI
• 容器编排: Kubernetes (AKS)
• DNS 服务: Azure DNS
• 监控: Kubernetes Metrics Server

服务信息

• 版本: v1.0.0
• 默认端口: 8000
• 默认命名空间: ai-agents

---

快速开始

验证服务

curl http://localhost:8000/

响应:

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

---

核心概念

1. Agent

Agent 是运行在 Kubernetes 中的 AI 服务实例，每个 Agent：

• 运行在独立的命名空间中
• 拥有唯一的外网访问地址
• 支持自动扩缩容
• 可以实时监控资源使用

2. Template（模板）

模板定义了 Agent 的类型和配置，包括：

• 容器镜像
• 环境变量要求
• 资源配置
• 框架类型

3. Framework（框架）

支持三种框架类型：

• MCP: Model Context Protocol
• A2A: Agent-to-Agent
• API: REST API（默认）

4. Namespace（命名空间）

每个 Agent 创建时自动生成独立的 Kubernetes 命名空间，格式：agent-{agent-name}

---

API 端点

基础信息

GET /

获取服务状态

响应:

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

---

Agent 管理

POST /agents

创建新的 Agent

请求体:

{
  "name": "my-agent",
  "template": "jina_search_agent",
  "framework": "API",
  "config": {
    "user_id": "user123"
  },
  "env": {
    "JINA_API_KEY": "your-api-key"
  }
}

参数说明:

参数	类型	必需	说明
name	string	✅	Agent 名称（1-63字符，小写字母、数字、连字符）
template	string	✅	模板类型（见模板列表）
framework	string	❌	框架类型：MCP、A2A、API（默认：API）
config	object	❌	配置信息（如 user_id）
env	object	❌	环境变量
namespace	string	❌	自定义命名空间（不推荐）

响应:

{
  "name": "my-agent",
  "namespace": "agent-my-agent",
  "framework": "API",
  "status": "Pending",
  "template": "jina_search_agent",
  "service_port": 8080,
  "access_info": {
    "external_ip": "135.171.210.24",
    "ip_url": "http://135.171.210.24:80",
    "domain": "my-agent.taijiagnet.com",
    "domain_url": "http://my-agent.taijiagnet.com",
    "recommended": "http://my-agent.taijiagnet.com"
  },
  "pod_id": "7160fcd9-fbbe-48a1-9675-2b111cc36bc8",
  "pod_ip": "10.244.3.80",
  "host_ip": "10.224.0.7",
  "node_name": "aks-node-001",
  "owner_info": {
    "user_id": "user123",
    "agent_name": "my-agent",
    "namespace": "agent-my-agent",
    "framework": "API",
    "labels": {
      "app": "my-agent",
      "framework": "api",
      "managed-by": "agent-manager",
      "template": "jina_search_agent"
    }
  }
}

状态码:

• 200: 创建成功
• 400: 参数错误（无效的模板或框架类型）
• 500: 服务器错误

---

GET /agents

列出所有 Agent

查询参数:

• template (可选): 按模板类型过滤

示例:

# 列出所有 Agent
curl http://localhost:8000/agents

# 按模板过滤
curl http://localhost:8000/agents?template=jina_search_agent

响应:

{
  "agents": [
    {
      "name": "my-agent",
      "status": "Running",
      "template": "jina_search_agent",
      "created_at": "2026-01-14T10:00:00+00:00",
      "pod_ip": "10.244.3.80"
    }
  ],
  "count": 1
}

---

GET /agents/{agent_name}/status

获取 Agent 详细状态

路径参数:

• agent_name: Agent 名称

响应:

{
  "name": "my-agent",
  "namespace": "agent-my-agent",
  "status": "Running",
  "health_status": "healthy",
  "template": "jina_search_agent",
  "created_at": "2026-01-14T10:00:00+00:00",
  "node": "aks-node-001",
  "pod_ip": "10.244.3.80",
  "containers": [
    {
      "name": "my-agent",
      "ready": true,
      "restart_count": 0,
      "state": "running",
      "started_at": "2026-01-14T10:00:05+00:00"
    }
  ],
  "resources": {
    "requests": {
      "cpu": "100m",
      "memory": "128Mi"
    },
    "limits": {
      "cpu": "500m",
      "memory": "512Mi"
    },
    "usage": {
      "cpu": "50m",
      "memory": "200Mi",
      "available": true
    }
  },
  "service_port": 8080,
  "access_url": "http://10.244.3.80:8080",
  "endpoints": {
    "root": "http://10.244.3.80:8080/",
    "health": "http://10.244.3.80:8080/health"
  },
  "conditions": [
    {
      "type": "Ready",
      "status": "True",
      "reason": "PodReady"
    }
  ]
}

健康状态:

• healthy: 容器运行正常
• unhealthy: 容器未就绪或终止
• degraded: 重启次数过多

---

GET /agents/{agent_name}/metrics

获取 Agent 资源使用情况

响应:

{
  "name": "my-agent",
  "namespace": "agent-my-agent",
  "requests": {
    "cpu": "100m",
    "memory": "128Mi"
  },
  "limits": {
    "cpu": "500m",
    "memory": "512Mi"
  },
  "usage": {
    "cpu": "45m",
    "memory": "256Mi"
  },
  "timestamp": "2026-01-14T10:30:00+00:00",
  "metrics_available": true
}

注意: 需要 Kubernetes Metrics Server 支持

---

DELETE /agents/{agent_name}

删除 Agent

路径参数:

• agent_name: Agent 名称

响应:

{
  "status": "success",
  "message": "Agent my-agent 的命名空间 agent-my-agent 及所有相关资源已删除",
  "namespace": "agent-my-agent"
}

删除内容:

• ✅ Kubernetes 命名空间
• ✅ Pod
• ✅ LoadBalancer Service
• ✅ Azure DNS 记录（如果存在）

状态码:

• 200: 删除成功
• 404: Agent 不存在
• 500: 服务器错误

---

模板管理

GET /templates

列出所有可用模板

响应:

{
  "templates": [
    {
      "template": "jina_search_agent",
      "port": 8080,
      "env_info": {
        "required": {
          "JINA_API_KEY": "Jina API密钥"
        },
        "optional": {
          "SERVICE_PORT": "HTTP服务端口，默认8080"
        }
      }
    }
  ],
  "count": 10
}

---

GET /templates/platform

列出平台模板

响应: 与 /templates 类似，但只包含平台预定义模板

平台模板列表:

• echo_agent
• chat_agent
• code_agent
• search_agent
• jina_search_agent
• azure_blob_agent
• azure_blob_agent_mcp
• azure_blob_agent_a2a

---

GET /templates/custom

列出自定义模板

自定义模板列表:

• mysql_agent
• postgresql_agent

---

GET /templates/{template_name}

获取指定模板详情

路径参数:

• template_name: 模板名称

响应:

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

---

数据模型

CreateAgentRequest

创建 Agent 请求模型

{
  "name": str,              # Agent名称（必需，1-63字符）
  "template": str,          # 模板类型（必需）
  "framework": str,         # 框架类型（可选，默认API）
  "config": dict,           # 配置信息（可选）
  "env": dict,              # 环境变量（可选）
  "namespace": str          # 命名空间（可选）
}

AgentResponse

Agent 响应模型

{
  "name": str,              # Agent名称
  "namespace": str,         # 命名空间
  "framework": str,         # 框架类型
  "status": str,            # 状态
  "template": str,          # 模板类型
  "service_port": int,      # 服务端口
  "access_info": dict,      # 访问信息
  "pod_id": str,            # Pod ID
  "pod_ip": str,            # Pod IP
  "host_ip": str,           # 宿主机IP
  "node_name": str,         # 节点名称
  "owner_info": dict        # 所有者信息
}

---

使用示例

示例 1: 创建 Jina 搜索 Agent

curl -X POST http://localhost:8000/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search-bot",
    "template": "jina_search_agent",
    "framework": "API",
    "config": {
      "user_id": "alice"
    },
    "env": {
      "JINA_API_KEY": "jina_xxx"
    }
  }'

示例 2: 创建 MCP 框架的 Azure Blob Agent

curl -X POST http://localhost:8000/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "blob-mcp",
    "template": "azure_blob_agent_mcp",
    "framework": "MCP",
    "config": {
      "user_id": "bob"
    },
    "env": {
      "MODEL_PROVIDER": "openai",
      "MODEL_NAME": "gpt-4",
      "MODEL_API_KEY": "sk-xxx",
      "AZURE_STORAGE_CONNECTION_STRING": "DefaultEndpointsProtocol=https;..."
    }
  }'

示例 3: 查询 Agent 状态

curl http://localhost:8000/agents/search-bot/status

示例 4: 监控资源使用

curl http://localhost:8000/agents/search-bot/metrics

示例 5: 列出所有 Agent

# 所有 Agent
curl http://localhost:8000/agents

# 只列出 Jina 搜索 Agent
curl http://localhost:8000/agents?template=jina_search_agent

示例 6: 删除 Agent

curl -X DELETE http://localhost:8000/agents/search-bot

示例 7: Python 客户端

import requests

# 基础 URL
BASE_URL = "http://localhost:8000"

# 创建 Agent
def create_agent(name, template, framework="API", env=None):
    response = requests.post(
        f"{BASE_URL}/agents",
        json={
            "name": name,
            "template": template,
            "framework": framework,
            "config": {"user_id": "demo"},
            "env": env or {}
        }
    )
    return response.json()

# 获取状态
def get_agent_status(name):
    response = requests.get(f"{BASE_URL}/agents/{name}/status")
    return response.json()

# 删除 Agent
def delete_agent(name):
    response = requests.delete(f"{BASE_URL}/agents/{name}")
    return response.json()

# 使用示例
agent = create_agent(
    name="my-search",
    template="jina_search_agent",
    env={"JINA_API_KEY": "jina_xxx"}
)

print(f"Agent 创建成功！")
print(f"访问地址: {agent['access_info']['recommended']}")

# 查询状态
status = get_agent_status("my-search")
print(f"状态: {status['status']}")

---

错误处理

错误响应格式

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

常见错误

400 Bad Request

原因:

• 无效的模板类型
• 无效的框架类型
• Agent 名称不符合规范

示例:

{
  "detail": "无效的模板类型。支持的模板: echo_agent, chat_agent, ..."
}

404 Not Found

原因:

• Agent 不存在
• 模板不存在

示例:

{
  "detail": "Pod my-agent 不存在"
}

500 Internal Server Error

原因:

• Kubernetes API 错误
• DNS 配置错误
• 网络问题

处理建议:

1. 检查 Kubernetes 集群状态
2. 验证 kubeconfig 配置
3. 检查网络连接
4. 查看服务日志

---

---

附录

A. 支持的模板列表

模板名称	类型	用途	必需环境变量
jina_search_agent	Platform	Jina AI 搜索	JINA_API_KEY
azure_blob_agent	Platform	Azure Blob 存储	LITELLM_API_BASE, LITELLM_MODEL, LITELLM_API_KEY
azure_blob_agent_mcp	Platform	Azure Blob MCP	MODEL_PROVIDER, MODEL_NAME, MODEL_API_KEY
azure_blob_agent_a2a	Platform	Azure Blob A2A	MODEL_PROVIDER, MODEL_NAME, MODEL_API_KEY, AGENT_ID, AGENT_ROLE
mysql_agent	Custom	MySQL 数据库	MYSQL_HOST, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE, OPENAI_API_KEY
postgresql_agent	Custom	PostgreSQL 数据库	POSTGRES_HOST, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DATABASE, OPENAI_API_KEY
search_agent	Platform	通用搜索	-
echo_agent	Platform	Echo 测试	-
chat_agent	Platform	聊天	-
code_agent	Platform	代码生成	-

B. 框架类型说明

框架	全称	用途
MCP	Model Context Protocol	基于协议的模型上下文交互
A2A	Agent-to-Agent	Agent 间通信
API	REST API	标准 HTTP API 接口

联系支持

如有问题或建议，请联系开发团队或查看项目文档。

文档版本: v1.0.0
最后更新: 2026-01-14