JSON sheme i opisi
Na ovoj stranici
Jezik alata: JSON shema
Da bi Grok mogao pozivati tvoje funkcije, mora znati što one rade i koje parametre očekuju. To je uloga JSON shema. Svaki alat opisan je strukturiranim objektom koji sadrži tri ključna dijela: naziv, opis i shemu parametara.
Anatomija definicije alata
Evo potpune strukture alata kakvu Grok API očekuje:
{
"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"]
}
}
Rastavimo svako polje:
Polje type
Uvijek ima vrijednost "function" za prilagođene funkcije. Postoje i druge vrste za ugrađene alate (web_search, code_interpreter), ali za tvoje vlastite funkcije to je uvijek "function".
Polje name
Tehnički naziv tvoje funkcije. Mora biti:
- Jedinstven među svim alatima u zahtjevu
- Opisan:
get_weatherumjestofn1 - U snake_case formatu po konvenciji:
search_products,create_ticket - Kratak, ali jasan: model koristi taj naziv kako bi odlučio koji alat pozvati
Polje description
Ovo je najvažnije polje za kvalitetu poziva. Model se prvenstveno oslanja na opis kako bi odlučio kada i kako koristiti alat. Dobar opis:
- Objašnjava što funkcija radi u jednoj rečenici
- Određuje kada je koristiti (ako nije očito)
- Spominje rubne slučajeve ako je potrebno
Usporedi ova dva opisa:
❌ "Vrijeme"
✅ "Dohvati trenutno vrijeme za grad. Vraća temperaturu, vlažnost i uvjete."
Drugi opis modelu daje dovoljno konteksta da točno zna kada pozvati tu funkciju i što će zauzvrat dobiti.
Blok parameters
Parametri slijede format JSON sheme. Podržane vrste uključuju:
string— nizovi znakovanumber/integer— brojeviboolean— true/falsearray— popisiobject— ugniježđeni objektienum— popis dopuštenih vrijednosti
Niz required navodi obavezne parametre. Ostali su opcionalni — model ih može izostaviti.
Opisi parametara
Svaki parametar trebao bi imati vlastiti description. To modelu omogućuje da razumije koju vrijednost proslijediti:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Bez opisa, model mora nagađati očekivani format — što dovodi do pogrešaka.
Napredni parametri
Enum za ograničavanje vrijednosti
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
Enum vrijednosti posebno su korisne: govore modelu točne vrijednosti koje smije koristiti, čime se eliminiraju pogreške u formatu.
Zadane vrijednosti
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
Model razumije da može izostaviti taj parametar ako mu zadana vrijednost odgovara.
Ugniježđeni objekti
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Najbolje prakse za opise
Opis je jedini kanal kroz koji model razumije tvoj alat — svaka riječ tu ima težinu. Prvo specifičnost: „Pretraži proizvode po nazivu ili kategoriji u katalogu“ modelu točno govori kada se taj alat primjenjuje, dok „Pretraži proizvode“ ostavlja prostor za nagađanje. Zatim formati: navođenje „Datum u ISO 8601 formatu (YYYY-MM-DD)“ u opisu parametra eliminira polovicu pogrešaka u argumentima jer model replicira format koji mu pokažeš. Ograničenja su dio ugovora: „Maksimalno 50 rezultata po pozivu“ sprječava model da korisniku obeća potpunost koju alat ne može pružiti. A opis povratne vrijednosti — „Vraća objekt s cijenom, dostupnošću i opisom“ — pomaže modelu da unaprijed isplanira: zna što će imati na raspolaganju prije nego što uopće izvrši poziv.
Ključne točke
- Svaki alat definiran je s
name,descriptioniparameters - Opis je faktor broj 1 za kvalitetu poziva — uloži vrijeme u njega
- Nazivi moraju biti jedinstveni i u snake_case formatu
- Koristi
enumza ograničavanje mogućih vrijednosti - Svaki parametar trebao bi imati vlastiti opis s očekivanim formatom
- Niz
requiredrazlikuje obavezne parametre od opcionalnih