# 动态 Agent 生成器 API 文档

> **版本**: 2026-01-29 v1.1  
> **服务地址**: http://20.212.121.126  
> **模板参考**: [cicd-AKS](http://gitee.ath.cx:3000/xiaohei/cicd-AKS)

---

## 系统架构

```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│                              动态 Agent 生成流程                                      │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                     │
│   ┌─────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌────────────┐ │
│   │   用户请求   │ →  │  Agent Manager  │ →  │   Gitee 仓库    │ →  │ CI/CD 构建  │ │
│   │ (工具定义)  │    │  (代码生成)      │    │  (代码推送)     │    │ (ARM64镜像) │ │
│   └─────────────┘    └─────────────────┘    └─────────────────┘    └────────────┘ │
│                                                     │                      │       │
│                                                     ↓                      ↓       │
│                                             ┌─────────────┐         ┌──────────┐  │
│                                             │ Gitea Action │    →    │   ACR    │  │
│                                             │ (self-hosted)│         │  (镜像)   │  │
│                                             └─────────────┘         └──────────┘  │
│                                                                           │       │
│                                                                           ↓       │
│                                                                    ┌──────────┐  │
│                                                                    │   AKS    │  │
│                                                                    │  (部署)   │  │
│                                                                    └──────────┘  │
│                                                                           │       │
│                                                                           ↓       │
│                                                                    ┌──────────┐  │
│                                                                    │Azure DNS │  │
│                                                                    │ (域名)   │  │
│                                                                    └──────────┘  │
│                                                                                     │
└─────────────────────────────────────────────────────────────────────────────────────┘
```

---

## 配置信息

### LLM 配置（用于 AI 生成代码）

| 配置项 | 值 |
|--------|-----|
| 终结点 | \`https://litellm.graystone-fb459c5d.southeastasia.azurecontainerapps.io/v1\` |
| 模型 | \`taiji/claude-sonnet-4-5\` |
| API Key | \`sk-mPV5MVVVVvfGSkXA-ASQXQ\` |

### Gitee 配置

| 配置项 | 值 |
|--------|-----|
| API URL | \`http://gitee.ath.cx:3000/api/v1\` |
| 用户名 | \`zhanggangyong\` |
| Owner | \`xiaohei\` |
| 模板仓库 | [cicd-AKS](http://gitee.ath.cx:3000/xiaohei/cicd-AKS) |

### ACR 配置

| 配置项 | 值 |
|--------|-----|
| Registry | \`agnettaiji.azurecr.io\` |
| Namespace | \`ai-agents\` |

### Azure DNS 配置

| 配置项 | 值 |
|--------|-----|
| DNS Zone | \`taijiagnet.com\` |
| 资源组 | \`taiji-ai-v0\` |

### WAF 白名单 (重要!)

Gitee 服务器使用雷池 WAF 保护，需要将以下 IP 添加到白名单：

\`\`\`
4.144.251.116  (AKS 集群出口 IP)
\`\`\`

---

## API 接口列表

| 序号 | 接口 | 方法 | 说明 |
|------|------|------|------|
| 1 | \`/tools/generate\` | POST | 生成单个外部数据工具 |
| 2 | \`/tools/generate-agent\` | POST | 生成完整 Agent 并推送到 Gitee |
| 3 | \`/tools/{tool_ref_id}\` | GET | 获取工具/Agent 信息 |
| 4 | \`/tools/{tool_ref_id}\` | PUT | 更新工具配置 |
| 5 | \`/tools/{tool_ref_id}\` | DELETE | 删除工具 |
| 6 | \`/tools/{tool_ref_id}/test\` | POST | 测试工具连接 |
| 7 | \`/tools/{tool_ref_id}/build-status\` | GET | 查询构建状态 |
| 8 | \`/tools/{tool_ref_id}/deploy\` | POST | 部署 Agent |
| 9 | \`/tools/\` | GET | 列出所有工具/Agent |

---

## 1. 生成单个工具

### 接口

\`\`\`
POST /tools/generate
\`\`\`

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | ✅ | 工具名称 (1-100 字符) |
| description | string | ✅ | 工具描述 |
| url | string | ✅ | API 端点 URL |
| method | string | ✅ | HTTP 方法: GET/POST/PUT/DELETE/PATCH |
| user_id | string | ✅ | 用户 ID |
| tenant_id | string | ❌ | 租户 ID |
| auth | object | ❌ | 认证配置 |
| request_params | object | ❌ | URL 查询参数 (JSON Schema) |
| request_body | object | ❌ | 请求体定义 (JSON Schema) |
| timeout | integer | ❌ | 超时时间（秒），默认 30 |

### 认证配置 (auth)

#### API Key 认证

\`\`\`json
{
  "type": "api_key",
  "key": "sk-xxxxxxxxxxxx",
  "in": "header",
  "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/tools/generate \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "weather-query",
    "description": "查询城市天气",
    "url": "https://api.weather.com/v1/current",
    "method": "GET",
    "user_id": "user-001",
    "auth": {
      "type": "api_key",
      "key": "demo-key",
      "in": "query",
      "name": "appid"
    },
    "request_params": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "城市名称",
          "required": true
        }
      }
    }
  }'
\`\`\`

### 响应示例

\`\`\`json
{
  "success": true,
  "data": {
    "tool_ref_id": "tool-weather-query-a49e00fe",
    "name": "weather-query",
    "description": "查询城市天气",
    "created_at": "2026-01-29T10:00:00.000000"
  },
  "message": "工具生成成功"
}
\`\`\`

### 生成的工具代码示例

\`\`\`python
"""
工具: weather-query
描述: 查询城市天气
"""
import os
import json
from typing import Optional, Any
import httpx


async def weather_query(city: str) -> str:
    """
    查询城市天气
    
    Args:
        city: 城市名称
    
    Returns:
        API 响应结果 (JSON 格式)
    """
    url = "https://api.weather.com/v1/current"
    headers = {}
    params = {"city": city}
    params["appid"] = os.getenv("TOOL_API_KEY", "")
    
    try:
        async with httpx.AsyncClient(timeout=30) as client:
            response = await client.request(
                method="GET",
                url=url,
                headers=headers,
                params={k: v for k, v in params.items() if v is not None}
            )
            
            if response.status_code == 200:
                return json.dumps({
                    "success": True,
                    "data": response.json()
                }, ensure_ascii=False, indent=2)
            else:
                return json.dumps({
                    "success": False,
                    "status_code": response.status_code,
                    "error": response.text[:500]
                }, ensure_ascii=False)
                
    except Exception as e:
        return json.dumps({
            "success": False,
            "error": str(e)
        }, ensure_ascii=False)
\`\`\`

---

## 2. 生成完整 Agent（核心接口）

### 接口

\`\`\`
POST /tools/generate-agent
\`\`\`

### 功能描述

1. 根据工具定义生成 Pydantic AI 代码
2. 创建 Gitee 仓库并推送代码
3. 包含完整 CI/CD 配置（参考 [cicd-AKS](http://gitee.ath.cx:3000/xiaohei/cicd-AKS)）
4. 自动触发构建和部署
5. 自动创建 Azure DNS 记录

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| agent_name | string | ✅ | Agent 名称 (1-63 字符) |
| description | string | ✅ | Agent 描述 |
| tools | array | ✅ | 工具配置列表 |
| user_id | string | ✅ | 用户 ID |
| tenant_id | string | ❌ | 租户 ID |
| auto_deploy | boolean | ❌ | 是否自动部署到 AKS（默认 false） |

### 请求示例

\`\`\`bash
curl -X POST http://20.212.121.126/tools/generate-agent \\
  -H "Content-Type: application/json" \\
  -d '{
    "agent_name": "weather-agent",
    "description": "天气查询智能 Agent，支持获取全球城市天气信息",
    "user_id": "user-001",
    "auto_deploy": true,
    "tools": [
      {
        "name": "get_weather",
        "description": "获取指定城市的当前天气",
        "url": "https://api.openweathermap.org/data/2.5/weather",
        "method": "GET",
        "user_id": "user-001",
        "auth": {
          "type": "api_key",
          "key": "your-openweather-api-key",
          "in": "query",
          "name": "appid"
        },
        "request_params": {
          "type": "object",
          "properties": {
            "q": {
              "type": "string",
              "description": "城市名称",
              "required": true
            },
            "units": {
              "type": "string",
              "description": "温度单位: metric/imperial",
              "default": "metric"
            }
          }
        },
        "timeout": 30
      }
    ]
  }'
\`\`\`

### 响应示例

\`\`\`json
{
  "success": true,
  "data": {
    "agent_ref_id": "agent-agent-weather-agent-ac3c11",
    "repo_name": "agent-weather-agent-ac3c11",
    "repo_url": "http://gitee.ath.cx:3000/zhanggangyong/agent-weather-agent-ac3c11",
    "image_name": "agnettaiji.azurecr.io/ai-agents/agent-weather-agent-ac3c11:latest",
    "status": "building",
    "files_pushed": 9,
    "tools_count": 2,
    "expected_domain": "agent-weather-agent-ac3c11.taijiagnet.com",
    "expected_namespace": "agent-agent-weather-agent-ac3c11"
  },
  "message": "Agent 项目已创建并推送到 Gitee，CI/CD 正在构建中。部署后访问: http://agent-weather-agent-ac3c11.taijiagnet.com"
}
\`\`\`

### 生成的项目结构

\`\`\`
agent-weather-agent-{id}/
├── .gitea/workflows/
│   └── ci-cd.yaml              # CI/CD 配置（构建+部署+DNS）
├── src/
│   ├── __init__.py
│   └── server/
│       ├── __init__.py
│       ├── mcp_server.py       # MCP 服务器 + 工具定义
│       └── api_server.py       # FastAPI HTTP 服务器
├── run_api_server.py           # 入口文件
├── Dockerfile                  # Docker 构建文件
├── requirements.txt            # Python 依赖
└── README.md                   # 说明文档
\`\`\`

---

## 3-9. 其他接口

### 3. 获取工具/Agent 信息

\`\`\`
GET /tools/{tool_ref_id}
\`\`\`

### 4. 更新工具配置

\`\`\`
PUT /tools/{tool_ref_id}
\`\`\`

### 5. 删除工具

\`\`\`
DELETE /tools/{tool_ref_id}?delete_repo=false
\`\`\`

### 6. 测试工具连接

\`\`\`
POST /tools/{tool_ref_id}/test
\`\`\`

### 7. 查询构建状态

\`\`\`
GET /tools/{tool_ref_id}/build-status
\`\`\`

### 8. 部署 Agent

\`\`\`
POST /tools/{tool_ref_id}/deploy
\`\`\`

### 9. 列出所有工具/Agent

\`\`\`
GET /tools/?user_id=user-001
\`\`\`

---

## 错误码定义

| HTTP 状态码 | 错误代码 | 说明 |
|-------------|----------|------|
| 400 | invalid_config | 配置格式无效 |
| 400 | invalid_url | URL 格式无效 |
| 404 | tool_not_found | 工具不存在 |
| 409 | repo_creation_failed | 仓库创建失败 |
| 500 | generation_failed | 代码生成失败 |
| 500 | deployment_failed | 部署失败 |

---

## 完整使用流程

### 步骤 1: 创建 Agent

\`\`\`bash
curl -X POST http://20.212.121.126/tools/generate-agent \\
  -H "Content-Type: application/json" \\
  -d '{
    "agent_name": "my-custom-agent",
    "description": "我的自定义 Agent",
    "user_id": "user-001",
    "auto_deploy": true,
    "tools": [...]
  }'
\`\`\`

### 步骤 2: 等待构建完成

\`\`\`bash
curl http://20.212.121.126/tools/{agent_ref_id}/build-status
\`\`\`

### 步骤 3: 访问 Agent

\`\`\`bash
# 通过域名访问
curl http://{agent-name}.taijiagnet.com/

# 健康检查
curl http://{agent-name}.taijiagnet.com/health

# 调用工具
curl -X POST http://{agent-name}.taijiagnet.com/tools/call \\
  -H "Content-Type: application/json" \\
  -d '{"tool_name": "get_weather", "parameters": {"q": "Beijing"}}'

# MCP 调用
curl -X POST http://{agent-name}.taijiagnet.com/mcp \\
  -H "Content-Type: application/json" \\
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
\`\`\`

---

## Agent 端点说明

生成的 Agent 提供以下端点：

### REST API

| 端点 | 方法 | 说明 |
|------|------|------|
| \`/\` | GET | 服务信息 |
| \`/health\` | GET | 健康检查 |
| \`/tools\` | GET | 列出可用工具 |
| \`/tools/call\` | POST | 调用工具 |

### MCP 端点

| 端点 | 方法 | 说明 |
|------|------|------|
| \`/mcp\` | POST | MCP HTTP 端点 |
| \`/mcp/sse\` | GET | MCP SSE 端点 |
| \`/mcp/sse\` | POST | MCP SSE POST 端点 |

---

## CI/CD Secrets 配置

| Secret 名称 | 说明 |
|-------------|------|
| \`ACR_LOGIN_SERVER\` | ACR 登录服务器 |
| \`ACR_USERNAME\` | ACR 用户名 |
| \`ACR_PASSWORD\` | ACR 密码 |
| \`AZ_CLIENT_ID\` | Azure 服务主体 Client ID |
| \`AZ_CLIENT_SECRET\` | Azure 服务主体密钥 |
| \`AZ_TENANT_ID\` | Azure 租户 ID |
| \`AZ_SUBSCRIPTION_ID\` | Azure 订阅 ID |
| \`AZ_RG\` | AKS 资源组名称 |
| \`AZ_AKS\` | AKS 集群名称 |
| \`AZURE_DNS_ZONE\` | DNS Zone 名称 |

---

**文档更新记录**

| 日期 | 版本 | 更新内容 |
|------|------|----------|
| 2026-01-26 | v1.0 | 初始版本 |
| 2026-01-29 | v1.1 | 更新服务地址 (20.212.121.126)；添加 DNS 配置说明；添加 generate_tool_code 生成的代码示例；更新项目结构为 src/server/ 目录；添加 expected_domain/expected_namespace 响应字段；添加 Agent 端点说明；简化 Secrets 配置表格 |