Schémata JSON a popisy
Na této stránce
Jazyk nástrojů: Schéma JSON
Aby mohl Grok volat tvé funkce, musí vědět, co dělají a jaké parametry očekávají. To je úloha schémat JSON. Každý nástroj je popsán strukturovaným objektem obsahujícím tři zásadní informace: název, popis a schéma parametrů.
Anatomie definice nástroje
Zde je úplná struktura nástroje tak, jak ji očekává 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"]
}
}
Pojďme si rozebrat každé pole:
Pole type
Pro vlastní funkce vždy "function". Existují i jiné typy pro vestavěné nástroje (web_search, code_interpreter), ale pro tvé vlastní funkce je to nezměnitelně "function".
Pole name
Technický název tvé funkce. Musí být:
- Jedinečný mezi všemi nástroji v požadavku
- Výstižný:
get_weathermístofn1 - Ve formátu snake_case podle konvence:
search_products,create_ticket - Stručný, ale explicitní: model používá tento název k rozhodnutí, který nástroj zavolat
Pole description
Toto je nejdůležitější pole pro kvalitu volání. Model se při rozhodování, kdy a jak nástroj použít, spoléhá primárně na popis. Dobrý popis:
- Vysvětluje co funkce dělá v jedné větě
- Upřesňuje kdy ji použít (pokud to není zřejmé)
- Zmiňuje hraniční případy, pokud je to nutné
Porovnej tyto dva popisy:
❌ "Počasí"
✅ "Získá aktuální počasí pro město. Vrací teplotu, vlhkost a podmínky."
Druhý popis dává modelu dostatek kontextu, aby přesně věděl, kdy tuto funkci zavolat a co dostane zpět.
Blok parameters
Parametry následují formát JSON Schema. Podporované typy zahrnují:
string— řetězce znakůnumber/integer— číslaboolean— pravda/nepravdaarray— seznamyobject— vnořené objektyenum— seznam povolených hodnot
Pole required uvádí povinné parametry. Ostatní jsou volitelné – model se může rozhodnout je vynechat.
Popisy parametrů
Každý parametr by měl mít vlastní description. To umožňuje modelu pochopit, jakou hodnotu předat:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Bez popisu musí model očekávaný formát hádat – což vede k chybám.
Pokročilé parametry
Enums pro omezení hodnot
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
Enums jsou obzvláště užitečné: říkají modelu přesné hodnoty, které může použít, čímž eliminují chyby formátu.
Výchozí hodnoty
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
Model pochopí, že může tento parametr vynechat, pokud mu vyhovuje výchozí hodnota.
Vnořené objekty
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Osvědčené postupy pro popisy
Popis je jediným kanálem, skrze který model chápe tvůj nástroj – každé slovo zde hraje roli. Na prvním místě je specifičnost: „Vyhledat produkty podle názvu nebo kategorie v katalogu“ říká modelu přesně, kdy tento nástroj použít, zatímco „Vyhledat produkty“ ho nechává tápat. Dále formáty: upřesnění „Datum ve formátu ISO 8601 (RRRR-MM-DD)“ v popisu parametru eliminuje polovinu chyb v argumentech, protože model replikuje formát, který mu ukážeš. Limity jsou součástí smlouvy: „Maximálně 50 výsledků na volání“ zabrání modelu slibovat uživateli úplnost, kterou nástroj neposkytne. A popis návratové hodnoty – „Vrací objekt s cenou, dostupností a popisem“ – pomáhá modelu plánovat dopředu: ví, co bude mít k dispozici, ještě před samotným voláním.
Klíčové poznatky
- Každý nástroj je definován pomocí
name,descriptionaparameters - Popis je faktorem číslo jedna pro kvalitu volání – věnuj mu čas
- Názvy musí být jedinečné a ve formátu snake_case
- Použij
enumpro omezení možných hodnot - Každý parametr by měl mít vlastní popis s očekávaným formátem
- Pole
requiredrozlišuje povinné parametry od volitelných