智能体工具（REST）

任何支持函数调用的智能体都可以使用 Warmbly 的 AI 工具注册表，无需 MCP 客户端。列出当前凭据可使用的工具，导出 OpenAI 和 Hermes 格式的工具清单，并直接通过 HTTP 执行工具。

并非所有智能体都支持 MCP。Hermes 类模型、兼容 OpenAI 的框架、LangChain 智能体和普通脚本都可以通过常规 HTTP 进行函数调用，因此 Warmbly 通过两个 REST 端点提供与 MCP 服务器相同的工具注册表：一个按智能体框架所需的清单格式列出当前凭据可使用的工具，另一个用于执行工具。

规则与 MCP 完全相同：每个工具都受各自的权限位约束，列表仅显示调用者有权使用的工具，并且永远不会提供发送类工具，也就是任何会实际发送邮件的工具。通过此接口接入的智能体可以读取、搜索、添加标签和起草内容，但发送操作始终由人来确认。

列表: GET https://api.warmbly.com/v1/ai/tools
执行: POST https://api.warmbly.com/v1/ai/tools/{name}/call
身份验证：在 Bearer 请求头中携带 API 密钥或 OAuth 访问令牌，也可使用控制台 JWT。使用 JWT 的成员必须拥有 使用 AI 权限，否则两个端点都会返回 403。每个工具都会检查权限表中对应的权限范围；对 JWT 成员则检查相应的组织权限。

列出工具

GET /ai/tools 返回按调用者凭据权限筛选后的工具目录。支持三种格式：

`format`	结构
`warmbly`（默认）	每个工具对应一个 `{ name, description, input_schema }`
`openai`	OpenAI 函数调用对象：`{ type: "function", function: { name, description, parameters } }`
`hermes`, `functions`	`openai` 的别名；同一套 JSON Schema 可原样放入 Hermes 的 `<tools>` 块

curl -s "https://api.warmbly.com/v1/ai/tools?format=openai" \
  -H "Authorization: Bearer wmbly_..."

{
  "data": [
    {
      "type": "function",
      "function": {
        "name": "list_threads",
        "description": "List unified-inbox conversation threads...",
        "parameters": {
          "type": "object",
          "properties": {
            "subject": { "type": "string" },
            "folder": { "type": "string" },
            "unseen_only": { "type": "boolean" },
            "limit": { "type": "integer" }
          }
        }
      }
    }
  ]
}

由于列表已经按权限筛选，你可以将响应直接交给智能体：其中所有工具都能使用同一凭据调用，而且没有任何工具能够发送邮件。

执行工具

POST /ai/tools/{name}/call 执行一个工具。请求体是该工具的 JSON 参数对象，应与模型在工具调用中生成的对象完全一致；请求体为空表示没有参数。

curl -s -X POST "https://api.warmbly.com/v1/ai/tools/list_threads/call" \
  -H "Authorization: Bearer wmbly_..." \
  -H "Content-Type: application/json" \
  -d '{"folder": "inbox", "unseen_only": true, "limit": 10}'

{
  "data": {
    "name": "list_threads",
    "result": { "threads": [], "count": 0 }
  }
}

result 是以 JSON 形式嵌入的工具输出。将其作为工具调用结果返回给模型，然后继续这一循环。

错误采用标准响应封装，并提供稳定的 code：未知工具返回 404 not_found；凭据缺少工具所需权限范围时返回 403 forbidden；参数请求体格式错误时返回 400 bad_request；工具自身的失败，例如验证错误或记录不存在，返回 422 unprocessable，并附带供模型读取和据此处理的工具错误消息。服务端自身发生故障时返回 500 internal_error，包含请求 ID，但不提供内部详情。

这是会产生实际变更的 POST 请求，因此与 API 的其他部分一样支持 Idempotency-Key，同时适用各密钥的速率限制和用量日志记录。

接入 Hermes 智能体

Hermes 格式模型，以及任何通过兼容 OpenAI 的工具调用 API 提供服务的模型，会从系统提示词或 tools 数组中读取函数定义，然后生成由你执行并返回结果的工具调用。与 Warmbly 交互的循环如下：

会话开始时调用一次 GET /ai/tools?format=hermes，将 data 数组作为可用工具提供给模型。
模型生成 { "name": ..., "arguments": ... } 形式的工具调用后，以参数对象为请求体调用 POST /ai/tools/{name}/call。
将 data.result 作为工具响应返回给模型，然后重复执行。

import json, requests

BASE = "https://api.warmbly.com/v1"
HEADERS = {"Authorization": "Bearer wmbly_..."}

tools = requests.get(f"{BASE}/ai/tools?format=hermes", headers=HEADERS).json()["data"]
# system prompt: "You may call these tools:\n<tools>" + json.dumps(tools) + "</tools>"

def run_tool(call):
    r = requests.post(
        f"{BASE}/ai/tools/{call['name']}/call",
        headers=HEADERS,
        json=call.get("arguments") or {},
    )
    body = r.json()
    return body["data"]["result"] if r.ok else body  # errors are model-readable too

这两个调用同样适用于任何框架的“自定义工具”扩展入口：将执行器指向 /ai/tools/{name}/call，将工具发现步骤指向 /ai/tools。

选择调用方式

使用场景	使用方式
Claude Code、Claude Desktop、Cursor 或任意 MCP 客户端	位于 `/v1/mcp` 的 MCP 服务器
Hermes / OpenAI 风格的函数调用智能体	本页介绍的 REST 接口
控制台	内置助手，以当前登录成员的身份使用同一工具注册表
终端	`warmblyctl tool list` 和 `warmblyctl tool call`

这四种方式使用完全相同的工具注册表和权限检查，因此无论通过哪个入口调用，同一工具的行为都一致。

另请参阅

MCP 服务器：此工具接口的 MCP 协议原生版本
权限：各工具检查的权限范围
实时 API：向长期运行的智能体推送事件流，无需轮询