自定义 HTTP 与代码工具

Clouisle 的工具分三类：内置工具（平台注册，无需创建，详见 内置工具）、MCP 服务（连接外部 MCP Server，详见 MCP 服务）和自定义工具（团队创建）。自定义工具属于当前团队，支持 HTTP API、代码和数据库三种类型，可配置参数、测试执行并共享给其他团队。

工具类型

在能力 > 工具的创建工具菜单里可以选择四种入口（MCP 服务单独成页）：

命名规则

创建工具名称只能包含字母、数字和下划线，且必须以字母开头，例如 lookup_order。名称在团队内唯一。

创建 HTTP API 工具

1. 在能力 > 工具中选择创建工具 > HTTP API。
2. 设置工具名称、显示名称、描述和分类。
3. 配置 HTTP 方法（默认 GET）、URL、请求头、查询参数、JSON 请求体和响应路径。
4. 在 URL、请求头、查询参数和正文中使用 {参数名} 占位符。
5. 超时默认 30 秒，范围 1-300 秒。
6. 保存后选择运行测试，确认结果路径和错误行为。

HTTP 工具配置示例：查询客户信息

Name: CRM Lookup
Description: 在 CRM 系统中查询客户信息
Category: Data
Type: Custom

Endpoint Configuration:
  URL: https://api.crm.example.com/customers
  Method: GET
  Authentication: API Key
  API Key Header: X-API-Key
  API Key: crm_...
  Query Parameters:
    customer_id: "{customer_id}"
  Timeout: 30 seconds

Input Parameters:
  - name: customer_id
    type: string
    required: true
    description: 要查询的客户 ID

Response Format:
  type: json
  schema:
    customer_id: string
    name: string
    email: string
    phone: string
    status: string

HTTP 工具配置示例：创建工单（POST）

Name: Create Support Ticket
Description: 在工单系统中创建支持工单
Category: Communication
Type: Custom

Endpoint Configuration:
  URL: https://api.tickets.example.com/tickets
  Method: POST
  Authentication: Bearer Token
  Token: Bearer tk_...
  Content-Type: application/json
  Timeout: 30 seconds

Input Parameters:
  - name: title
    type: string
    required: true
    description: 工单标题

  - name: description
    type: string
    required: true
    description: 工单描述

  - name: priority
    type: enum
    required: false
    default: medium
    options: [low, medium, high, urgent]
    description: 工单优先级

  - name: assignee
    type: string
    required: false
    description: 处理人邮箱

Response Format:
  type: json
  schema:
    ticket_id: string
    status: string
    created_at: string

创建代码工具

代码工具支持 Python 与 JavaScript，在受限沙箱中执行。Python 包必须使用精确 package==version；JavaScript 包必须使用 package@version。可配置命令 argv、包源地址、产物和资源限制。

默认资源限制：

产物路径必须位于 /workspace，可标记为可选。

创建数据库工具

数据库工具让 Agent 直接查询外部数据库。连接信息（主机、端口、账号、密码、连接 URL）对模型保密——Agent 只看到工具名称和描述，因此描述要写清这个库存了什么、适合回答哪类问题。

1. 在能力 > 工具中选择创建工具 > 数据库工具。
2. 选择数据库类型：PostgreSQL、MySQL、Redis 或 MongoDB。
3. 填写连接信息，二选一：
   • 字段模式：主机、端口、数据库名、用户名、密码、SSL。
   • 连接 URL 模式：直接填连接地址（Redis / MongoDB 常用）；Redis 可再指定逻辑库序号，MongoDB 可指定认证库。
4. 设置查询超时（默认 15 秒，范围 1-120 秒）和最大返回行数（默认 100，范围 1-1000）。
5. 点击测试连通性验证配置（同样经过站点安全校验），成功后保存。

Agent 能做什么

返回条数始终受最大返回行数约束，Agent 自己要求的条数只能更小；查询默认返回 50 行，MongoDB 查询与聚合默认返回 20 行。

编辑与删除工具

编辑自定义工具

1. 选择自定义工具
2. 选择编辑
3. 修改工具详情、端点配置、参数或响应格式
4. 测试工具
5. 保存更改

删除自定义工具

1. 选择自定义工具
2. 选择删除
3. 检查影响：正在使用该工具的 Agent 和工作流
4. 确认删除

测试工具

运行测试

1. 选择工具
2. 选择测试按钮
3. 输入测试参数
4. 选择运行测试

测试结果示例

网页搜索测试：选择引擎（站点默认或某个已启用引擎），填写查询词与结果条数。

Tool: Web Search
Test Parameters:
  query: "artificial intelligence"
  num_results: 5
  engine: site default

Status: Success
Response:
  results:
    - title: "Artificial Intelligence - Wikipedia"
      url: "https://en.wikipedia.org/wiki/Artificial_intelligence"
      content: "Artificial intelligence (AI) is intelligence..."

    - title: "What is AI? | IBM"
      url: "https://www.ibm.com/topics/artificial-intelligence"
      content: "Artificial intelligence leverages computers..."

Tool: CRM Lookup
Test Parameters:
  customer_id: "12345"

Status: Success
Response Time: 0.5 seconds
Response:
  {
    "customer_id": "12345",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1-555-0123",
    "status": "active"
  }

Validation: Passed
  ✓ Response format matches schema
  ✓ All required fields present
  ✓ Data types correct

凭据与共享

凭据由服务端保存，调用时注入。自定义工具可以共享给其他团队，权限为只读或读取并执行。

工具列表会显示共享状态与已共享的团队数量。

工具状态管理

工具有启用/禁用两种状态：

失败处理

HTTP 工具测试失败

检查以下方面：

• URL 是否正确
• TLS 证书是否有效
• 认证凭据是否过期
• 请求体 JSON 格式是否正确
• 响应路径是否匹配实际响应结构

代码工具测试失败

检查以下方面：

• 包是否使用固定版本（package==version）
• 标准输出是否超过 256KB 上限
• 磁盘使用是否超过 1024MB 上限
• 执行是否超时（默认 30 秒）
• 产物路径是否位于 /workspace

最佳实践

工具配置

✅ 推荐做法：

• 启用前先测试工具
• 定期轮换凭据
• 记录工具用途
• 保持工具更新
• 使用错误处理

❌ 避免做法：

• 启用未经测试的工具
• 长期使用静态凭据
• 跳过文档记录
• 忽略错误

安全

✅ 推荐做法：

• 使用安全认证方式
• 定期轮换 API 密钥
• 限制工具访问范围
• 启用审计日志
• 监控异常使用
• 仅使用 HTTPS
• 验证响应数据

❌ 避免做法：

• 使用弱认证方式
• 长期使用静态 API 密钥
• 允许无限制访问
• 禁用审计日志
• 忽略可疑活动
• 允许 HTTP 连接
• 盲目信任响应

性能

✅ 推荐做法：

• 设置合理的超时时间
• 尽可能使用缓存
• 监控响应时间
• 优化工具调用
• 优雅处理错误

❌ 避免做法：

• 使用过长超时
• 跳过缓存
• 忽略性能指标
• 进行不必要的调用
• 忽略错误

工具命名规范与思考状态展示

Agent 在对话过程中调用工具时，顶部的思考折叠栏无需展开即可自动识别并展示当前工具的操作意图。为了让前台展示最自然、直观，建议遵循以下工具命名规范：

1. 命名规范与推荐动词前缀

2. 展示名称建议

• 优先设置中文展示名称：创建工具时，若填写了友好的展示名称（如 查询股票行情、发送飞书通知），前端外层状态栏将直接优先展示该名称（如 正在查询：查询股票行情...）。
• 英文标识符自动美化：若工具仅有标识符（如 fetch_user_orders 或 syncCrmAccount），系统会自动转换为自然单词组并应用到状态中（如 正在查询：Fetch User Orders...）。
• 并发调用智能聚合：当 Agent 在一轮思考中同时并发执行多个工具时，外层折叠栏会自动聚合为 正在并行调用 {N} 个工具...，保持界面整洁。

故障排除

工具调用失败

1. 检查工具配置： 验证凭据、端点 URL，测试连通性
2. 检查审计日志： 查看工具所属团队的审计日志条目
3. 常见错误：
   • 认证失败： 凭据无效
   • 超时： 增加超时时间或检查端点
   • 参数无效： 检查参数格式
4. 测试工具： 使用测试面板查看结果

响应缓慢

1. 使用工具测试面板测量响应时间
2. 优化：增加超时、减少数据传输、优化端点
3. 检查外部服务状态，确认无中断

相关内容

• 内置工具 — 启用时间、计算、网页、文件和媒体等系统能力
• MCP 服务 — 通过 stdio、SSE 或 HTTP 连接 MCP Server
• Skills 与包 — 导入可复用 Skill 包并管理资源
• 工具 API — 完整的端点、字段与权限参考