Tools API

Nexevo 暴露了一个 REST Tools API，因此任何 agent 框架的 SDK——LangChain、Anthropic、LlamaIndex、Gemini 或自定义客户端——都能以该框架已有的线上格式，消费你工作区工具的一个安全子集。

概述

Tools API 是 MCP server 的 REST 互补方案。对于 MCP 原生客户端（Claude Desktop、Cursor）请使用 MCP；当你希望以框架自有的工具调用格式使用纯 REST JSON 时，请使用 Tools API。

端点

三个 REST 端点，全部使用工作区 API 密钥认证：

GET /v1/tools?format=openai——以所请求的线上格式列出所有可用工具的 schema。
GET /v1/tools/{name}?format=anthropic——单个工具的 schema。
POST /v1/tools/{name}/invoke——带参数执行某个工具。

认证

使用与 REST API 相同的工作区 API 密钥，放在 Authorization 头中。该密钥将调用绑定到某个工作区——客户端只能看到该工作区的工具和数据。

http

Authorization: Bearer sk-ws-...

暴露的能力

仅提供 agent 工具集中一个安全的、只读 / 纯计算的子集（与 MCP server 的作用域相同）：

网络检索——搜索、读取页面、抓取、读取 PDF/文档、对图片做 OCR。
开放数据——arXiv、SEC EDGAR、World Bank、OECD、市场数据、RSS。
你的工作区知识——在其长期记忆和已上传知识之上的 rag_search。
计算——计算器、单位换算及其他纯函数助手。

生成、邮件、浏览器、连接器、SQL 以及破坏性操作不会被暴露——外部客户端可以读取和推理，但无法消耗或修改。

线上格式

format 查询参数决定工具 schema 的序列化方式。选择你的框架 SDK 所期望的那个：

format	Schema 字段	配合使用
`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
]