taijibaga/taiji-AI-PAD
9
0
Fork 0
forked from xiaohei/taiji-AI-PAD
Code Pull Requests Activity
Files
fe69a70a3aaf2f205592d280dbce02787ac56e96
taiji-AI-PAD/plans/自定义外部数据工具功能方案.md
T

32 KiB
Raw Blame History

自定义外部数据工具功能方案

版本: v1.0
日期: 2026-01-23
状态: ✅ 已实现

1. 功能概述

1.1 背景

用户需要能够创建自定义的外部数据工具，这些工具可以连接到外部 API 服务（如第三方数据接口、企业内部系统等），并在部署自定义 Agent 时使用这些工具。

1.2 核心流程

┌─────────────────────────────────────────────────────────────────────────────────────┐
│                              自定义外部数据工具流程                                    │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                     │
│  ① 用户上传工具配置        ② MCP-Server 处理          ③ Agent Manager 生成工具      │
│  ┌───────────────┐        ┌───────────────┐          ┌───────────────┐             │
│  │ 表单填写 或   │  ───→  │ 验证配置格式   │   ───→   │ 生成 Pydantic │             │
│  │ 上传JSON文件  │        │ 发送给AM服务   │          │ 工具代码文件   │             │
│  └───────────────┘        └───────────────┘          └───────────────┘             │
│                                  │                          │                      │
│                                  ↓                          ↓                      │
│                           ┌───────────────┐          ┌───────────────┐             │
│                           │ 存储工具信息   │   ←───   │ 返回工具标识   │             │
│                           │ 到 PostgreSQL │          │ (tool_ref_id) │             │
│                           └───────────────┘          └───────────────┘             │
│                                                                                     │
│  ④ 创建自定义Agent时                     ⑤ 部署Agent                               │
│  ┌───────────────┐                      ┌───────────────┐                          │
│  │ 选择已创建的   │   ───────────────→   │ 传递工具标识   │                          │
│  │ 外部数据工具   │                      │ 给AgentManager │                          │
│  └───────────────┘                      └───────────────┘                          │
│                                                                                     │
└─────────────────────────────────────────────────────────────────────────────────────┘

1.3 变更说明

变更项 旧方案 新方案
工具类型 模板工具 + API工具 统一为外部数据工具
工具代码生成 无 Agent Manager 生成并存储 Pydantic 工具文件
MCP-Server 存储 存储完整配置 只存储工具基本信息 + tool_ref_id 标识
部署方式 传递环境变量配置 传递工具标识列表，AM 根据标识加载文件部署

1.4 存储职责划分

┌─────────────────────────────────────────────────────────────────────────────┐
│                              存储职责划分                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  MCP-Server (PostgreSQL)              Agent Manager (文件系统/存储)         │
│  ┌─────────────────────────┐          ┌─────────────────────────┐          │
│  │ • 工具名称、描述         │          │ • Pydantic 工具代码文件  │          │
│  │ • URL、方法、认证类型    │          │ • 工具运行时配置         │          │
│  │ • tool_ref_id (标识)    │   ←───→  │ • 根据 tool_ref_id 索引  │          │
│  │ • 用户归属信息           │          │                         │          │
│  │ • 创建/更新时间          │          │                         │          │
│  └─────────────────────────┘          └─────────────────────────┘          │
│                                                                             │
│  部署流程：                                                                  │
│  MCP-Server 传 tool_ref_ids → Agent Manager 查找对应文件 → 部署到 AKS       │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

2. 数据结构设计

2.1 外部数据工具 JSON 模板格式

用户上传的 JSON 文件格式定义：

{
  "name": "weather-query-tool",
  "description": "查询天气信息的外部数据工具",
  "url": "https://api.weather.com/v1/forecast",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  "auth": {
    "type": "api_key",
    "key": "your-api-key-here",
    "in": "header",
    "name": "X-API-Key"
  },
  "request_params": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称",
        "required": true
      },
      "days": {
        "type": "integer",
        "description": "预报天数",
        "default": 7,
        "required": false
      }
    }
  },
  "request_body": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "查询内容"
      },
      "options": {
        "type": "object",
        "description": "查询选项",
        "properties": {
          "format": {
            "type": "string",
            "enum": ["json", "xml"],
            "default": "json"
          }
        }
      }
    }
  },
  "response_mapping": {
    "success_field": "status",
    "success_value": "ok",
    "data_field": "data.result",
    "error_field": "error.message"
  },
  "timeout": 30,
  "retry": {
    "max_attempts": 3,
    "delay_seconds": 1
  }
}

2.2 JSON 字段说明

字段 类型 必填 说明
name string ✅ 工具名称（唯一标识，1-100字符，支持中英文）
description string ❌ 工具描述
url string ✅ API 端点 URL
method string ✅ HTTP 方法（GET/POST/PUT/DELETE/PATCH）
headers object ❌ 自定义请求头（键值对）
auth object ❌ 认证配置
auth.type string ✅ 认证类型：api_key/bearer/basic/none
auth.key string 条件 API Key 或 Bearer Token
auth.in string 条件 Key 位置：header/query/body
auth.name string 条件 Key 名称（如 X-API-Key、Authorization）
auth.username string 条件 Basic Auth 用户名
auth.password string 条件 Basic Auth 密码
request_params object ❌ URL 查询参数定义（JSON Schema 格式）
request_body object ❌ 请求体定义（JSON Schema 格式）
response_mapping object ❌ 响应字段映射
timeout integer ❌ 超时时间（秒），默认 30
retry object ❌ 重试配置

2.3 认证类型详解

API Key 认证

{
  "auth": {
    "type": "api_key",
    "key": "sk-xxxxxxxxxxxx",
    "in": "header",
    "name": "X-API-Key"
  }
}

Bearer Token 认证

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

Basic Auth 认证

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

无认证

{
  "auth": {
    "type": "none"
  }
}

2.4 数据库模型设计

ExternalDataTool 模型（新增）

设计原则：MCP-Server 只存储必要的元信息和关联标识，工具的实际代码和运行配置由 Agent Manager 管理。

class ExternalDataTool(BaseModel, Base):
    """外部数据工具模型
    
    存储工具的基本信息和 Agent Manager 返回的标识，
    工具的 Pydantic 代码文件由 Agent Manager 生成并存储。
    """
    __tablename__ = "external_data_tools"
    
    # 基本信息（用于前端展示）
    name = Column(String(100), nullable=False)
    description = Column(Text)
    url = Column(String(500), nullable=False)  # 仅用于展示，实际配置在 AM
    method = Column(String(10), nullable=False, default="POST")
    auth_type = Column(String(20), default="none")  # 仅用于展示
    
    # Agent Manager 关联（核心字段）
    tool_ref_id = Column(String(100), unique=True)  # AM 返回的工具标识，部署时传给 AM
    status = Column(String(20), default="pending")  # pending, active, error
    error_message = Column(Text)  # 生成失败时的错误信息
    
    # 归属信息
    owner_id = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=False)
    tenant_id = Column(UUID(as_uuid=True), ForeignKey("tenants.id"))
    is_active = Column(Boolean, default=True)
    
    # 统计信息
    usage_count = Column(Integer, default=0)  # 被 Agent 使用次数
    
    # 关系
    owner = relationship("User", back_populates="external_data_tools")
    
    __table_args__ = (
        Index("idx_external_data_tool_owner", owner_id),
        Index("idx_external_data_tool_ref", tool_ref_id),
    )

说明：

  • tool_ref_id 是核心字段，部署 Agent 时传递给 Agent Manager
  • URL、method、auth_type 仅用于前端列表展示，实际的完整配置在 Agent Manager 侧
  • 不存储敏感信息（API Key 等），这些信息只传给 Agent Manager，不在 MCP-Server 落库

删除旧的 Tool 模型相关字段

需要删除 Tool 模型中的以下字段（或废弃整个模型）：

  • template
  • env_config
  • 其他模板工具相关字段

3. API 接口设计（MCP-Server 侧）

3.1 接口列表

序号 接口 方法 说明
1 /api/user/external-tools POST 创建外部数据工具
2 /api/user/external-tools GET 获取用户的外部数据工具列表
3 /api/user/external-tools/{tool_id} GET 获取工具详情
4 /api/user/external-tools/{tool_id} PUT 更新工具配置
5 /api/user/external-tools/{tool_id} DELETE 删除工具
6 /api/user/external-tools/upload POST 上传 JSON 文件创建工具
7 /api/user/external-tools/{tool_id}/test POST 测试工具连接
8 /api/user/custom-agents POST 创建自定义 Agent（更新）

3.2 创建外部数据工具

接口

POST /api/user/external-tools

请求体

{
  "name": "weather-query-tool",
  "description": "查询天气信息的外部数据工具",
  "url": "https://api.weather.com/v1/forecast",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "auth": {
    "type": "api_key",
    "key": "sk-xxxxxxxxxxxx",
    "in": "header",
    "name": "X-API-Key"
  },
  "request_params": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称",
        "required": true
      }
    }
  },
  "request_body": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "查询内容"
      }
    }
  },
  "response_mapping": {
    "data_field": "data.result"
  },
  "timeout": 30
}

响应

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "weather-query-tool",
    "tool_ref_id": "tool-weather-abc123",
    "status": "active",
    "created_at": "2026-01-23T10:00:00Z"
  },
  "message": "外部数据工具创建成功"
}

3.3 上传 JSON 文件创建工具

接口

POST /api/user/external-tools/upload
Content-Type: multipart/form-data

请求参数

参数 类型 必填 说明
file File ✅ JSON 配置文件（.json）

响应

同 3.2 创建接口

3.4 获取工具列表

接口

GET /api/user/external-tools

查询参数

参数 类型 必填 说明
status string ❌ 过滤状态：active/pending/error
page integer ❌ 页码，默认 1
page_size integer ❌ 每页数量，默认 20

响应

说明：列表只返回基本展示信息，完整配置由 Agent Manager 管理。

{
  "success": true,
  "data": {
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "weather-query-tool",
        "description": "查询天气信息的外部数据工具",
        "url": "https://api.weather.com/v1/forecast",
        "method": "POST",
        "auth_type": "api_key",
        "status": "active",
        "usage_count": 15,
        "created_at": "2026-01-23T10:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

3.5 获取工具详情

接口

GET /api/user/external-tools/{tool_id}

响应

注意：MCP-Server 只存储基本展示信息，不存储完整配置和敏感信息。

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "weather-query-tool",
    "description": "查询天气信息的外部数据工具",
    "url": "https://api.weather.com/v1/forecast",
    "method": "POST",
    "auth_type": "api_key",
    "tool_ref_id": "tool-weather-abc123",
    "status": "active",
    "usage_count": 15,
    "created_at": "2026-01-23T10:00:00Z",
    "updated_at": "2026-01-23T10:00:00Z"
  }
}

如需查看工具的完整配置（包括参数定义等），可调用 Agent Manager 的接口获取。

3.6 更新工具配置

接口

PUT /api/user/external-tools/{tool_id}

请求体

与创建接口格式相同，需要传递完整的工具配置（因为 MCP-Server 不存储完整配置）。

{
  "name": "weather-query-tool-v2",
  "description": "更新后的天气查询工具",
  "url": "https://api.weather.com/v2/forecast",
  "method": "POST",
  "auth": {
    "type": "api_key",
    "key": "new-api-key",
    "in": "header",
    "name": "X-API-Key"
  },
  "request_params": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称",
        "required": true
      }
    }
  },
  "timeout": 30
}

响应

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "weather-query-tool-v2",
    "tool_ref_id": "tool-weather-abc123-v2",
    "status": "active",
    "updated_at": "2026-01-23T11:00:00Z"
  },
  "message": "外部数据工具更新成功"
}

处理流程

  1. MCP-Server 接收完整配置
  2. 调用 Agent Manager 更新接口（传递新配置）
  3. Agent Manager 重新生成工具文件，返回新的 tool_ref_id
  4. MCP-Server 更新数据库中的基本信息和 tool_ref_id

3.7 删除工具

接口

DELETE /api/user/external-tools/{tool_id}

响应

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "message": "外部数据工具删除成功"
}

注意：删除工具时需要通知 Agent Manager 删除对应的工具文件。

3.8 测试工具连接

接口

POST /api/user/external-tools/{tool_id}/test

请求体（可选测试参数）

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

响应

{
  "success": true,
  "data": {
    "connected": true,
    "response_time_ms": 156,
    "status_code": 200,
    "sample_response": {
      "status": "ok",
      "data": {
        "city": "北京",
        "temperature": "15°C"
      }
    }
  },
  "message": "工具连接测试成功"
}

3.9 创建自定义 Agent（更新）

接口

POST /api/user/custom-agents

请求体

{
  "name": "my-data-agent",
  "description": "我的数据处理 Agent",
  "external_tools": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ],
  "cpuRequest": "500m",
  "cpuLimit": "1000m",
  "memoryRequest": "512Mi",
  "memoryLimit": "1Gi",
  "model": "gpt-4"
}

字段说明

参数 类型 必填 说明
name string ✅ Agent 名称
description string ❌ Agent 描述
external_tools string[] ✅ 外部数据工具 ID 列表
cpuRequest string ❌ CPU 请求量，默认 "100m"
cpuLimit string ❌ CPU 限制量
memoryRequest string ❌ 内存请求量，默认 "128Mi"
memoryLimit string ❌ 内存限制量
model string ❌ 使用的模型名称

响应

{
  "success": true,
  "data": {
    "name": "my-data-agent",
    "namespace": "ai-agents",
    "status": "Pending",
    "tools_attached": 2,
    "quotaRemaining": {
      "cpu": 3.5,
      "memory": 7.0
    }
  },
  "message": "自定义 Agent 创建成功"
}

4. Agent Manager 接口设计（模拟）

4.1 接口列表

序号 接口 方法 说明
1 /tools/generate POST 生成 Pydantic 工具文件
2 /tools/{tool_ref_id} PUT 更新工具文件
3 /tools/{tool_ref_id} DELETE 删除工具文件
4 /agents POST 创建 Agent（更新：支持工具标识列表）

4.2 生成工具文件

接口

POST {AGENT_MANAGER_URL}/tools/generate

请求体

{
  "name": "weather-query-tool",
  "description": "查询天气信息的外部数据工具",
  "url": "https://api.weather.com/v1/forecast",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "auth": {
    "type": "api_key",
    "key": "sk-xxxxxxxxxxxx",
    "in": "header",
    "name": "X-API-Key"
  },
  "request_params": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称",
        "required": true
      }
    }
  },
  "request_body": {},
  "response_mapping": {
    "data_field": "data.result"
  },
  "timeout": 30,
  "user_id": "user-123",
  "tenant_id": "tenant-456"
}

响应

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

4.3 更新工具文件

接口

PUT {AGENT_MANAGER_URL}/tools/{tool_ref_id}

请求体

同 4.2 生成接口（需要传递完整的工具配置）

响应

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

说明：Agent Manager 会生成新的工具文件，可能返回新的 tool_ref_id（版本更新）。

4.4 删除工具文件

接口

DELETE {AGENT_MANAGER_URL}/tools/{tool_ref_id}

响应

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

4.5 创建 Agent（更新）

接口

POST {AGENT_MANAGER_URL}/agents

请求体（新增 tool_refs 字段）

{
  "name": "my-data-agent",
  "template": "custom_agent",
  "config": {
    "user_id": "user-123",
    "cpu_request": "500m",
    "cpu_limit": "1000m",
    "memory_request": "512Mi",
    "memory_limit": "1Gi",
    "replicas": 1
  },
  "env": {
    "LLM_BASE_URL": "https://litellm.xxx.io",
    "OPENAI_API_KEY": "sk-xxx",
    "MODEL_NAME": "gpt-4"
  },
  "tool_refs": [
    "tool-weather-abc123",
    "tool-stock-def456"
  ]
}

新增字段说明

字段 类型 必填 说明
tool_refs string[] ❌ 外部数据工具标识列表，Agent 运行时加载这些工具

5. 工作流程详解

5.1 创建工具流程

┌──────────┐     ┌──────────────┐     ┌───────────────┐     ┌──────────────┐
│   前端   │────→│  MCP-Server  │────→│ Agent Manager │────→│  MCP-Server  │
└──────────┘     └──────────────┘     └───────────────┘     └──────────────┘
     │                 │                     │                     │
     │  1.提交配置     │                     │                     │
     │  (表单/JSON)   │                     │                     │
     │ ───────────────>│                     │                     │
     │                 │                     │                     │
     │                 │  2.验证配置格式     │                     │
     │                 │  3.调用 AM 接口     │                     │
     │                 │ ───────────────────>│                     │
     │                 │                     │                     │
     │                 │                     │  4.生成 Pydantic   │
     │                 │                     │     工具文件        │
     │                 │                     │                     │
     │                 │  5.返回 tool_ref_id │                     │
     │                 │ <───────────────────│                     │
     │                 │                     │                     │
     │                 │  6.存储到数据库     │                     │
     │                 │  (关联 tool_ref_id) │                     │
     │                 │                     │                     │
     │  7.返回结果     │                     │                     │
     │ <───────────────│                     │                     │
     │                 │                     │                     │

5.2 创建 Agent 并使用工具流程

┌──────────┐     ┌──────────────┐     ┌───────────────┐
│   前端   │────→│  MCP-Server  │────→│ Agent Manager │
└──────────┘     └──────────────┘     └───────────────┘
     │                 │                     │
     │  1.创建Agent    │                     │
     │  选择工具列表   │                     │
     │ ───────────────>│                     │
     │                 │                     │
     │                 │  2.查询工具信息     │
     │                 │  获取 tool_ref_ids  │
     │                 │                     │
     │                 │  3.调用 AM 创建     │
     │                 │  传递 tool_refs     │
     │                 │ ───────────────────>│
     │                 │                     │
     │                 │                     │  4.部署 Agent
     │                 │                     │  加载工具文件
     │                 │                     │
     │                 │  5.返回部署结果     │
     │                 │ <───────────────────│
     │                 │                     │
     │  6.返回结果     │                     │
     │ <───────────────│                     │
     │                 │                     │

6. 前端对接说明

6.1 工具管理页面

功能需求

  1. 工具列表展示

    • 显示用户创建的所有外部数据工具
    • 显示状态（active/pending/error）
    • 显示使用次数
    • 支持搜索和筛选

  2. 创建工具

    • 方式一：表单填写
    • 方式二：上传 JSON 文件
    • 实时验证配置格式

  3. 工具详情

    • 查看完整配置（敏感信息脱敏）
    • 编辑配置
    • 测试连接

  4. 删除工具

    • 检查是否被 Agent 使用
    • 确认删除

表单字段

字段 组件类型 说明
工具名称 Input 必填，1-100字符
描述 Textarea 可选
API URL Input 必填，URL 格式
HTTP 方法 Select GET/POST/PUT/DELETE/PATCH
请求头 键值对编辑器 可选
认证类型 Select api_key/bearer/basic/none
认证配置 动态表单 根据认证类型显示
请求参数 Schema 编辑器 可选
请求体 Schema 编辑器 可选
超时时间 InputNumber 默认 30 秒

6.2 创建 Agent 时选择工具

流程

  1. 获取用户的外部数据工具列表
  2. 多选工具
  3. 提交创建 Agent 请求时包含 external_tools 字段

UI 建议

  • 使用穿梭框或多选列表
  • 显示工具名称、描述、状态
  • 禁用 error 状态的工具

7. 实现步骤

7.1 Phase 1: 数据库和模型（预计 1 天）

  • 创建 ExternalDataTool 模型
  • 编写数据库迁移脚本
  • 添加模型关系
  • 废弃/清理旧的 Tool 模型相关代码

7.2 Phase 2: Agent Manager 客户端（预计 0.5 天）

  • 在 agent_manager_client.py 中添加工具相关方法
    • generate_tool()
    • update_tool()
    • delete_tool()
  • 更新 create_agent() 方法，支持 tool_refs 参数

7.3 Phase 3: API 接口实现（预计 2 天）

  • 实现 POST /api/user/external-tools 创建工具
  • 实现 POST /api/user/external-tools/upload 上传 JSON
  • 实现 GET /api/user/external-tools 获取列表
  • 实现 GET /api/user/external-tools/{tool_id} 获取详情
  • 实现 PUT /api/user/external-tools/{tool_id} 更新工具
  • 实现 DELETE /api/user/external-tools/{tool_id} 删除工具
  • 实现 POST /api/user/external-tools/{tool_id}/test 测试连接
  • 更新 POST /api/user/custom-agents 支持外部工具

7.4 Phase 4: 删除旧接口和代码（预计 0.5 天）

  • 删除旧的 /api/user/tools/* 接口
  • 删除旧的 /api/user/custom-agents/templates 接口
  • 清理相关的 Schema 定义
  • 更新文档

7.5 Phase 5: 测试和文档（预计 1 天）

  • 编写单元测试
  • 编写集成测试
  • 更新 API 文档
  • 更新前端对接文档

8. 错误码定义

HTTP状态码 错误代码 说明
400 invalid_config 工具配置格式无效
400 invalid_url URL 格式无效
400 invalid_auth 认证配置无效
400 invalid_json_file JSON 文件格式无效
400 tool_in_use 工具正在被 Agent 使用，无法删除
404 tool_not_found 工具不存在
409 tool_name_exists 工具名称已存在
500 am_generate_failed Agent Manager 生成工具失败
503 am_unavailable Agent Manager 服务不可用

9. 安全考虑

9.1 敏感信息处理

  1. 敏感信息不落库

    • API Key、Bearer Token、密码等敏感信息不存储在 MCP-Server
    • 敏感信息只在创建时传递给 Agent Manager，由 AM 安全存储

  2. 传输安全

    • MCP-Server 与 Agent Manager 之间通过 HTTPS 传输
    • 敏感信息在传输层加密

9.2 权限控制

  1. 用户只能操作自己创建的工具
  2. 删除工具前检查是否被 Agent 使用
  3. API 调用需要 JWT 认证

9.3 输入验证

  1. URL 格式验证（必须是有效的 HTTP/HTTPS URL）
  2. JSON Schema 格式验证
  3. 超时时间范围限制（1-300 秒）

10. 附录

10.1 JSON 配置文件示例

示例 1：天气查询工具

{
  "name": "weather-api",
  "description": "查询城市天气信息",
  "url": "https://api.weather.com/v1/forecast",
  "method": "GET",
  "auth": {
    "type": "api_key",
    "key": "your-weather-api-key",
    "in": "query",
    "name": "apikey"
  },
  "request_params": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称",
        "required": true
      },
      "units": {
        "type": "string",
        "description": "温度单位",
        "enum": ["metric", "imperial"],
        "default": "metric"
      }
    }
  },
  "response_mapping": {
    "data_field": "data.forecast"
  },
  "timeout": 10
}

示例 2：企业内部 API

{
  "name": "internal-crm-api",
  "description": "查询客户信息",
  "url": "https://internal.company.com/api/v2/customers",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "X-Request-ID": "{{uuid}}"
  },
  "auth": {
    "type": "bearer",
    "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "request_body": {
    "type": "object",
    "properties": {
      "customer_id": {
        "type": "string",
        "description": "客户ID",
        "required": true
      },
      "include_orders": {
        "type": "boolean",
        "description": "是否包含订单信息",
        "default": false
      }
    }
  },
  "response_mapping": {
    "success_field": "code",
    "success_value": 0,
    "data_field": "data",
    "error_field": "message"
  },
  "timeout": 30,
  "retry": {
    "max_attempts": 3,
    "delay_seconds": 2
  }
}

示例 3：数据库查询服务

{
  "name": "db-query-service",
  "description": "执行 SQL 查询",
  "url": "https://db-gateway.company.com/query",
  "method": "POST",
  "auth": {
    "type": "basic",
    "username": "readonly",
    "password": "secure-password-123"
  },
  "request_body": {
    "type": "object",
    "properties": {
      "database": {
        "type": "string",
        "description": "数据库名称",
        "required": true
      },
      "sql": {
        "type": "string",
        "description": "SQL 查询语句",
        "required": true
      },
      "params": {
        "type": "array",
        "description": "查询参数",
        "items": {
          "type": "string"
        }
      }
    }
  },
  "timeout": 60
}

文档结束

View Git Blame Copy Permalink