Files

T

zhanggangyong 8cb166fb58 feat: 新增外部工具 API 及回调功能（计费）

主要更新:
- 新增 external_tool_api.py: 外部工具管理 API
- 新增 tool_storage.py: 工具存储管理器
- 新增回调功能用于计费 (agent_callback_utils)
- 支持多工具创建 Agent
- 新增 CI/CD 构建状态查询 API
- 新增部署信息查询 API
- 更新文档 (EXTERNAL_TOOL_API.md v2.0)
- 更新 Dockerfile 添加新模块
- 更新 app.py 集成外部工具路由

2026-01-29 12:00:16 +00:00

20 KiB

Raw Blame History

外部工具 API 文档

版本: 2026-01-29 v2.0
服务地址: http://20.212.121.126
规范参考: Agent-Manager外部工具接口规范

📊 系统架构

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

职责划分

组件	职责
MCP-Server	接收前端请求、存储工具基本信息和 tool_ref_id、调用 Agent Manager 接口
Agent Manager	生成 Pydantic 工具代码文件、存储完整配置（含敏感信息）、部署 Agent 到 AKS、集成计费回调
计费系统	接收 Agent 运行时长回调、记录使用的工具、计算费用

🆕 v2.0 新增功能

1. 回调功能（计费）

每个生成的 Agent 自动包含回调模块，用于向计费系统发送使用记录：

记录 Agent 运行时长
记录使用的工具列表
支持请求级别的计费追踪

2. 多工具支持

每个 Agent 可以包含多个工具，在创建时通过 tool_refs 数组指定。

3. 新增状态查询 API

GET /agents/{agent_ref_id}/build-status - 查询 CI/CD 构建状态
GET /agents/{agent_ref_id}/deployment-info - 查询部署详情

4. 批量工具调用

POST /tools/batch-call - 批量调用多个工具（统一计费）

🔐 通用规范

基础路径

http://20.212.121.126/external-tools

请求头

Content-Type: application/json
X-User-ID: <user_id>  # 可选，用于计费

响应格式

成功响应

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

错误响应

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

📑 接口列表

序号	接口	方法	说明
1	`/external-tools/generate`	POST	生成外部数据工具
2	`/external-tools/{tool_ref_id}`	GET	获取工具详情
3	`/external-tools/{tool_ref_id}`	PUT	更新外部数据工具
4	`/external-tools/{tool_ref_id}`	DELETE	删除外部数据工具
5	`/external-tools/{tool_ref_id}/test`	POST	测试工具连接
6	`/external-tools/{tool_ref_id}/code`	GET	获取生成的代码
7	`/external-tools/`	GET	列出所有工具
8	`/external-tools/agents/create-with-tools`	POST	创建带工具的 Agent
9	`/external-tools/agents/{agent_ref_id}/build-status`	GET	🆕 查询构建状态
10	`/external-tools/agents/{agent_ref_id}/deployment-info`	GET	🆕 查询部署信息
11	`/agents`	POST	创建 Agent（支持 tool_refs 字段）

1️⃣ 生成外部数据工具

接口

POST /external-tools/generate

功能描述

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

验证配置格式
根据配置生成 Pydantic AI 工具代码文件
存储工具代码文件和完整配置（包含敏感信息如 API Key）
返回唯一的 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"
}

请求示例

curl -X POST http://20.212.121.126/external-tools/generate \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weather-query",
    "description": "查询指定城市的天气信息",
    "url": "https://api.weather.com/v1/current",
    "method": "GET",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "auth": {
      "type": "api_key",
      "key": "sk-xxx",
      "in": "query",
      "name": "apikey"
    },
    "request_params": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "城市名称"
        }
      }
    }
  }'

响应示例

{
  "success": true,
  "data": {
    "tool_ref_id": "tool-weather-query-7ff71b5e",
    "name": "weather-query",
    "description": "查询指定城市的天气信息",
    "created_at": "2026-01-29T11:07:32.538533"
  },
  "message": "工具生成成功"
}

2️⃣ 更新外部数据工具

接口

PUT /external-tools/{tool_ref_id}

请求参数

参数	类型	必填	说明
description	string	❌	工具描述
url	string	❌	API URL
method	string	❌	HTTP 方法
headers	object	❌	自定义请求头
auth	object	❌	认证配置
request_params	object	❌	请求参数定义
request_body	object	❌	请求体定义
timeout	integer	❌	超时时间

请求示例

curl -X PUT http://20.212.121.126/external-tools/tool-weather-query-7ff71b5e \
  -H "Content-Type: application/json" \
  -d '{
    "description": "更新后的天气查询工具描述",
    "timeout": 60
  }'

响应示例

{
  "success": true,
  "data": {
    "tool_ref_id": "tool-weather-query-7ff71b5e",
    "name": "weather-query",
    "updated_at": "2026-01-29T11:09:12.322545"
  },
  "message": "工具更新成功"
}

3️⃣ 删除外部数据工具

接口

DELETE /external-tools/{tool_ref_id}

请求示例

curl -X DELETE http://20.212.121.126/external-tools/tool-weather-query-7ff71b5e

响应示例

{
  "success": true,
  "data": {
    "tool_ref_id": "tool-weather-query-7ff71b5e"
  },
  "message": "工具删除成功"
}

注意事项

如果工具正在被 Agent 使用，删除将失败并返回 tool_in_use 错误

4️⃣ 测试工具连接

接口

POST /external-tools/{tool_ref_id}/test

请求参数

参数	类型	必填	说明
test_params	object	❌	测试参数（URL 查询参数）
test_body	object	❌	测试请求体

请求示例

curl -X POST http://20.212.121.126/external-tools/tool-weather-query-7ff71b5e/test \
  -H "Content-Type: application/json" \
  -d '{"test_params": {"city": "Beijing"}}'

响应示例

{
  "success": true,
  "data": {
    "status_code": 200,
    "response_time_ms": 1058.84,
    "content_type": "application/json",
    "response_preview": "{...}"
  },
  "message": "连接测试成功"
}

5️⃣ 创建带有外部工具的 Agent（支持多工具）

接口

POST /external-tools/agents/create-with-tools

功能描述

创建带有外部工具的 Agent，自动：

加载对应的工具代码文件（支持多个工具）
将工具集成到 Agent 中
生成完整项目并推送到 Gitee
触发 CI/CD 构建和部署
集成计费回调功能

请求参数

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

请求示例（多工具）

curl -X POST http://20.212.121.126/external-tools/agents/create-with-tools \
  -H "Content-Type: application/json" \
  -d '{
    "name": "multi-tool-agent",
    "template": "custom_agent",
    "tool_refs": [
      "tool-search-api-60e5c2a1",
      "tool-weather-api-8e08be59",
      "tool-translate-api-82e0f9bd"
    ],
    "config": {
      "user_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

响应示例

{
  "success": true,
  "name": "multi-tool-agent",
  "agent_ref_id": "agent-agent-multi-tool-agent-ad2b92",
  "namespace": "agent-agent-multi-tool-agent-ad2b92",
  "status": "Building",
  "created_at": "2026-01-29T11:45:30.123456",
  "template": "custom_agent",
  "service_port": 8000,
  "access_info": {
    "domain": "agent-multi-tool-agent-ad2b92.taijiagnet.com",
    "domain_url": "http://agent-multi-tool-agent-ad2b92.taijiagnet.com",
    "ip_url": "pending"
  },
  "tools_attached": 3,
  "repo_url": "http://gitee.ath.cx:3000/zhanggangyong/agent-multi-tool-agent-ad2b92",
  "image_name": "agnettaiji.azurecr.io/ai-agents/agent-multi-tool-agent-ad2b92:latest",
  "status_query_url": "/external-tools/agents/agent-agent-multi-tool-agent-ad2b92/build-status",
  "deployment_info_url": "/external-tools/agents/agent-agent-multi-tool-agent-ad2b92/deployment-info"
}

6️⃣ 🆕 查询 CI/CD 构建状态

接口

GET /external-tools/agents/{agent_ref_id}/build-status

功能描述

查询 Agent 的 CI/CD 构建状态，包括：

Gitee Action 运行状态
ACR 镜像是否已构建
整体构建状态

响应示例

{
  "success": true,
  "data": {
    "agent_ref_id": "agent-agent-multi-tool-agent-ad2b92",
    "repo_name": "agent-multi-tool-agent-ad2b92",
    "overall_status": "ready",
    "gitee_action": {
      "status": "completed",
      "conclusion": "success",
      "run_id": 123,
      "html_url": "http://gitee.ath.cx:3000/.../actions/runs/123"
    },
    "acr_image": {
      "image_name": "agnettaiji.azurecr.io/ai-agents/agent-multi-tool-agent-ad2b92:latest",
      "exists": true,
      "tags": ["latest", "abc123"]
    },
    "access_info": {
      "expected_domain": "agent-multi-tool-agent-ad2b92.taijiagnet.com",
      "expected_url": "http://agent-multi-tool-agent-ad2b92.taijiagnet.com",
      "expected_namespace": "agent-agent-multi-tool-agent-ad2b92"
    }
  }
}

状态说明

overall_status	含义
`pending`	等待 CI/CD 开始
`building`	CI/CD 正在构建
`ready`	镜像已构建，等待部署
`deployed`	已部署到 K8s
`build_failed`	构建失败
`unknown`	状态未知

7️⃣ 🆕 查询部署详情

接口

GET /external-tools/agents/{agent_ref_id}/deployment-info

功能描述

查询 Agent 部署后的详细信息，包括：

K8s 部署状态
Pod 运行状态
服务端点信息
DNS 域名信息

响应示例

{
  "success": true,
  "data": {
    "agent_ref_id": "agent-agent-multi-tool-agent-ad2b92",
    "repo_name": "agent-multi-tool-agent-ad2b92",
    "namespace": "agent-agent-multi-tool-agent-ad2b92",
    "k8s_status": {
      "namespace_exists": true,
      "namespace_status": "Active",
      "pod_name": "agent-multi-tool-agent-ad2b92-xxx",
      "pod_status": "Running",
      "pod_ip": "10.224.0.50",
      "node_name": "aks-nodepool1-xxx",
      "status": "running"
    },
    "access_info": {
      "service_name": "agent-multi-tool-agent-ad2b92-service",
      "cluster_ip": "10.0.100.50",
      "external_ip": "20.x.x.x",
      "ip_url": "http://20.x.x.x",
      "domain": "agent-multi-tool-agent-ad2b92.taijiagnet.com",
      "domain_url": "http://agent-multi-tool-agent-ad2b92.taijiagnet.com",
      "recommended_url": "http://agent-multi-tool-agent-ad2b92.taijiagnet.com"
    },
    "image_info": {
      "image_name": "agnettaiji.azurecr.io/ai-agents/agent-multi-tool-agent-ad2b92:latest",
      "registry": "agnettaiji.azurecr.io"
    }
  }
}

8️⃣ 原有 /agents 接口 - 支持 tool_refs

接口

POST /agents

新增参数

参数	类型	必填	说明
tool_refs	string[]	❌	外部数据工具标识列表（支持多个）

请求示例

curl -X POST http://20.212.121.126/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-tools-agent",
    "template": "echo_agent",
    "framework": "API",
    "config": {
      "user_id": "test-user"
    },
    "tool_refs": ["tool-weather-query-7ff71b5e", "tool-stock-api-abc123"]
  }'

响应新增字段

字段	类型	说明
tools_attached	integer	附加的外部工具数量

🔔 回调功能（计费）

概述

每个生成的 Agent 自动集成回调功能，用于向计费系统发送使用记录。

生成的文件结构

src/server/
├── mcp_server.py           # MCP 服务器（工具定义）
├── api_server.py           # HTTP API（集成回调）
└── agent_callback_utils.py # 回调工具模块

回调数据格式

Agent 在处理请求时会自动发送以下数据到计费系统：

{
  "agentName": "multi-tool-agent",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "podRunningTimeSeconds": 5,
  "toolsUsed": ["search-api", "weather-api"],
  "startTime": "2026-01-29T11:45:30.000000+00:00",
  "endTime": "2026-01-29T11:45:35.000000+00:00",
  "requestId": "api-1738151130"
}

回调触发时机

每次 /tools/call 调用
每次 /tools/batch-call 调用
每次 MCP tools/call 请求

传递 User ID

通过以下方式传递 user_id 用于计费：

请求参数：在请求体中添加 user_id 字段
请求头：设置 X-User-ID 头
环境变量：Agent 启动时设置 USER_ID 环境变量

❌ 错误码定义

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

📋 完整使用流程示例

1. 创建多个工具

# 工具1: 搜索 API
TOOL1=$(curl -s -X POST http://20.212.121.126/external-tools/generate \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search-api",
    "description": "搜索API工具",
    "url": "https://api.search.com/v1/search",
    "method": "GET",
    "user_id": "user-123"
  }' | jq -r '.data.tool_ref_id')

# 工具2: 天气 API
TOOL2=$(curl -s -X POST http://20.212.121.126/external-tools/generate \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weather-api",
    "description": "获取天气信息",
    "url": "https://api.weather.com/v1/current",
    "method": "GET",
    "user_id": "user-123"
  }' | jq -r '.data.tool_ref_id')

echo "工具1: $TOOL1"
echo "工具2: $TOOL2"

2. 创建包含多工具的 Agent

AGENT_RESULT=$(curl -s -X POST http://20.212.121.126/external-tools/agents/create-with-tools \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"my-multi-tool-agent\",
    \"template\": \"custom_agent\",
    \"tool_refs\": [\"$TOOL1\", \"$TOOL2\"],
    \"config\": {\"user_id\": \"user-123\"}
  }")

AGENT_REF_ID=$(echo $AGENT_RESULT | jq -r '.agent_ref_id')
echo "Agent Ref ID: $AGENT_REF_ID"

3. 轮询构建状态

while true; do
  STATUS=$(curl -s "http://20.212.121.126/external-tools/agents/${AGENT_REF_ID}/build-status")
  OVERALL=$(echo $STATUS | jq -r '.data.overall_status')
  echo "当前状态: $OVERALL"
  
  if [ "$OVERALL" = "ready" ] || [ "$OVERALL" = "deployed" ]; then
    echo "✅ 构建完成！"
    break
  elif [ "$OVERALL" = "build_failed" ]; then
    echo "❌ 构建失败！"
    break
  fi
  sleep 30
done

4. 获取部署信息

curl -s "http://20.212.121.126/external-tools/agents/${AGENT_REF_ID}/deployment-info" | jq .

5. 访问 Agent

DOMAIN=$(curl -s "http://20.212.121.126/external-tools/agents/${AGENT_REF_ID}/deployment-info" \
  | jq -r '.data.access_info.domain')

curl "http://${DOMAIN}/"

📞 联系方式

如有疑问，请联系 Agent Manager 开发团队。

文档更新记录

日期	版本	更新内容
2026-01-29	v1.0	初始版本，实现 MCP-Server 外部工具接口规范
2026-01-29	v2.0	新增回调功能（计费）、多工具支持、构建状态查询、部署信息查询

20 KiB Raw Blame History Unescape Escape

外部工具 API 文档

📊 系统架构

职责划分

🆕 v2.0 新增功能

1. 回调功能（计费）

2. 多工具支持

3. 新增状态查询 API

4. 批量工具调用

🔐 通用规范

基础路径

请求头

响应格式

成功响应

错误响应

📑 接口列表

1️⃣ 生成外部数据工具

接口

功能描述

请求参数

认证配置 (auth) 结构

API Key 认证

Bearer Token 认证

Basic Auth 认证

请求示例

响应示例

2️⃣ 更新外部数据工具

接口

请求参数

请求示例

响应示例

3️⃣ 删除外部数据工具

接口

请求示例

响应示例

注意事项

4️⃣ 测试工具连接

接口

请求参数

请求示例

响应示例

5️⃣ 创建带有外部工具的 Agent（支持多工具）

接口

功能描述

请求参数

请求示例（多工具）

响应示例

6️⃣ 🆕 查询 CI/CD 构建状态

接口

功能描述

响应示例

状态说明

7️⃣ 🆕 查询部署详情

接口

功能描述

响应示例

8️⃣ 原有 /agents 接口 - 支持 tool_refs

接口

新增参数

请求示例

响应新增字段

🔔 回调功能（计费）

概述

生成的文件结构

回调数据格式

回调触发时机

传递 User ID

❌ 错误码定义

📋 完整使用流程示例

1. 创建多个工具

2. 创建包含多工具的 Agent

3. 轮询构建状态

4. 获取部署信息

5. 访问 Agent

📞 联系方式

20 KiB

Raw Blame History