zhanggangyong
8cb166fb58
主要更新: - 新增 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 集成外部工具路由
521 lines
15 KiB
Markdown
521 lines
15 KiB
Markdown
# 动态 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 配置表格 |
|