agent_management/docs/EXTERNAL_TOOL_API.md

# 外部工具 API 文档

> **版本**: 2026-01-31 v2.2  
> **服务地址**: 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.2 新增功能

### 1. 简化版工具生成接口 🚀

新增 `/external-tools/generate-simple` 接口，**默认使用 AI 辅助生成**，只需三个核心字段：

| 核心字段 | 说明 |
|----------|------|
| `url` | API 端点 URL |
| `auth` | 认证配置（支持 `token` 和 `key` 字段） |
| `request_body_schema` | 请求体 Schema（JSON Schema 格式） |

### 2. AuthConfig 增强

认证配置现在同时支持 `token` 和 `key` 字段（兼容更多使用习惯）：

```json
{
  "type": "bearer",
  "token": "your-api-token"  // 与 "key" 等效
}
```

### 3. TOOL_API_KEY 环境变量自动注入 ⭐

创建 Agent 时，系统会自动从工具配置中提取 API Key，并注入到 K8s Deployment 的环境变量中：

```yaml
env:
- name: TOOL_API_KEY
  value: "your-extracted-api-key"
```

工具代码可以通过 `os.getenv("TOOL_API_KEY")` 获取。

### 4. use_ai 默认开启

`/external-tools/generate` 接口的 `use_ai` 参数现在默认为 `True`，AI 会更智能地生成工具代码。

---

## 🆕 v2.1 新增功能

### 1. 资源配置支持

创建 Agent 时可以自定义 **CPU、内存、副本数** 等 K8s 资源配置：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `cpu_request` | `"100m"` | CPU 请求（如 100m, 500m） |
| `cpu_limit` | `"500m"` | CPU 限制（如 500m, 1000m） |
| `memory_request` | `"128Mi"` | 内存请求（如 128Mi, 256Mi） |
| `memory_limit` | `"512Mi"` | 内存限制（如 512Mi, 1Gi） |
| `replicas` | `1` | 副本数量（1-10） |

---

## 🆕 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 | 生成外部数据工具（完整版） |
| **1.1** | **`/external-tools/generate-simple`** | **POST** | **🆕 简化版工具生成（AI 辅助，推荐）** |
| 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": "工具生成成功"
}
```

---

## 1.1️⃣ 🆕 简化版工具生成（推荐）

### 接口

```
POST /external-tools/generate-simple
```

### 功能描述

简化版工具生成接口，**默认使用 AI 辅助生成**，只需提供三个核心字段。AI 会智能理解您的配置并生成高质量的 Pydantic AI 工具代码。

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | ✅ | 工具名称（1-100 字符） |
| url | string | ✅ | **核心字段** - API 端点 URL |
| method | string | ❌ | HTTP 方法，默认 `POST` |
| user_id | string | ❌ | 用户 ID，默认 `default` |
| auth | object | ❌ | **核心字段** - 认证配置（支持 `token` 或 `key`） |
| request_body_schema | object | ❌ | **核心字段** - 请求体 Schema（JSON Schema 格式） |
| request_params | object | ❌ | URL 查询参数定义 |
| headers | object | ❌ | 自定义请求头 |
| description | string | ❌ | 工具描述（可选，AI 会自动推断） |
| api_key | string | ❌ | LLM API Key（可选，使用系统默认） |

### 认证配置（支持两种字段名）

```json
// 方式1: 使用 token 字段
{
  "type": "bearer",
  "token": "your-api-token"
}

// 方式2: 使用 key 字段
{
  "type": "bearer",
  "key": "your-api-key"
}
```

### 请求示例

```bash
curl -X POST http://20.212.121.126/external-tools/generate-simple \
  -H "Content-Type: application/json" \
  -d '{
    "name": "jina_reader",
    "url": "https://r.jina.ai/",
    "method": "POST",
    "user_id": "test-user",
    "auth": {
      "type": "bearer",
      "token": "jina_xxxxxxxxxxxxxx"
    },
    "request_body_schema": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "要爬取的网页URL"
        }
      },
      "required": ["url"]
    }
  }'
```

### 响应示例

```json
{
  "success": true,
  "data": {
    "tool_ref_id": "tool-jina_reader-d57dcc49",
    "name": "jina_reader",
    "description": "调用 jina_reader API，参数: url",
    "url": "https://r.jina.ai/",
    "method": "POST",
    "has_auth": true,
    "created_at": "2026-01-30T17:25:13.855295"
  },
  "message": "工具生成成功 (AI 辅助)"
}
```

### AI 生成的代码示例

AI 会智能理解 API 的调用方式，例如 Jina Reader API 需要将目标 URL 拼接到路径中：

```python
async def jina_reader(url: str) -> str:
    """调用 jina_reader API 爬取网页内容"""
    api_key = os.getenv("TOOL_API_KEY", "default_key")
    
    # AI 正确理解了 URL 拼接方式
    api_url = f"https://r.jina.ai/{url}"
    
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    async with httpx.AsyncClient(timeout=60.0) as client:
        response = await client.post(api_url, headers=headers)
        # ... 完整的错误处理
```

---

## 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 | ❌ | `{}` | 其他配置（如 user_id） |
| env | object | ❌ | `{}` | 环境变量 |
| **cpu_request** | string | ❌ | `"100m"` | 🆕 CPU 请求（如 100m, 500m） |
| **cpu_limit** | string | ❌ | `"500m"` | 🆕 CPU 限制（如 500m, 1000m） |
| **memory_request** | string | ❌ | `"128Mi"` | 🆕 内存请求（如 128Mi, 256Mi） |
| **memory_limit** | string | ❌ | `"512Mi"` | 🆕 内存限制（如 512Mi, 1Gi） |
| **replicas** | int | ❌ | `1` | 🆕 副本数量（1-10） |

### 请求示例（多工具 + 资源配置）

```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"
    },
    "cpu_request": "200m",
    "cpu_limit": "1000m",
    "memory_request": "256Mi",
    "memory_limit": "1Gi",
    "replicas": 2
  }'
```

### 响应示例

```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"
  },
  "resources": {
    "cpu_request": "200m",
    "cpu_limit": "1000m",
    "memory_request": "256Mi",
    "memory_limit": "1Gi",
    "replicas": 2
  },
  "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\"},
    \"cpu_request\": \"200m\",
    \"cpu_limit\": \"1000m\",
    \"memory_request\": \"256Mi\",
    \"memory_limit\": \"1Gi\",
    \"replicas\": 2
  }")

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

### 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 | 新增回调功能（计费）、多工具支持、构建状态查询、部署信息查询 |
| 2026-01-30 | v2.1 | 新增资源配置参数（cpu_request, cpu_limit, memory_request, memory_limit, replicas） |
| 2026-01-31 | v2.2 | 🆕 新增简化版工具生成接口 `/generate-simple`、AuthConfig 支持 `token` 字段、TOOL_API_KEY 环境变量自动注入、use_ai 默认开启 |