Schematy JSON i opisy
Na tej stronie
Język narzędzi: Schemat JSON
Aby Grok mógł wywołać Twoje funkcje, musi wiedzieć, co robią i jakich parametrów oczekują. Tę rolę pełnią schematy JSON. Każde narzędzie jest opisane za pomocą strukturalnego obiektu zawierającego trzy kluczowe elementy: nazwę, opis oraz schemat parametrów.
Anatomia definicji narzędzia
Oto kompletna struktura narzędzia, jakiej oczekuje 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"]
}
}
Przeanalizujmy każde pole z osobna:
Pole type
Zawsze przyjmuje wartość "function" dla funkcji niestandardowych. Inne typy istnieją dla narzędzi wbudowanych (web_search, code_interpreter), ale w przypadku Twoich własnych funkcji jest to niezmiennie "function".
Pole name
Techniczna nazwa Twojej funkcji. Musi być:
- Unikalna wśród wszystkich narzędzi w żądaniu
- Opisowa:
get_weatherzamiastfn1 - Zapisana w snake_case zgodnie z konwencją:
search_products,create_ticket - Krótka, ale jednoznaczna: model używa tej nazwy, aby zdecydować, którego narzędzia użyć
Pole description
To najważniejsze pole wpływające na jakość wywołania. Model polega głównie na opisie, aby zdecydować, kiedy i jak użyć narzędzia. Dobry opis:
- Wyjaśnia w jednym zdaniu, co robi funkcja
- Określa, kiedy jej użyć (jeśli nie jest to oczywiste)
- Wspomina o przypadkach brzegowych, jeśli to konieczne
Porównaj te dwa opisy:
❌ "Pogoda"
✅ "Pobierz aktualną pogodę dla miasta. Zwraca temperaturę, wilgotność i warunki atmosferyczne."
Drugi opis daje modelowi wystarczający kontekst, by wiedzieć dokładnie, kiedy wywołać tę funkcję i czego może się spodziewać w odpowiedzi.
Blok parameters
Parametry遵循 formatu JSON Schema. Obsługiwane typy to:
string— ciągi znakównumber/integer— liczbyboolean— prawda/fałszarray— listyobject— zagnieżdżone obiektyenum— lista dozwolonych wartości
Tablica required wymienia parametry obowiązkowe. Pozostałe są opcjonalne — model może zdecydować się na ich pominięcie.
Opisy parametrów
Każdy parametr powinien mieć własny description. To właśnie pozwala modelowi zrozumieć, jaką wartość przekazać:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Bez opisu model musi zgadywać oczekiwany format, co prowadzi do błędów.
Zaawansowane parametry
Enumy do ograniczania wartości
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
Enumy są szczególnie przydatne: informują model o dokładnych wartościach, jakich może użyć, eliminując błędy formatu.
Wartości domyślne
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
Model rozumie, że może pominąć ten parametr, jeśli domyślna wartość jest wystarczająca.
Zagnieżdżone obiekty
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Najlepsze praktyki dotyczące opisów
Opis to jedyny kanał, dzięki któremu model rozumie Twoje narzędzie – każde słowo ma tu znaczenie. Przede wszystkim precyzja: „Wyszukaj produkty po nazwie lub kategorii w katalogu“ mówi modelowi dokładnie, kiedy zastosować to narzędzie, podczas gdy „Wyszukaj produkty“ pozostawia go z domysłami. Następnie formaty: określenie „Data w formacie ISO 8601 (RRRR-MM-DD)“ w opisie parametru eliminuje połowę błędów argumentów, ponieważ model replikuje pokazany mu format. Limity są częścią kontraktu: „Maksymalnie 50 wyników na wywołanie“ zapobiega obiecującemu użytkownikowi kompletności, której narzędzie nie zapewni. A opisanie zwrotu – „Zwraca obiekt z ceną, dostępnością i opisem“ – pomaga modelowi zaplanować działania z wyprzedzeniem: wie, czym będzie dysponował, zanim jeszcze wywoła funkcję.
Kluczowe wnioski
- Każde narzędzie jest definiowane przez
name,descriptioniparameters - Opis jest czynnikiem nr 1 wpływającym na jakość wywołania – poświęć mu czas
- Nazwy muszą być unikalne i zapisane w snake_case
- Używaj
enum, aby ograniczyć możliwe wartości - Każdy parametr powinien mieć własny opis z oczekiwanym formatem
- Tablica
requiredodróżnia parametry obowiązkowe od opcjonalnych