Tools API

تكشف Nexevo عن REST Tools API بحيث يمكن لأي SDK لإطار عمل agent — LangChain، Anthropic، LlamaIndex، Gemini، أو عميل مخصّص — استهلاك مجموعة فرعية آمنة من أدوات مساحة عملك، بتنسيق السلك الذي يتحدثه ذلك الإطار بالفعل.

نظرة عامة

Tools API هو المكمل الـ REST لـ خادم MCP. استخدم MCP لعملاء MCP الأصليين (Claude Desktop، Cursor)؛ واستخدم Tools API عندما تريد REST JSON عاديًا بتنسيق استدعاء أدوات خاص بالإطار.

المُنفّذات

ثلاثة مُنفّذات REST، جميعها مُصادَق عليها بمفتاح API لمساحة عمل:

GET /v1/tools?format=openai — سرد جميع مخططات الأدوات المتاحة بتنسيق السلك المطلوب.
GET /v1/tools/{name}?format=anthropic — مخطط أداة واحدة.
POST /v1/tools/{name}/invoke — تنفيذ أداة بوسائط.

المصادقة

استخدم نفس مفتاح API لمساحة العمل كـ REST API، في ترويسة Authorization. يربط المفتاح الاستدعاء بمساحة عمل واحدة — يرى العميل فقط أدوات وبيانات تلك المساحة.

http

Authorization: Bearer sk-ws-...

ما الذي يُكشف

فقط مجموعة فرعية آمنة، للقراءة / الحساب فقط من مجموعة أدوات الـ agent متاحة (مطابقة لنطاق خادم MCP):

بحث الويب — بحث، قراءة صفحة، كشط، قراءة PDF/doc، OCR لصورة.
البيانات المفتوحة — arXiv، SEC EDGAR، World Bank، OECD، بيانات السوق، RSS.
معرفة مساحة عملك — rag_search فوق ذاكرتها طويلة الأمد ومعرفتها المرفوعة.
الحوسبة — حاسبة، تحويل وحدات، ومساعدات نقية أخرى.

التوليد، البريد، المتصفح، الموصلات، 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 المستدعي التفاعل.

تكامل الإطار

نمط التكامل النموذجي: اجلب قائمة الأدوات مرة واحدة، مرّرها إلى واجهة استدعاء الأدوات الخاصة بإطارك، ثم وجّه كل استدعاء أداة يُصدره النموذج إلى 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
]