agent_management/docs/EXTERNAL_TOOL_API.md

# 外部工具 API 文档

> **版本**: 2026-01-29 v2.0  
> **服务地址**: http://20.212.121.126  
> **规范参考**: [Agent-Manager外部工具接口规范](http://gitee.ath.cx:3000/xiaohei/taiji-AI-PAD/src/branch/feature/chenchen/Docs/Agent-Manager%E5%A4%96%E9%83%A8%E5%B7%A5%E5%85%B7%E6%8E%A5%E5%8F%A3%E8%A7%84%E8%8C%83.md)

---

## 📊 系统架构

```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│                              系统交互流程                                             │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                     │
│   ┌─────────────┐         ┌─────────────────┐         ┌─────────────────┐          │
│   │   前端      │   ───→  │   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
```

### 请求头

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

### 响应格式

#### 成功响应

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

#### 错误响应

```json
{
  "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 需要：
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 认证

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

#### Bearer Token 认证

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

#### Basic Auth 认证

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

### 请求示例

```bash
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": "城市名称"
        }
      }
    }
  }'
```

### 响应示例

```json
{
  "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 | ❌ | 超时时间 |

### 请求示例

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

### 响应示例

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

### 请求示例

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

### 响应示例

```json
{
  "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 | ❌ | 测试请求体 |

### 请求示例

```bash
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"}}'
```

### 响应示例

```json
{
  "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，自动：
1. 加载对应的工具代码文件（**支持多个工具**）
2. 将工具集成到 Agent 中
3. 生成完整项目并推送到 Gitee
4. 触发 CI/CD 构建和部署
5. **集成计费回调功能**

### 请求参数

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

### 请求示例（多工具）

```bash
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"
    }
  }'
```

### 响应示例

```json
{
  "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 镜像是否已构建
- 整体构建状态

### 响应示例

```json
{
  "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 域名信息

### 响应示例

```json
{
  "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[] | ❌ | 外部数据工具标识列表（支持多个） |

### 请求示例

```bash
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 在处理请求时会自动发送以下数据到计费系统：

```json
{
  "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` 用于计费：

1. **请求参数**：在请求体中添加 `user_id` 字段
2. **请求头**：设置 `X-User-ID` 头
3. **环境变量**：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. 创建多个工具

```bash
# 工具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

```bash
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. 轮询构建状态

```bash
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. 获取部署信息

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

### 5. 访问 Agent

```bash
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 | 新增回调功能（计费）、多工具支持、构建状态查询、部署信息查询 |