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

15 KiB

Raw Blame History

动态 Agent 生成器 API 文档

版本: 2026-01-29 v1.1
服务地址: http://20.212.121.126
模板参考: 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

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 ```

功能描述

根据工具定义生成 Pydantic AI 代码
创建 Gitee 仓库并推送代码
包含完整 CI/CD 配置（参考 cicd-AKS）
自动触发构建和部署
自动创建 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 配置表格

15 KiB Raw Blame History Unescape Escape

动态 Agent 生成器 API 文档

系统架构

配置信息

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

Gitee 配置

ACR 配置

Azure DNS 配置

WAF 白名单 (重要!)

API 接口列表

1. 生成单个工具

接口

请求参数

认证配置 (auth)

API Key 认证

Bearer Token 认证

Basic Auth 认证

请求示例

响应示例

生成的工具代码示例

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

接口

功能描述

请求参数

请求示例

响应示例

生成的项目结构

3-9. 其他接口

3. 获取工具/Agent 信息

4. 更新工具配置

5. 删除工具

6. 测试工具连接

7. 查询构建状态

8. 部署 Agent

9. 列出所有工具/Agent

错误码定义

完整使用流程

步骤 1: 创建 Agent

步骤 2: 等待构建完成

步骤 3: 访问 Agent

通过域名访问

健康检查

调用工具

MCP 调用

Agent 端点说明

REST API

MCP 端点

CI/CD Secrets 配置

15 KiB

Raw Blame History