Schémy JSON a popisy
Na tejto strane
Jazyk nástrojov: Schéma JSON
Aby mohol Grok volať tvoje funkcie, potrebuje vedieť, čo robia a aké parametre očakávajú. To je úlohou schém JSON. Každý nástroj je opísaný štruktúrovaným objektom obsahujúcim tri základné časti: názov, popis a schému parametrov.
Anatómia definície nástroja
Tu je kompletná štruktúra nástroja tak, ako ju očakáva API Grok:
{
"type": "function",
"name": "get_weather",
"description": "Get the current weather for a given city",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city name (e.g., Paris, Lyon)"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"default": "celsius"
}
},
"required": ["city"]
}
}
Poďme si rozobrať každé pole:
Pole type
Pre vlastné funkcie má vždy hodnotu "function". Existujú aj iné typy pre vstavané nástroje (web_search, code_interpreter), ale pre tvoje vlastné funkcie je to vždy "function".
Pole name
Technický názov tvojej funkcie. Musí byť:
- Jedinečný medzi všetkými nástrojmi v požiadavke
- Výstižný:
get_weathernamiestofn1 - V tvare snake_case podľa konvencie:
search_products,create_ticket - Stručný, no explicitný: model používa tento názov na rozhodovanie, ktorý nástroj zavolať
Pole description
Toto je najdôležitejšie pole pre kvalitu volania. Model sa pri rozhodovaní, kedy a ako nástroj použiť, spolieha primárne na popis. Dobrý popis:
- V jednej vete vysvetľuje, čo funkcia robí
- Špecifikuje, kedy ju použiť (ak to nie je zrejmé)
- Spomína hraničné prípady, ak je to potrebné
Porovnaj tieto dva popisy:
❌ "Počasie"
✅ "Získa aktuálne počasie pre mesto. Vracia teplotu, vlhkosť a podmienky."
Druhý popis dáva modelu dostatok kontextu, aby presne vedel, kedy túto funkciu zavolať a čo dostane späť.
Blok parameters
Parametre nasledujú formát JSON Schema. Podporované typy zahŕňajú:
string— reťazce znakovnumber/integer— číslaboolean— pravda/nepravdaarray— zoznamyobject— vnorené objektyenum— zoznam povolených hodnôt
Pole required obsahuje zoznam povinných parametrov. Ostatné sú voliteľné – model sa môže rozhodnúť ich vynechať.
Popisy parametrov
Každý parameter by mal mať vlastný description. To umožňuje modelu pochopiť, akú hodnotu má odovzdať:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Bez popisu musí model formát hádať – čo vedie k chybám.
Pokročilé parametre
Enumy na obmedzenie hodnôt
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
Enumy sú obzvlášť užitočné: hovoria modelu presné hodnoty, ktoré môže použiť, čím eliminujú chyby vo formáte.
Predvolené hodnoty
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
Model pochopí, že tento parameter môže vynechať, ak mu vyhovuje predvolená hodnota.
Vnorené objekty
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Osvedčené postupy pre popisy
Popis je jediným kanálom, cez ktorý model chápe tvoj nástroj – každé slovo tu hrá rolu. Na prvom mieste je špecifickosť: „Vyhľadaj produkty podľa názvu alebo kategórie v katalógu“ modelu presne povie, kedy sa tento nástroj použije, zatiaľ čo „Vyhľadaj produkty“ ho nechá tápať. Ďalej sú to formáty: špecifikácia „Dátum vo formáte ISO 8601 (RRRR-MM-DD)“ v popise parametra eliminuje polovicu chýb v argumentoch, pretože model replikuje formát, ktorý mu ukážeš. Limity sú súčasťou zmluvy: „Maximálne 50 výsledkov na volanie“ zabráni modelu sľubovať používateľovi úplnosť, ktorú nástroj neposkytne. A popis návratovej hodnoty – „Vracia objekt s cenou, dostupnosťou a popisom“ – pomáha modelu plánovať dopredu: vie, čo bude mať k dispozícii ešte pred samotným volaním.
Kľúčové poznatky
- Každý nástroj je definovaný pomocou
name,descriptionaparameters - Popis je faktorom číslo jedna pre kvalitu volania – venuj mu čas
- Názvy musia byť jedinečné a v tvare snake_case
- Použi
enumna obmedzenie možných hodnôt - Každý parameter by mal mať vlastný popis s očakávaným formátom
- Pole
requiredodlišuje povinné parametre od voliteľných