跳转到主内容

工具配置 API

Creatoria Agent API 文档

#工具配置 API

管理 Agent 可用的工具配置，包括搜索工具、代码工具等的提供商配置和用量监控。

基础路径: /v1/tools/configurations

#工具配置管理

#列出工具配置

GET /v1/tools/configurations

#查询参数

参数类型说明
pagenumber页码，默认 1
limitnumber每页条数，默认 20，最大 100
enabledboolean按启用状态筛选
toolNamestring按工具名称筛选

#响应

json{
  "data": [
    {
      "id": "config_xxx",
      "organizationId": "org_xxx",
      "toolName": "web-search",
      "enabled": true,
      "provider": "exa",
      "usageLimits": {
        "maxCallsPerDay": 1000,
        "maxCallsPerMonth": 30000
      },
      "usageStats": {
        "callsToday": 45,
        "callsThisMonth": 1200,
        "remainingToday": 955,
        "remainingThisMonth": 28800
      },
      "createdAt": "2026-01-05T08:00:00Z",
      "updatedAt": "2026-02-10T12:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

#获取工具配置详情

GET /v1/tools/configurations/:configId

#响应

json{
  "id": "config_xxx",
  "organizationId": "org_xxx",
  "toolName": "web-search",
  "enabled": true,
  "config": {
    "provider": "exa",
    "apiKey": "***",
    "usageLimits": {
      "maxCallsPerDay": 1000,
      "maxCallsPerMonth": 30000
    }
  },
  "usageLimits": {
    "maxCallsPerDay": 1000,
    "maxCallsPerMonth": 30000
  },
  "metadata": {},
  "createdAt": "2026-01-05T08:00:00Z",
  "updatedAt": "2026-02-10T12:00:00Z"
}
注意：响应中的 apiKey 字段会被脱敏显示为 ***。

#创建工具配置

POST /v1/tools/configurations

所需权限: tools:create（admin 或 user 角色）

#请求体

json{
  "toolName": "web-search",
  "config": {
    "provider": "exa",
    "apiKey": "your-provider-api-key",
    "usageLimits": {
      "maxCallsPerDay": 500,
      "maxCallsPerMonth": 15000
    }
  },
  "enabled": true
}
字段类型必填说明
toolNamestring是工具名称
configobject否工具配置
config.providerstring否提供商，默认 builtin
config.apiKeystring否提供商 API Key
enabledboolean否是否启用，默认 true

#响应

HTTP 201 Created
json{
  "id": "config_xxx",
  "organizationId": "org_xxx",
  "toolName": "web-search",
  "enabled": true,
  "createdAt": "2026-02-20T08:00:00Z"
}

#更新工具配置

PATCH /v1/tools/configurations/:configId

所需权限: tools:update（admin 或 user 角色）

#请求体

json{
  "enabled": false,
  "config": {
    "apiKey": "new-api-key"
  }
}

#删除工具配置

DELETE /v1/tools/configurations/:configId

所需权限: tools:delete（仅 admin 角色）

#响应

json{
  "id": "config_xxx",
  "deleted": true
}

#用量统计

#获取当前用量

GET /v1/tools/configurations/:configId/usage

#响应

json{
  "toolConfigId": "config_xxx",
  "toolName": "web-search",
  "provider": "exa",
  "usage": {
    "today": {
      "calls": 45,
      "limit": 1000,
      "remaining": 955,
      "percentage": 4.5,
      "successRate": 98.5
    },
    "thisMonth": {
      "calls": 1200,
      "limit": 30000,
      "remaining": 28800,
      "percentage": 4.0,
      "successRate": 97.8
    }
  },
  "lastResetAt": "2026-02-20T00:00:00Z",
  "nextResetAt": "2026-02-21T00:00:00Z"
}

#获取用量历史

GET /v1/tools/configurations/:configId/usage/history

#查询参数

参数类型说明
startDatestring起始日期（ISO 格式），默认 30 天前
endDatestring结束日期（ISO 格式），默认当前时间

#响应

json{
  "toolConfigId": "config_xxx",
  "toolName": "web-search",
  "period": {
    "start": "2026-01-21T00:00:00Z",
    "end": "2026-02-20T00:00:00Z"
  },
  "history": [
    {
      "date": "2026-02-19",
      "calls": 120,
      "successRate": 99.2,
      "errorCount": 1,
      "avgDuration": 450
    }
  ],
  "summary": {
    "totalCalls": 3500,
    "avgSuccessRate": 98.5,
    "avgDuration": 0,
    "totalErrors": 52
  }
}

#测试与验证

#测试工具配置

POST /v1/tools/configurations/:configId/test

所需权限: tools:update

测试工具配置是否有效。

#响应

json{
  "success": true,
  "results": [
    {
      "title": "Configuration test",
      "url": "",
      "content": "Tool \"web-search\" (exa) configuration is valid."
    }
  ],
  "duration": 150,
  "provider": "exa"
}

#验证 API Key

POST /v1/tools/configurations/validate

所需权限: tools:create

验证提供商 API Key 的有效性。

#请求体

json{
  "provider": "exa",
  "apiKey": "your-api-key"
}

#响应

json{
  "valid": true,
  "provider": "exa",
  "quotaInfo": {
    "plan": "unknown",
    "remaining": 0,
    "limit": 0
  }
}

#自定义工具 API

创建和管理自定义工具，支持 HTTP Webhook 和 JavaScript 沙箱两种类型。自定义工具可绑定到 Agent，在对话过程中被 LLM 自动调用。

基础路径: /v1/custom-tools

#工具类型

类型说明
http调用外部 HTTP 端点（Webhook 模式），支持同步和异步执行
code在 Node.js 沙箱中执行 JavaScript 代码片段

#创建自定义工具

POST /v1/custom-tools

#HTTP 类型工具请求体

json{
  "name": "get-weather",
  "description": "获取指定城市的天气信息",
  "toolType": "http",
  "inputSchema": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称"
      }
    },
    "required": ["city"]
  },
  "endpoint": {
    "url": "https://api.example.com/weather",
    "timeoutMs": 5000,
    "auth": {
      "type": "bearer",
      "token": "your-api-token"
    }
  },
  "executionMode": "sync"
}

#Code 类型工具请求体

json{
  "name": "calculate-price",
  "description": "根据数量和折扣计算价格",
  "toolType": "code",
  "inputSchema": {
    "type": "object",
    "properties": {
      "quantity": {
        "type": "number",
        "description": "数量"
      },
      "discount": {
        "type": "number",
        "description": "折扣比例（0-1）"
      }
    },
    "required": ["quantity"]
  },
  "codeSnippet": "const price = 99.9;\nconst total = price * args.quantity * (1 - (args.discount || 0));\nreturn { total: total.toFixed(2), currency: 'CNY' };",
  "timeoutMs": 5000
}

#字段说明

字段类型必填说明
namestring是工具名称（组织内唯一）
descriptionstring是工具描述（LLM 用于理解工具用途）
toolTypestring是http 或 code
inputSchemaobject是JSON Schema 格式的参数定义
endpointobjecthttp 必填HTTP 端点配置
endpoint.urlstring是请求 URL
endpoint.timeoutMsnumber否超时时间（毫秒），默认 5000
endpoint.authobject否认证配置
codeSnippetstringcode 必填JavaScript 代码片段
timeoutMsnumber否执行超时（毫秒），默认 5000，最大 30000
executionModestring否sync（默认）或 async

#认证类型

类型字段说明
none-无认证
api_keyheader, value自定义请求头认证
bearertokenBearer Token 认证
basicusername, passwordHTTP Basic 认证

#响应

HTTP 201 Created

#列出自定义工具

GET /v1/custom-tools

返回当前组织的所有自定义工具。

#获取自定义工具详情

GET /v1/custom-tools/:toolId

#更新自定义工具

PATCH /v1/custom-tools/:toolId

支持部分更新，字段同创建接口。

#删除自定义工具

DELETE /v1/custom-tools/:toolId

#响应

json{
  "success": true
}

#测试自定义工具

POST /v1/custom-tools/:toolId/test

使用给定参数测试工具执行。

#请求体

json{
  "arguments": {
    "city": "上海"
  }
}

#响应

json{
  "success": true,
  "content": "{\"temperature\": 22, \"condition\": \"晴\"}",
  "duration": 350
}

#将自定义工具绑定到 Agent

通过 Agent 更新接口，将自定义工具绑定到指定 Agent：

PATCH /v1/agents/:agentId
json{
  "settings": {
    "toolsEnabled": true,
    "customToolIds": ["tool-uuid-1", "tool-uuid-2"]
  }
}

绑定后，Agent 在对话中会自动识别并调用关联的自定义工具。

下一篇: Webhooks API →