Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Ulkoiset työkalut ja tuetut SDK:t

Oppitunti 3 / 12 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Kolme sisäänmenoa samaan mekanismiin
  2. Natiivi xAI SDK
  3. Responses API, OpenAI-yhteensopiva
  4. Voice Agent API
  5. Mikä ei muutu rajapintojen välillä
  6. Keskeiset asiat

Kolme sisäänmenoa samaan mekanismiin

xAI tarjoaa etä-MCP:n kolmen eri rajapinnan kautta. Ne on suunnattu erilaisille kehittäjille: yksi uusiin projekteihin, toinen siirrettyihin projekteihin ja kolmas erityisiin käyttötarkoituksiin. MCP:n toiminta on täsmälleen sama kaikissa kolmessa tapauksessa; vain konfiguraatiosyntaksi ja oheistyökalut muuttuvat. Valintasi riippuu siis nykyisestä teknologiapinostasi, ei protokollan ominaisuuksista.

Natiivi xAI SDK

Tämä on xAI:n suosittelema menetelmä. Se tarjoaa mcp()-apufunktion, joka tiivistää konfiguraation yhdeksi funktiokutsuksi.

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"],
)

mcp()-apufunktio hyväksyy kaikki MCP-konfiguraatioparametrit – URL-osoitteen, nimen, kuvauksen, sallitut työkalut ja todennuksen – ja hoitaa niiden muotoilun oikein rajapintaa varten. Tämä on tiivein syntaksi, ja mikä tärkeintä, se on tapa, jossa virheen tekemisen todennäköisyys on pienin, sillä avainten nimet ja sisäkkäisyys hoidetaan puolestasi. Valitse tämä polku uusiin projekteihin, joissa ei ole yhteensopivuusrajoitteita, nopeaan prototyyppaukseen ja aina kun hyödynnät xAI:n omia ominaisuuksia, kuten yllä näkyvää yksityiskohtaista suoratoistoa (verbose streaming).

Responses API, OpenAI-yhteensopiva

Tämä rajapinta hyväksyy täsmälleen OpenAI API:n formaatin. Se on olemassa erityisestä syystä: jotta tiimi, joka on jo kirjoittanut sovelluksensa tässä formaatissa, ei joutuisi kirjoittamaan kaikkea uudelleen testatakseen Grokia. Muutos rajoittuu API-avaimen ja perus-URL-osoitteen vaihtamiseen.

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",
    }],
)

Tässä MCP-palvelin määritellään tools-taulukon elementtinä, jonka tyyppi on "mcp" ja parametrit ovat avain-arvopareja samassa objektissa. Apufunktiota ei ole: kirjoitat sanakirjan käsin, mikä jättää enemmän tilaa kirjoitusvirheille avainten nimissä.

Tällä yhteensopivuudella on hintansa, ja sinun tulee tietää se ennen sen päälle rakentamista. Kaksi natiivissa SDK:ssa saatavilla olevaa parametria eivät ole käytettävissä tässä: require_approval, jonka avulla voit vaatia ihmisen vahvistuksen ennen MCP-työkalun suorittamista, ja connector_id, joka hallinnoi OpenAI-koneistoja. Jos agenttisi käsittelee arkaluonteisia toimintoja ja olet luottanut manuaaliseen vahvistukseen, tämä rajoitus on este, ja sinun kannattaa palata natiiviin xAI SDK:hon. Responses API on silti oikea valinta siirryttäessä OpenAI:sta ilman uudelleenkirjoitusta, monitoimittajaprojekteissa, joissa vuorottelet Grokin ja muiden mallien välillä, sekä tiimeille, jotka tuntevat tämän formaatin ennestään.

Voice Agent API

Kolmas rajapinta on suunniteltu puheagenteille. Tyypillinen skenaario on puhelinavustaja, jonka täytyy keskustelun keskellä hakea tietokannasta, tarkistaa tilauksen status tai kysyä ulkoiselta järjestelmältä – ilman että soittaja kohtaa selittämätöntä hiljaisuutta.

MCP-konfiguraatio noudattaa samaa formaattia kuin muissakin SDK:issa, samoilla server_url-, server_label- ja muilla parametreilla. Ero on siinä, mitä tapahtuu työkalukutsun jälkeen: tulos integroidaan puhesynteesivirtaan tekstinäyttämisen sijaan. Tämä vaikuttaa siihen, miten kirjoitat työkalujen kuvaukset ja muotoilet vastaukset, sillä käyttäjä ei koskaan näe taulukkoa tai listaa – hän vain kuulee ne.

Mikä ei muutu rajapintojen välillä

SDK:sta riippumatta sekvenssi on sama. Grok löytää MCP-palvelimen tarjoamat työkalut, valitsee pyyntöön sopivan, muotoilee kutsun oikeilla parametreilla ja integroi tuloksen vastaukseensa. Mikään kolmesta rajapinnasta ei tee mallista parempaa tai huonompaa työkalun valinnassa.

Erot löytyvät siis muualta: syntaksin tiiviydestä, käytettävissä olevista oheisominaisuuksista – yksityiskohtainen suoratoisto xAI SDK:ssa, formaattiyhteensopivuus Responses API:ssa, puhesynteesi Voice Agentissa – sekä kahdesta OpenAI-formaatista puuttuvasta parametrista. Päätä näiden kriteerien perusteella, etkä mene vikaan.

Keskeiset asiat

  • Natiivi xAI SDK funktiolla mcp() on yksinkertaisin ja kattavin menetelmä
  • Responses API (OpenAI-formaatti) helpottaa siirtymää, mutta ei tue parametreja require_approval tai connector_id
  • Voice Agent API yhdistää puheagentit MCP-työkaluihin
  • MCP:n toiminta on identtinen kaikissa kolmessa tapauksessa; vain syntaksi muuttuu
  • Tee valinta nykyisen teknologiapinosi ja erityistarpeidesi perusteella