Tools API

A Nexevo expõe uma Tools API REST para que o SDK de qualquer framework de agent — LangChain, Anthropic, LlamaIndex, Gemini, ou um cliente personalizado — possa consumir um subconjunto seguro das ferramentas do seu workspace, no formato de transmissão que o framework já fala.

Visão geral

A Tools API é o complemento REST do servidor MCP. Use MCP para clientes nativos-MCP (Claude Desktop, Cursor); use a Tools API quando você quer REST JSON puro no formato de chamada de ferramentas do próprio framework.

Endpoints

Três endpoints REST, todos autenticados com uma chave de API do workspace:

GET /v1/tools?format=openai — lista todos os esquemas de ferramenta disponíveis no formato de transmissão solicitado.
GET /v1/tools/{name}?format=anthropic — o esquema de uma ferramenta.
POST /v1/tools/{name}/invoke — executa uma ferramenta com argumentos.

Autenticação

Use a mesma chave de API do workspace que a API REST, no cabeçalho Authorization. A chave vincula a chamada a um workspace — um cliente só vê as ferramentas e dados daquele workspace.

http

Authorization: Bearer sk-ws-...

O que é exposto

Apenas um subconjunto seguro, somente leitura / computação do conjunto de ferramentas do agent está disponível (idêntico ao escopo do servidor MCP):

Pesquisa web — buscar, ler uma página, fazer scrape, ler um PDF/doc, OCR de uma imagem.
Dados abertos — arXiv, SEC EDGAR, World Bank, OECD, dados de mercado, RSS.
Conhecimento do seu workspace — rag_search sobre sua memória de longo prazo e conhecimento enviado.
Computação — uma calculadora, conversão de unidades e outros auxiliares puros.

Geração, e-mail, navegador, conectores, SQL e ações destrutivas não são expostos — um cliente externo pode ler e raciocinar, mas não pode gastar nem mutar.

Formatos de transmissão

O parâmetro de query format seleciona como os esquemas de ferramenta são serializados. Escolha aquele que o SDK do seu framework espera:

format	Campo de schema	Usar com
`openai` (padrão)	`parameters`	OpenAI Chat Completions, LangChain
`openai_responses`	`parameters` (flat)	OpenAI Responses API
`anthropic`	`input_schema`	Anthropic Messages API
`mcp`	`inputSchema`	Clientes compatíveis com MCP
`gemini`	`parameters`	Google Gemini FunctionDeclarations

Listando ferramentas

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"
}

Invocando uma ferramenta

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": []
}

Erros de ferramenta retornam ok: false com um error_kind (timeout / exception) e um content legível por humanos — nunca um erro HTTP, então o agent chamador pode reagir.

Integração com framework

O padrão típico de integração: busque a lista de ferramentas uma vez, passe-a para a API de chamada de ferramentas do seu framework, então roteie cada chamada de ferramenta que o modelo emite para POST /v1/tools/{name}/invoke.

SDK Anthropic

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
]