Tools API

Nexevo expone una Tools API REST para que el SDK de cualquier framework de agents (LangChain, Anthropic, LlamaIndex, Gemini o un cliente propio) consuma un subconjunto seguro de las herramientas de tu workspace, en el formato de cable que ese framework ya maneja.

Visión general

La Tools API es el complemento REST del servidor MCP. Usa MCP para clientes nativos de MCP (Claude Desktop, Cursor); usa la Tools API cuando quieras REST JSON puro en el formato de llamada a herramientas del propio framework.

Endpoints

Tres endpoints REST, todos autenticados con una API key del workspace:

GET /v1/tools?format=openai — lista todos los esquemas de herramientas disponibles en el formato de cable solicitado.
GET /v1/tools/{name}?format=anthropic — el esquema de una herramienta.
POST /v1/tools/{name}/invoke — ejecuta una herramienta con argumentos.

Autenticación

Usa la misma API key del workspace que la API REST, en la cabecera Authorization. La clave vincula la llamada a un workspace: un cliente solo ve las herramientas y los datos de ese workspace.

http

Authorization: Bearer sk-ws-...

Qué se expone

Solo está disponible un subconjunto seguro, de solo lectura / solo cómputo del set de herramientas del agent (idéntico al alcance del servidor MCP):

Investigación web — buscar, leer una página, scrapear, leer un PDF/doc, OCR de una imagen.
Datos abiertos — arXiv, SEC EDGAR, World Bank, OECD, datos de mercado, RSS.
El conocimiento de tu workspace — rag_search sobre su memoria a largo plazo y el conocimiento subido.
Cómputo — una calculadora, conversión de unidades y otras utilidades puras.

La generación, el email, el navegador, los connectors, el SQL y las acciones destructivas no se exponen: un cliente externo puede leer y razonar, pero no gastar ni mutar.

Formatos de cable

El parámetro de consulta format selecciona cómo se serializan los esquemas de herramientas. Elige el que espera el SDK de tu framework:

format	Campo del esquema	Usar con
`openai` (por defecto)	`parameters`	OpenAI Chat Completions, LangChain
`openai_responses`	`parameters` (plano)	OpenAI Responses API
`anthropic`	`input_schema`	Anthropic Messages API
`mcp`	`inputSchema`	Clientes compatibles con MCP
`gemini`	`parameters`	Google Gemini FunctionDeclarations

Listar herramientas

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

Invocar una herramienta

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

Los errores de herramienta devuelven ok: false con un error_kind (timeout / exception) y un content legible por humanos, nunca un error HTTP, de modo que el agent que llama pueda reaccionar.

Integración con frameworks

El patrón típico de integración: obtén la lista de herramientas una vez, pásala a la API de llamada a herramientas de tu framework y luego enruta cada llamada a herramienta que emite el modelo a POST /v1/tools/{name}/invoke.

SDK de 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
]