taijibaga/taiji-AI-PAD
9
0
Fork 0
forked from xiaohei/taiji-AI-PAD
Code Pull Requests Activity
Files
feature/chenchen
taiji-AI-PAD/Docs/Agent-Manager外部工具接口规范.md
T

16 KiB
Raw Permalink Blame History

Agent Manager 外部工具接口规范

版本: 2026-01-26 v1.0
用途: 本文档描述 MCP-Server 期望 Agent Manager 提供的接口规范
调用方: MCP-Server
服务方: Agent Manager

📊 系统架构

┌─────────────────────────────────────────────────────────────────────────────────────┐
│                              系统交互流程                                             │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                     │
│   ┌─────────────┐         ┌─────────────────┐         ┌─────────────────┐          │
│   │   前端      │   ───→  │   MCP-Server    │   ───→  │  Agent Manager  │          │
│   │   用户界面  │         │   (调用方)       │         │  (本文档规范)    │          │
│   └─────────────┘         └─────────────────┘         └─────────────────┘          │
│                                   │                          │                     │
│                                   ↓                          ↓                     │
│                           ┌─────────────┐           ┌─────────────────┐           │
│                           │  PostgreSQL │           │   工具文件存储   │           │
│                           │  (基本信息)  │           │   AKS 部署       │           │
│                           └─────────────┘           └─────────────────┘           │
│                                                                                     │
└─────────────────────────────────────────────────────────────────────────────────────┘

职责划分

组件 职责
MCP-Server 接收前端请求、存储工具基本信息和 tool_ref_id、调用 Agent Manager 接口
Agent Manager 生成 Pydantic 工具代码文件、存储完整配置（含敏感信息）、部署 Agent 到 AKS

🔐 通用规范

基础路径

{AGENT_MANAGER_URL}

MCP-Server 通过环境变量 AGENT_MANAGER_URL 配置 Agent Manager 地址。

请求头

Content-Type: application/json

响应格式

成功响应

{
  "success": true,
  "data": { ... },
  "message": "操作成功"
}

错误响应

{
  "success": false,
  "error": "error_code",
  "message": "错误描述"
}

📑 接口列表

序号 接口 方法 说明
1 /tools/generate POST 生成外部数据工具
2 /tools/{tool_ref_id} PUT 更新外部数据工具
3 /tools/{tool_ref_id} DELETE 删除外部数据工具
4 /tools/{tool_ref_id}/test POST 测试工具连接
5 /agents POST 创建 Agent（新增 tool_refs 字段）

1️⃣ 生成外部数据工具

接口

POST /tools/generate

功能描述

MCP-Server 将用户配置的工具信息发送给 Agent Manager，Agent Manager 需要：

  1. 验证配置格式
  2. 根据配置生成 Pydantic AI 工具代码文件
  3. 存储工具代码文件和完整配置（包含敏感信息如 API Key）
  4. 返回唯一的 tool_ref_id 供后续引用

请求参数

参数 类型 必填 说明
name string ✅ 工具名称（1-100 字符，将用于生成 Python 函数名）
description string ✅ 工具描述（将作为工具的 docstring）
url string ✅ API 端点 URL
method string ✅ HTTP 方法：GET/POST/PUT/DELETE/PATCH
user_id string ✅ 用户 ID（UUID 格式）
tenant_id string ❌ 租户 ID（UUID 格式）
headers object ❌ 自定义请求头
auth object ❌ 认证配置（详见下方）
request_params object ❌ URL 查询参数定义（JSON Schema 格式）
request_body object ❌ 请求体定义（JSON Schema 格式）
response_mapping object ❌ 响应字段映射
timeout integer ❌ 超时时间（秒），默认 30
retry object ❌ 重试配置

认证配置 (auth) 结构

API Key 认证

{
  "type": "api_key",
  "key": "sk-xxxxxxxxxxxx",
  "in": "header",       // 位置: header / query
  "name": "X-API-Key"   // 参数名
}

Bearer Token 认证

{
  "type": "bearer",
  "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Basic Auth 认证

{
  "type": "basic",
  "username": "admin",
  "password": "password123"
}

请求参数定义 (request_params / request_body) - JSON Schema 格式

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "城市名称",
      "required": true
    },
    "units": {
      "type": "string",
      "description": "温度单位",
      "enum": ["metric", "imperial"],
      "default": "metric"
    }
  }
}

响应字段映射 (response_mapping)

{
  "success_field": "code",      // 成功标识字段
  "success_value": 0,           // 成功值
  "data_field": "data",         // 数据字段
  "error_field": "message"      // 错误信息字段
}

重试配置 (retry)

{
  "max_retries": 3,
  "retry_delay": 1.0,
  "backoff_multiplier": 2.0
}

请求示例

{
  "name": "weather-query-tool",
  "description": "查询城市天气信息的工具",
  "url": "https://api.weather.com/v1/forecast",
  "method": "POST",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "660e8400-e29b-41d4-a716-446655440001",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  "auth": {
    "type": "api_key",
    "key": "sk-weather-api-key-xxx",
    "in": "header",
    "name": "X-API-Key"
  },
  "request_params": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称",
        "required": true
      }
    }
  },
  "timeout": 30,
  "retry": {
    "max_retries": 3,
    "retry_delay": 1.0
  }
}

响应示例

成功

{
  "success": true,
  "tool_ref_id": "tool-weather-abc123",
  "tool_name": "weather_query_tool",
  "status": "active",
  "message": "工具生成成功"
}

失败

{
  "success": false,
  "error": "invalid_config",
  "message": "工具配置无效: URL 格式不正确"
}

Agent Manager 需要完成的工作

  1. 验证配置

    • 验证 URL 格式是否有效
    • 验证 HTTP 方法是否合法
    • 验证 auth 配置格式

  2. 生成 Pydantic AI 工具代码

    • 根据 name 生成 Python 函数名（转换为 snake_case）
    • 根据 description 生成 docstring
    • 根据 request_params / request_body 生成函数参数
    • 生成调用外部 API 的代码

  3. 存储

    • 存储生成的工具代码文件
    • 存储完整配置（含敏感信息）
    • 生成唯一的 tool_ref_id

  4. 返回

    • 返回 tool_ref_id 供 MCP-Server 记录关联

2️⃣ 更新外部数据工具

接口

PUT /tools/{tool_ref_id}

路径参数

参数 类型 说明
tool_ref_id string 工具标识（由生成接口返回）

功能描述

更新已有工具的配置。Agent Manager 会重新生成工具代码文件，可能返回新的 tool_ref_id。

请求参数

与「生成外部数据工具」接口相同。

请求示例

{
  "name": "weather-query-tool-v2",
  "description": "查询城市天气信息的工具（升级版）",
  "url": "https://api.weather.com/v2/forecast",
  "method": "POST",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "headers": {
    "Content-Type": "application/json"
  },
  "auth": {
    "type": "api_key",
    "key": "sk-new-api-key-xxx",
    "in": "header",
    "name": "X-API-Key"
  },
  "timeout": 60
}

响应示例

成功

{
  "success": true,
  "tool_ref_id": "tool-weather-abc123-v2",
  "status": "active",
  "message": "工具更新成功"
}

注意: tool_ref_id 可能会变化，MCP-Server 会更新本地记录。

3️⃣ 删除外部数据工具

接口

DELETE /tools/{tool_ref_id}

路径参数

参数 类型 说明
tool_ref_id string 工具标识

功能描述

删除工具代码文件和存储的配置。

响应示例

成功

{
  "success": true,
  "message": "工具删除成功"
}

失败（工具正在被使用）

{
  "success": false,
  "error": "tool_in_use",
  "message": "工具正在被 Agent 使用，无法删除"
}

4️⃣ 测试工具连接

接口

POST /tools/{tool_ref_id}/test

路径参数

参数 类型 说明
tool_ref_id string 工具标识

功能描述

Agent Manager 使用存储的工具配置，尝试调用外部 API 并返回测试结果。

请求参数

参数 类型 必填 说明
test_params object ❌ 测试时使用的参数值

请求示例

{
  "test_params": {
    "city": "北京"
  }
}

响应示例

成功

{
  "success": true,
  "connected": true,
  "response_time_ms": 156,
  "status_code": 200,
  "sample_response": {
    "status": "ok",
    "data": {
      "city": "北京",
      "temperature": "15°C",
      "weather": "晴"
    }
  }
}

连接失败

{
  "success": true,
  "connected": false,
  "response_time_ms": 5000,
  "status_code": 0,
  "error": "连接超时"
}

5️⃣ 创建带有外部工具的 Agent

接口

POST /agents

功能描述

这是 Agent Manager 已有的创建 Agent 接口，需要新增 tool_refs 字段支持。

当 MCP-Server 传递 tool_refs 时，Agent Manager 需要：

  1. 加载对应的工具代码文件
  2. 将工具集成到 Agent 中
  3. 部署 Agent 到 AKS

请求参数

参数 类型 必填 说明
name string ✅ Agent 名称（1-63 字符，符合 K8s 命名规范）
template string ✅ Agent 模板名称
tool_refs string[] ❌ 新增 外部数据工具标识列表
config object ❌ 资源配置
env object ❌ 环境变量

资源配置 (config) 结构

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "cpu_request": "100m",
  "cpu_limit": "500m",
  "memory_request": "128Mi",
  "memory_limit": "512Mi",
  "replicas": 1
}

请求示例

{
  "name": "my-data-agent",
  "template": "custom_agent",
  "tool_refs": [
    "tool-weather-abc123",
    "tool-stock-def456"
  ],
  "config": {
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "cpu_request": "500m",
    "cpu_limit": "1000m",
    "memory_request": "512Mi",
    "memory_limit": "1Gi",
    "replicas": 1
  },
  "env": {
    "LLM_BASE_URL": "https://litellm.example.com",
    "MODEL_NAME": "gpt-4"
  }
}

响应示例

{
  "success": true,
  "name": "my-data-agent",
  "namespace": "ai-agents",
  "status": "Pending",
  "created_at": "2026-01-26T10:00:00Z",
  "template": "custom_agent",
  "service_port": 8080,
  "access_info": {
    "domain": "my-data-agent.example.com",
    "domain_url": "https://my-data-agent.example.com",
    "ip_url": "http://10.0.0.100:8080"
  },
  "tools_attached": 2
}

Agent Manager 需要完成的工作

  1. 加载工具文件

    • 根据 tool_refs 列表查找对应的工具代码文件
    • 验证所有工具都存在且可用

  2. 集成工具到 Agent

    • 将工具代码文件打包到 Agent 容器镜像中
    • 或通过 ConfigMap/Volume 挂载工具文件

  3. 配置环境变量

    • 注入工具所需的认证信息（从存储的配置中读取）
    • 合并 MCP-Server 传递的 env

  4. 部署到 AKS

    • 创建 Deployment/Pod
    • 创建 Service
    • 配置 Ingress（如需要）

❌ 错误码定义

HTTP 状态码 错误代码 说明
400 invalid_config 配置格式无效
400 invalid_url URL 格式无效
400 invalid_method HTTP 方法无效
400 invalid_auth 认证配置无效
400 invalid_schema JSON Schema 格式无效
404 tool_not_found 工具不存在
409 tool_name_exists 工具名称已存在（同一用户下）
409 tool_in_use 工具正在被 Agent 使用
500 generation_failed 工具代码生成失败
500 deployment_failed Agent 部署失败

📋 Pydantic AI 工具代码生成示例

以下是 Agent Manager 需要生成的工具代码示例，供参考：

输入配置

{
  "name": "weather-query",
  "description": "查询指定城市的天气信息",
  "url": "https://api.weather.com/v1/current",
  "method": "GET",
  "auth": {
    "type": "api_key",
    "key": "sk-xxx",
    "in": "query",
    "name": "apikey"
  },
  "request_params": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称",
        "required": true
      }
    }
  }
}

生成的工具代码

from pydantic_ai import Agent
from pydantic_ai.tools import Tool
import httpx
from typing import Any, Dict

async def weather_query(city: str) -> Dict[str, Any]:
    """
    查询指定城市的天气信息
    
    Args:
        city: 城市名称
        
    Returns:
        天气信息字典
    """
    url = "https://api.weather.com/v1/current"
    params = {
        "city": city,
        "apikey": "sk-xxx"  # 从配置注入
    }
    
    async with httpx.AsyncClient(timeout=30) as client:
        response = await client.get(url, params=params)
        response.raise_for_status()
        return response.json()

# 注册为 Pydantic AI 工具
weather_query_tool = Tool(
    name="weather_query",
    description="查询指定城市的天气信息",
    function=weather_query
)

📌 集成测试建议

在 Agent Manager 实现完成后，建议进行以下测试：

1. 工具生成测试

# 创建工具
curl -X POST "${AGENT_MANAGER_URL}/tools/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-tool",
    "description": "测试工具",
    "url": "https://httpbin.org/get",
    "method": "GET",
    "user_id": "test-user-id"
  }'

2. 工具测试

# 测试工具连接
curl -X POST "${AGENT_MANAGER_URL}/tools/{tool_ref_id}/test" \
  -H "Content-Type: application/json" \
  -d '{}'

3. 带工具的 Agent 创建测试

# 创建 Agent
curl -X POST "${AGENT_MANAGER_URL}/agents" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-agent",
    "template": "custom_agent",
    "tool_refs": ["tool-ref-id-1"],
    "config": {
      "cpu_request": "100m",
      "memory_request": "128Mi"
    }
  }'

📞 联系方式

如有疑问，请联系 MCP-Server 开发团队。

文档更新记录

日期 版本 更新内容
2026-01-26 v1.0 初始版本
View Git Blame Copy Permalink