Tools API

Nexevo 提供 REST Tools API，讓任何 agent 框架的 SDK——LangChain、Anthropic、LlamaIndex、Gemini 或自訂用戶端——都能以該框架既有的傳輸格式，消費你 workspace 工具的安全子集。

概觀

Tools API 是 MCP server 的 REST 互補。MCP 原生用戶端（Claude Desktop、Cursor）請用 MCP；若你想要的是以框架本身工具呼叫格式的純 REST JSON，則請用 Tools API。

端點

三個 REST 端點，全部以 workspace API key 驗證：

GET /v1/tools?format=openai——以指定的傳輸格式列出所有可用的工具結構描述。
GET /v1/tools/{name}?format=anthropic——單一工具的結構描述。
POST /v1/tools/{name}/invoke——以引數執行某個工具。

驗證

使用與 REST API 相同的工作區 API key，放在 Authorization 標頭中。該 key 會將呼叫綁定至單一 workspace——用戶端只會看到該 workspace 的工具與資料。

http

Authorization: Bearer sk-ws-...

公開的內容

只提供 agent 工具集中安全、唯讀／僅計算的子集（與 MCP server 的範圍相同）：

網頁研究——搜尋、讀取頁面、爬取、讀取 PDF／文件、對圖片 OCR。
開放資料——arXiv、SEC EDGAR、World Bank、OECD、市場資料、RSS。
你的 workspace 知識——對其長期記憶與上傳知識進行 rag_search。
計算——計算機、單位換算與其他純粹的輔助工具。

生成、電子郵件、瀏覽器、connectors、SQL 與破壞性操作不會公開——外部用戶端可以讀取與推理，但無法消耗或變更。

傳輸格式

format 查詢參數決定工具結構描述的序列化方式。挑選你的框架 SDK 期望的格式：

format	結構描述欄位	適用於
`openai`（預設）	`parameters`	OpenAI Chat Completions、LangChain
`openai_responses`	`parameters`（扁平）	OpenAI Responses API
`anthropic`	`input_schema`	Anthropic Messages API
`mcp`	`inputSchema`	MCP 相容用戶端
`gemini`	`parameters`	Google Gemini FunctionDeclarations

列出工具

bash

curl https://nexevo.ai/v1/tools?format=anthropic \
  -H "Authorization: Bearer sk-ws-..."

json

{
  "tools": [
    {
      "name": "web_search",
      "description": "Search the public web ...",
      "input_schema": {
        "type": "object",
        "properties": { "query": { "type": "string" } },
        "required": ["query"]
      }
    }
  ],
  "format": "anthropic"
}

呼叫工具

bash

curl -X POST https://nexevo.ai/v1/tools/web_search/invoke \
  -H "Authorization: Bearer sk-ws-..." \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"query": "latest LLM benchmarks"}}'

json

{
  "content": "{\"count\": 5, \"results\": [...]}",
  "ok": true,
  "error_kind": "",
  "artifacts": []
}

工具錯誤會回傳 ok: false 並帶有 error_kind（timeout／exception）與人類可讀的 content——絕不會回傳 HTTP 錯誤，因此呼叫端 agent 可以自行反應。

框架整合

典型的整合模式：取得一次工具清單，把它傳給你框架的工具呼叫 API，然後將模型發出的每次工具呼叫路由到 POST /v1/tools/{name}/invoke。

Anthropic SDK

python

import anthropic, httpx

client = anthropic.Anthropic()
BASE = "https://nexevo.ai/v1"
HEADERS = {"Authorization": "Bearer sk-ws-..."}

# 1. fetch tools in Anthropic format
tools = httpx.get(f"{BASE}/tools", params={"format": "anthropic"}, headers=HEADERS).json()["tools"]

# 2. let Claude pick a tool, then execute it via Nexevo
msg = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "What's in my knowledge base about Q3?"}],
)
for block in msg.content:
    if block.type == "tool_use":
        r = httpx.post(f"{BASE}/tools/{block.name}/invoke",
                       headers=HEADERS, json={"arguments": block.input})
        print(r.json()["content"])

OpenAI／LangChain

python

import httpx
from langchain_core.tools import StructuredTool

BASE = "https://nexevo.ai/v1"
HEADERS = {"Authorization": "Bearer sk-ws-..."}

# fetch in OpenAI format, wrap each as a LangChain tool
raw = httpx.get(f"{BASE}/tools", params={"format": "openai"}, headers=HEADERS).json()["tools"]

def make_executor(name):
    def _run(**kwargs):
        r = httpx.post(f"{BASE}/tools/{name}/invoke", headers=HEADERS, json={"arguments": kwargs})
        return r.json()["content"]
    return _run

tools = [
    StructuredTool.from_function(
        func=make_executor(t["function"]["name"]),
        name=t["function"]["name"],
        description=t["function"]["description"],
        # args_schema can be derived from t["function"]["parameters"]
    )
    for t in raw
]