工具开发指南

概述

工具 (Tool) 是 AI 可以调用的原子操作。当用户向 AI 提出问题时，AI 会根据工具的名称和描述自动判断需要调用哪些工具。每个工具定义包含三个核心要素：

描述 -- AI 用来理解工具用途
输入参数 -- JSON Schema 格式的参数定义
执行方式 -- 工具被调用时的实际执行逻辑

执行方式

HTTP 工具

最常用的工具类型，AI 调用时向指定 URL 发送 HTTP 请求：

json

{
  "name": "weather_query",
  "description": "查询指定城市的实时天气",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": { "type": "string", "description": "城市名称" }
    },
    "required": ["city"]
  },
  "execution": {
    "type": "http",
    "method": "GET",
    "url": "https://api.example.com/weather?city={city}"
  }
}

URL 中的 {city} 占位符会被 AI 传入的参数值自动替换。

支持的 HTTP 配置：

字段	说明
`type`	固定为 `"http"`
`method`	HTTP 方法：GET, POST, PUT, DELETE
`url`	请求 URL，支持 `{param}` 占位符
`headers`	自定义请求头
`params`	URL 查询参数
`body`	POST/PUT 请求体

POST 请求示例：

json

{
  "execution": {
    "type": "http",
    "method": "POST",
    "url": "https://erp.example.com/api/orders",
    "headers": {
      "Authorization": "Bearer {token}"
    },
    "body": {
      "product_id": "{product_id}",
      "quantity": "{quantity}"
    }
  }
}

Handler 工具

自定义处理函数，需要桌面代理 (Desktop Agent) 执行：

json

{
  "execution": {
    "type": "handler",
    "handler": "custom_function_name"
  }
}

Handler 工具的测试执行会返回提示消息，实际执行在桌面代理环境中完成。

注册工具

cURLPythonNode.js

bash

curl -X POST https://api.invoratec.cn/v1/tools \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "erp_get_inventory",
    "description": "查询 ERP 系统的库存数据，返回指定仓库的所有商品库存",
    "appId": "my-erp",
    "input_schema": {
      "type": "object",
      "properties": {
        "warehouse_id": {
          "type": "string",
          "description": "仓库ID，格式为 WH-XXX"
        },
        "product_code": {
          "type": "string",
          "description": "产品编码，格式为 PRD-XXXX（可选，不填则返回全部）"
        }
      },
      "required": ["warehouse_id"]
    },
    "execution": {
      "type": "http",
      "method": "GET",
      "url": "https://erp.example.com/api/inventory?wh={warehouse_id}&product={product_code}"
    }
  }'

python

claw.tools.register(
    name="erp_get_inventory",
    description="查询 ERP 系统的库存数据，返回指定仓库的所有商品库存",
    input_schema={
        "type": "object",
        "properties": {
            "warehouse_id": {
                "type": "string",
                "description": "仓库ID，格式为 WH-XXX"
            },
            "product_code": {
                "type": "string",
                "description": "产品编码（可选）"
            }
        },
        "required": ["warehouse_id"]
    },
    execution={
        "type": "http",
        "method": "GET",
        "url": "https://erp.example.com/api/inventory?wh={warehouse_id}&product={product_code}"
    }
)

javascript

await claw.tools.register({
  name: 'erp_get_inventory',
  description: '查询 ERP 系统的库存数据，返回指定仓库的所有商品库存',
  appId: 'my-erp',
  inputSchema: {
    type: 'object',
    properties: {
      warehouse_id: {
        type: 'string',
        description: '仓库ID，格式为 WH-XXX'
      },
      product_code: {
        type: 'string',
        description: '产品编码（可选）'
      }
    },
    required: ['warehouse_id']
  },
  execution: {
    type: 'http',
    method: 'GET',
    url: 'https://erp.example.com/api/inventory?wh={warehouse_id}&product={product_code}'
  }
})

如果 name 已存在，API 会自动执行更新。

编写好的工具描述

工具描述直接影响 AI 调用工具的准确性。好的描述应该：

推荐写法：

json

{
  "name": "hr_get_employee_attendance",
  "description": "查询指定员工的考勤记录。返回迟到、早退、缺勤等统计数据。可按月份过滤。适用于HR需要查看某人考勤情况的场景。"
}

避免的写法：

json

{
  "name": "get_data",
  "description": "获取数据"
}

编写建议：

说明工具做什么和返回什么
说明适用场景
在参数 description 中说明格式要求
使用中文描述，让 AI 更好理解业务语义

输入参数 Schema

使用标准 JSON Schema 定义工具输入参数：

json

{
  "input_schema": {
    "type": "object",
    "properties": {
      "start_date": {
        "type": "string",
        "description": "开始日期，格式 YYYY-MM-DD",
        "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
      },
      "department": {
        "type": "string",
        "description": "部门名称",
        "enum": ["技术部", "市场部", "人事部", "财务部"]
      },
      "limit": {
        "type": "integer",
        "description": "返回条数上限",
        "default": 10,
        "minimum": 1,
        "maximum": 100
      }
    },
    "required": ["start_date"]
  }
}

支持的 JSON Schema 类型：string, integer, number, boolean, array, object。

测试工具

注册完成后，使用测试接口验证工具是否正常工作：

cURLPythonNode.js

bash

curl -X POST https://api.invoratec.cn/v1/tools/erp_get_inventory/test \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "warehouse_id": "WH-001" }
  }'

python

result = claw.tools.test("erp_get_inventory", input={"warehouse_id": "WH-001"})
print(result)
# {"status": "success", "result": {...}, "elapsed_ms": 230}

javascript

const result = await claw.tools.test('erp_get_inventory', {
  input: { warehouse_id: 'WH-001' }
})
console.log(result.status)      // 'success'
console.log(result.elapsed_ms)  // 230

测试在沙箱环境中执行，HTTP 工具的超时时间为 10 秒。

工具包

工具包 (Tool Pack) 是一组相关工具的集合，还可以附加 AI 知识提示，帮助 AI 更好地理解和使用这些工具。

创建工具包

cURLPythonNode.js

bash

curl -X POST https://api.invoratec.cn/v1/tools/packs \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "erp-inventory-pack",
    "name": "ERP Inventory Pack",
    "nameZh": "ERP 库存工具包",
    "description": "ERP 系统的库存查询和管理工具集合",
    "tools": ["erp_get_inventory", "erp_update_stock", "erp_stock_alert"],
    "knowledge": "## 仓库编号规则\n仓库ID格式: WH-XXX (三位数字)\n\n## 数据同步\n库存数据每5分钟从ERP系统同步一次\n\n## 注意事项\n- 库存更新操作需要审批\n- 负库存会触发报警"
  }'

python

claw.tools.create_pack(
    id="erp-inventory-pack",
    name="ERP Inventory Pack",
    nameZh="ERP 库存工具包",
    tools=["erp_get_inventory", "erp_update_stock"],
    knowledge="仓库ID格式: WH-XXX。库存数据每5分钟同步一次。"
)

javascript

await claw.tools.createPack({
  id: 'erp-inventory-pack',
  name: 'ERP Inventory Pack',
  nameZh: 'ERP 库存工具包',
  tools: ['erp_get_inventory', 'erp_update_stock'],
  knowledge: '仓库ID格式: WH-XXX。库存数据每5分钟同步一次。'
})

knowledge 字段中的文本会作为上下文提供给 AI，帮助 AI 理解工具的使用场景、数据格式和业务规则。

Python 装饰器注册

Python SDK 支持装饰器语法快速注册工具：

python

@claw.tool("my_calculator", description="计算两数之和")
def add(a: int, b: int):
    return {"sum": a + b}

装饰器会自动从函数签名推断 input_schema。

实战示例：IoT 设备工具集

以太古里运维平台为例，展示完整的工具集开发流程：

python

# 1. 注册设备查询工具
claw.tools.register(
    name="iot_get_devices",
    description="查询所有IoT设备的状态。返回设备列表，包含在线状态、最新数据、报警信息。",
    appId="taikoo-ops",
    input_schema={
        "type": "object",
        "properties": {
            "building": {"type": "string", "description": "楼栋（如：A栋、B栋）"},
            "status": {"type": "string", "enum": ["online", "offline", "alarm"]},
            "device_type": {"type": "string", "enum": ["冷水机", "空调", "电梯", "照明"]}
        }
    },
    execution={
        "type": "http",
        "method": "GET",
        "url": "https://iot.taikoo.com/api/devices?building={building}&status={status}&type={device_type}"
    }
)

# 2. 注册能耗查询工具
claw.tools.register(
    name="iot_get_energy",
    description="查询能耗数据。支持按日/周/月粒度查询，返回用电量和费用。",
    appId="taikoo-ops",
    input_schema={
        "type": "object",
        "properties": {
            "period": {"type": "string", "enum": ["day", "week", "month"]},
            "building": {"type": "string"}
        },
        "required": ["period"]
    },
    execution={
        "type": "http",
        "method": "GET",
        "url": "https://iot.taikoo.com/api/energy?period={period}&building={building}"
    }
)

# 3. 创建工具包
claw.tools.create_pack(
    id="taikoo-iot-pack",
    name="Taikoo IoT Pack",
    nameZh="太古里IoT工具包",
    tools=["iot_get_devices", "iot_get_energy"],
    knowledge="太古里有A栋和B栋两栋楼。冷水机位于B1层。能耗数据来自智能电表，每分钟采集一次。"
)

下一步

知识库指南 -- 为工具添加 RAG 知识增强
工作流指南 -- 将工具组合为自动化工作流
API 参考: 工具 -- 完整 API 端点文档

工具开发指南 ​

概述 ​

执行方式 ​

HTTP 工具 ​

Handler 工具 ​

注册工具 ​

编写好的工具描述 ​

输入参数 Schema ​

测试工具 ​

工具包 ​

创建工具包 ​

Python 装饰器注册 ​

实战示例：IoT 设备工具集 ​

下一步 ​

工具开发指南

概述

执行方式

HTTP 工具

Handler 工具

注册工具

编写好的工具描述

输入参数 Schema

测试工具

工具包

创建工具包

Python 装饰器注册

实战示例：IoT 设备工具集

下一步