Salt la conținutul principal
Română— Alege o limbă
Meniu

Instrumente externe și SDK-uri acceptate

Lecția 3 din 12 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Trei puncte de intrare către același mecanism
  2. SDK-ul nativ xAI
  3. API-ul Responses, compatibil OpenAI
  4. API-ul Voice Agent
  5. Ce nu se schimbă între interfețe
  6. Puncte cheie

Trei puncte de intrare către același mecanism

xAI expune MCP la distanță prin trei interfețe. Acestea se adresează unor dezvoltatori diferiți: una pentru proiecte noi, alta pentru proiecte migrate și a treia pentru contexte de utilizare specifice. Comportamentul MCP este exact același în toate cele trei cazuri; doar sintaxa de configurare și instrumentele periferice se schimbă. Alegerea dumneavoastră depinde, așadar, de stiva tehnologică existentă, nu de capacitățile protocolului.

SDK-ul nativ xAI

Aceasta este metoda recomandată de xAI. Oferă un helper mcp() care condensează configurarea într-un singur apel de funcție.

from xai_sdk import Client
from xai_sdk.tools import mcp

client = Client(api_key=os.getenv("XAI_API_KEY"))

chat = client.chat.create(
    model="grok-4.20-0309-reasoning",
    tools=[
        mcp(server_url="https://mcp.deepwiki.com/mcp")
    ],
    include=["verbose_streaming"],
)

Helper-ul mcp() acceptă toți parametrii de configurare MCP—URL, etichetă, descriere, instrumente permise, autentificare—și se ocupă de formatarea lor corectă pentru API. Aceasta este sintaxa cea mai concisă și, crucial, cea în care riscați cel mai puțin să faceți o greșeală, deoarece numele cheilor și imbricarea sunt gestionate automat. Alegeți această cale pentru un proiect nou fără constrângeri de compatibilitate, pentru orice prototipare rapidă și ori de câte ori utilizați funcții specifice xAI, cum ar fi streaming-ul detaliat vizibil mai sus.

API-ul Responses, compatibil OpenAI

Această interfață acceptă exact formatul API OpenAI. Există dintr-un motiv specific: pentru ca o echipă care și-a scris deja aplicația în acest format să nu fie nevoită să rescrie totul pentru a testa Grok. Modificarea se limitează la cheia API și la URL-ul de bază.

from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input=[{"role": "user", "content": "Explain the React project"}],
    tools=[{
        "type": "mcp",
        "server_url": "https://mcp.deepwiki.com/mcp",
        "server_label": "deepwiki",
    }],
)

Aici, serverul MCP este declarat ca un element al tabloului tools, cu tipul "mcp" și parametrii sub formă de perechi cheie-valoare în același obiect. Fără helper: scrieți dicționarul manual, ceea ce lasă mai mult loc pentru o greșeală de tastare într-un nume de cheie.

Această compatibilitate are un cost pe care trebuie să îl cunoașteți înainte de a construi pe baza ei. Doi parametri disponibili în SDK-ul nativ nu sunt disponibili aici: require_approval, care vă permite să cereți validarea umană înainte de executarea unui instrument MCP, și connector_id, care gestionează conectorii OpenAI. Dacă agentul dumneavoastră gestionează operațiuni sensibile și contați pe validarea manuală, această limitare este un blocaj și ar trebui să vă orienteze înapoi către SDK-ul nativ xAI. API-ul Responses rămâne alegerea corectă pentru o migrare de la OpenAI fără rescriere, pentru un proiect multi-furnizor unde alternați între Grok și alte modele și pentru o echipă deja familiarizată cu acest format.

API-ul Voice Agent

A treia interfață este concepută pentru agenți vocali. Scenariul tipic este un asistent telefonic care, în mijlocul unei conversații, trebuie să consulte o bază de cunoștințe, să verifice starea unei comenzi sau să interogheze un sistem extern—fără ca apelantul să experimenteze o tăcere inexplicabilă.

Configurarea MCP urmează același format ca în celelalte SDK-uri, cu aceiași parametri server_url, server_label și alții. Diferența constă în ceea ce se întâmplă după apelarea instrumentului: rezultatul este integrat în fluxul de sinteză vocală, în loc să fie redat ca text. Acest lucru influențează modul în care scrieți descrierile instrumentelor și formulați răspunsurile acestora, deoarece utilizatorul nu va vedea niciodată un tabel sau o listă—le va doar auzi.

Ce nu se schimbă între interfețe

Indiferent de SDK, secvența este aceeași. Grok descoperă instrumentele expuse de serverul MCP, selectează instrumentul care corespunde cererii, formulează apelul cu parametrii corecți, apoi integrează rezultatul în răspunsul său. Niciuna dintre cele trei interfețe nu face modelul mai mult sau mai puțin priceput în alegerea unui instrument.

Diferențele se află, așadar, în altă parte: concizia sintaxei, funcțiile periferice disponibile—streaming detaliat pe SDK-ul xAI, compatibilitatea formatului pe API-ul Responses, sinteza vocală pe Voice Agent—și cei doi parametri lipsă din formatul OpenAI. Decideți pe baza acestor criterii și nu veți da greș.

Puncte cheie

  • SDK-ul nativ xAI cu mcp() este metoda cea mai simplă și completă
  • API-ul Responses (format OpenAI) facilitează migrarea, dar nu suportă require_approval sau connector_id
  • API-ul Voice Agent conectează agenții vocali la instrumentele MCP
  • Comportamentul MCP este identic în toate cele trei cazuri; doar sintaxa se schimbă
  • Alegeți în funcție de stiva tehnologică existentă și de nevoile specifice