工具 API

端点

方法	路径	用途
GET	`/api/v1/tools`	列出所有工具
GET	`/api/v1/tools/id/{tool_id}`	通过 ID 获取工具详情
GET	`/api/v1/tools/name/{tool_name}?team_id={team_id}`	通过名称获取工具详情
POST	`/api/v1/tools/test`	单次测试工具（无独立执行端点）
POST	`/api/v1/tools/execute-code`	在沙箱中直接运行代码
POST	`/api/v1/tools?team_id={team_id}`	创建自定义工具
PUT	`/api/v1/tools/{tool_id}`	更新工具配置
DELETE	`/api/v1/tools/{tool_id}`	删除自定义工具

身份验证

所有端点需要经过认证的 JWT 用户会话。管理与执行路由不接受 API Key 认证。

所需权限：

tool:read — 查看工具
tool:create — 创建工具
tool:update — 更新工具
tool:delete — 删除工具
tool:execute — 执行/测试工具

列出工具

获取所有可用工具的列表，支持分页、搜索和多维筛选。

查询参数

参数	类型	必填	默认值	描述
`page`	integer	否	1	页码
`page_size`	integer	否	10	每页条数（最大 100）
`search`	string	否	-	按名称或显示名称搜索
`type`	array	否	-	按类型筛选：`builtin`、`custom`、`mcp`（可重复）
`category`	array	否	-	按分类筛选（可重复）
`status`	array	否	-	按启用状态筛选（可重复）
`team_id`	array	否	-	按所属团队筛选（可重复）
`creator`	array	否	-	按创建者筛选（可重复）

请求示例

curl -X GET "https://your-domain.com/api/v1/tools?category=search" \
  -H "Authorization: Bearer YOUR_TOKEN"

响应

成功 (200 OK)：

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "tool-123",
        "name": "web_search",
        "display_name": "Web Search",
        "description": "Search the internet for information",
        "type": "builtin",
        "category": "search",
        "icon": "🔍",
        "parameters": [
          {
            "name": "query",
            "type": "string",
            "description": "Search query",
            "required": true
          },
          {
            "name": "max_results",
            "type": "integer",
            "description": "Maximum number of results",
            "required": false,
            "default": 5
          }
        ],
        "is_enabled": true,
        "requires_config": false,
        "config_fields": [],
        "custom_type": null,
        "http_config": null,
        "code_config": null,
        "mcp_config": null,
        "team_id": null,
        "created_by_id": null,
        "created_by_name": null,
        "is_owned": true,
        "owner_team_id": null,
        "owner_team_name": null,
        "share_permission": null,
        "shared_with_count": 0
      }
    ],
    "total": 15,
    "page": 1,
    "page_size": 10
  },
  "msg": "success"
}

获取工具详情

支持通过工具 ID 或名称查询。名称查询需附加 team_id 参数。

路径参数

参数	类型	必填	描述
`tool_id`	string	是	工具 UUID（用于 `GET /id/{tool_id}`）
`tool_name`	string	是	工具名称（用于 `GET /name/{tool_name}`）

请求示例

curl -X GET "https://your-domain.com/api/v1/tools/id/tool-123" \
  -H "Authorization: Bearer YOUR_TOKEN"

响应

成功 (200 OK)：

{
  "code": 0,
  "data": {
    "id": "tool-123",
    "name": "web_search",
    "display_name": "Web Search",
    "description": "Search the internet for information",
    "type": "builtin",
    "category": "search",
    "icon": "🔍",
    "parameters": [...],
    "is_enabled": true,
    "requires_config": false,
    "config_fields": [],
    "custom_type": null,
    "http_config": null,
    "code_config": null,
    "mcp_config": null,
    "team_id": null,
    "created_by_id": null,
    "created_by_name": null,
    "is_owned": true,
    "owner_team_id": null,
    "owner_team_name": null,
    "share_permission": null,
    "shared_with_count": 0,
    "created_at": null,
    "updated_at": null
  },
  "msg": "success"
}

测试工具

按名称单次执行工具并传入参数。注意： 没有独立的 POST /tools/{tool_id}/execute 端点，统一使用此接口。

请求体

{
  "name": "web_search",
  "arguments": {
    "query": "artificial intelligence",
    "max_results": 5
  }
}

请求字段

字段	类型	必填	描述
`name`	string	是	工具名称
`arguments`	object	否	工具参数

请求示例

curl -X POST "https://your-domain.com/api/v1/tools/test" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web_search",
    "arguments": {
      "query": "artificial intelligence",
      "max_results": 5
    }
  }'

响应

成功 (200 OK)：

{
  "code": 0,
  "data": {
    "name": "web_search",
    "success": true,
    "result": {
      "results": [
        {
          "title": "Artificial Intelligence - Wikipedia",
          "url": "https://en.wikipedia.org/wiki/Artificial_intelligence",
          "snippet": "Artificial intelligence (AI) is intelligence demonstrated by machines..."
        }
      ]
    },
    "error": null,
    "logs": null,
    "artifacts": [],
    "duration_ms": 1200
  },
  "msg": "success"
}

错误 (400 Bad Request)：

{
  "code": 1001,
  "data": {
    "field": "arguments.query",
    "error": "Query is required"
  },
  "msg": "Validation failed"
}

执行代码

直接在沙箱中运行 JavaScript/Python 代码，无需保存为工具。

请求体

{
  "language": "python",
  "code": "print(1 + 1)",
  "params": {},
  "timeout": 30,
  "python_packages": ["requests"]
}

请求字段

字段	类型	必填	描述
`language`	string	是	代码语言：`javascript`、`python`
`code`	string	是	代码内容
`params`	object	否	输入参数
`timeout`	number	否	超时秒数（1-60，默认 30）
`command`	array	否	自定义命令（argv 数组）
`python_packages`	array	否	需要安装的 Python 包
`js_packages`	array	否	需要安装的 JavaScript 包
`python_package_index_url`	string	否	Python 包镜像 URL
`node_package_registry_url`	string	否	JavaScript 包注册表 URL
`artifacts`	array	否	沙箱产物配置
`limits`	object	否	资源限制（timeout_seconds、disk_mb、max_stdout_kb、max_stderr_kb）

请求示例

curl -X POST "https://your-domain.com/api/v1/tools/execute-code" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "code": "print(1 + 1)"
  }'

响应

成功 (200 OK)：

{
  "code": 0,
  "data": {
    "success": true,
    "result": "2\n",
    "error": null,
    "logs": null,
    "artifacts": [],
    "duration_ms": 350
  },
  "msg": "success"
}

创建自定义工具

创建自定义工具。team_id 为必填查询参数。

查询参数

参数	类型	必填	描述
`team_id`	string	是	拥有该工具的团队 UUID

请求体

{
  "name": "crm_lookup",
  "display_name": "CRM Lookup",
  "description": "Look up customer information in CRM",
  "category": "data",
  "type": "custom",
  "custom_type": "http",
  "icon": "👤",
  "parameters": [
    {
      "name": "customer_id",
      "type": "string",
      "required": true,
      "description": "Customer ID to lookup"
    }
  ],
  "http_config": {
    "method": "GET",
    "url": "https://api.crm.example.com/customers/{customer_id}",
    "headers": {
      "X-API-Key": "crm_..."
    },
    "timeout": 30
  },
  "credentials": {},
  "is_enabled": true
}

请求字段

字段	类型	必填	描述
`name`	string	是	工具名称（唯一标识，最大 100 字符）
`display_name`	string	是	显示名称（最大 100 字符）
`description`	string	否	工具描述
`icon`	string	否	图标（emoji 或 URL，最大 100 字符）
`category`	string	否	工具分类（默认 `other`）
`type`	string	否	工具类型：`builtin`、`custom`、`mcp`（默认 `custom`）
`custom_type`	string	否	自定义工具类型：`http`、`code`、`mcp`（仅 `type=custom` 时有效）
`parameters`	array	否	参数定义（name、type、description、required、enum、default）
`http_config`	object	否	HTTP 配置（method、url、headers、query_params、body_template、content_type、form_fields、timeout、response_path）
`code_config`	object	否	代码配置（language、code、command、python_packages、js_packages、artifacts、limits）
`mcp_config`	object	否	MCP Server 配置（transport、command、args、env、url、headers）
`credentials`	object	否	工具凭证
`is_enabled`	boolean	否	启用状态（默认 true）

请求示例

curl -X POST "https://your-domain.com/api/v1/tools?team_id=team-123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "crm_lookup",
    "display_name": "CRM Lookup",
    "description": "Look up customer information in CRM",
    "category": "data",
    "type": "custom",
    "custom_type": "http",
    "parameters": [
      {
        "name": "customer_id",
        "type": "string",
        "required": true
      }
    ],
    "http_config": {
      "method": "GET",
      "url": "https://api.crm.example.com/customers/{customer_id}"
    }
  }'

响应

成功 (200 OK)：

{
  "code": 0,
  "data": {
    "id": "tool-789",
    "name": "crm_lookup",
    "display_name": "CRM Lookup",
    "description": "Look up customer information in CRM",
    "type": "custom",
    "category": "data",
    "custom_type": "http",
    "is_enabled": true,
    "team_id": "team-123",
    "created_at": "2026-02-11T16:00:00Z",
    "updated_at": "2026-02-11T16:00:00Z",
    "created_by_name": "alice"
  },
  "msg": "Tool created successfully"
}

更新工具

更新工具配置。所有字段均为可选，只需包含要更新的字段。

路径参数

参数	类型	必填	描述
`tool_id`	string	是	工具 UUID

请求体

{
  "display_name": "CRM Lookup (Updated)",
  "is_enabled": true,
  "http_config": {
    "timeout": 60
  }
}

请求示例

curl -X PUT "https://your-domain.com/api/v1/tools/tool-789" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "CRM Lookup (Updated)",
    "is_enabled": true
  }'

响应

成功 (200 OK)：

{
  "code": 0,
  "data": {
    "id": "tool-789",
    "name": "crm_lookup",
    "display_name": "CRM Lookup (Updated)",
    "type": "custom",
    "is_enabled": true,
    "team_id": "team-123",
    "created_at": "2026-02-11T16:00:00Z",
    "updated_at": "2026-02-11T16:05:00Z",
    "created_by_name": "alice"
  },
  "msg": "Tool updated successfully"
}

删除工具

删除自定义工具。

路径参数

参数	类型	必填	描述
`tool_id`	string	是	工具 UUID

请求示例

curl -X DELETE "https://your-domain.com/api/v1/tools/tool-789" \
  -H "Authorization: Bearer YOUR_TOKEN"

响应

成功 (200 OK)：

{
  "code": 0,
  "data": null,
  "msg": "Tool deleted successfully"
}

错误代码

代码	消息	描述
`4000`	Not found	工具不存在
`3000`	Permission denied	权限不足
`1001`	Validation failed	请求数据无效

注意： 当前无每端点限流实现，这些端点未配置限流中间件。代码 6300-6306 保留给 SSO 错误，工具 API 未使用。

代码示例

Python

import requests

def list_tools(token):
    """列出所有可用工具。"""
    url = "https://your-domain.com/api/v1/tools"
    headers = {
        "Authorization": f"Bearer {token}"
    }

    response = requests.get(url, headers=headers)
    result = response.json()

    if result['code'] == 0:
        return result['data']['items']
    else:
        raise Exception(f"Error: {result['msg']}")

def test_tool(token, name, arguments):
    """单次执行工具。"""
    url = "https://your-domain.com/api/v1/tools/test"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }
    data = {
        "name": name,
        "arguments": arguments
    }

    response = requests.post(url, headers=headers, json=data)
    result = response.json()

    if result['code'] == 0:
        return result['data']['result']
    else:
        raise Exception(f"Error: {result['msg']}")

# 使用
tools = list_tools("YOUR_TOKEN")
for tool in tools:
    print(f"Tool: {tool['display_name']} ({tool['category']})")

# 执行网络搜索
result = test_tool(
    "YOUR_TOKEN",
    "web_search",
    {"query": "artificial intelligence", "max_results": 5}
)
print(f"Search results: {result['results']}")

JavaScript

async function listTools(token) {
  const response = await fetch(
    'https://your-domain.com/api/v1/tools',
    {
      headers: {
        'Authorization': `Bearer ${token}`,
      },
    }
  );

  const result = await response.json();

  if (result.code === 0) {
    return result.data.items;
  } else {
    throw new Error(result.msg);
  }
}

async function testTool(token, name, arguments) {
  const response = await fetch(
    'https://your-domain.com/api/v1/tools/test',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        name: name,
        arguments: arguments,
      }),
    }
  );

  const result = await response.json();

  if (result.code === 0) {
    return result.data.result;
  } else {
    throw new Error(result.msg);
  }
}

// 使用
const tools = await listTools('YOUR_TOKEN');
tools.forEach(tool => {
  console.log(`Tool: ${tool.display_name} (${tool.category})`);
});

// 执行网络搜索
const result = await testTool(
  'YOUR_TOKEN',
  'web_search',
  { query: 'artificial intelligence', max_results: 5 }
);
console.log('Search results:', result.results);

工具 API

本页目录