## Narzędzia (function calling)

*Agenci*

*Ostatnia zmiana: 28 września 2026*

Model nie wykonuje żadnego kodu. Dostaje listę narzędzi z nazwą, opisem i schematem argumentów, a gdy uzna to za potrzebne, zamiast odpowiedzi wypisuje wywołanie: twój kod je wykonuje i odsyła wynik.

**Po ludzku:** Kierownik, który może tylko dzwonić. Ma kartkę z listą spraw, które załatwi asystent, i krótkim opisem każdej. Mówi: „Sprawdź, czy jutrzejszy pociąg o 8:15 jedzie planowo”, a asystent sprawdza i oddzwania z wynikiem. Gdy opisy na kartce są mętne, kierownik prosi nie o to, co trzeba.

*Interaktywny widżet na stronie: Zmień jakość opisów narzędzi i przełącz równoległe wywołania, potem przejdź krok po kroku przez wymianę. Patrz, po które narzędzie sięga model, ile requestów to kosztuje i czy odpowiedź jest prawdziwa.*

### Jak działa function calling

- Model nie ma dostępu do internetu, bazy danych ani twojego komputera. Umie tylko napisać w umówionym formacie „wywołaj prognoza_pogody dla Gdańska na jutro”. Wynik wraca do niego jako kolejna wiadomość, a model czyta go jak każdy inny tekst. Jak z tego powstaje wielokrokowa praca, opisuje temat „Pętla agenta”.
- Definicje trafiają do promptu jako tekst w formacie znanym modelowi z treningu, tak jak role w temacie „Jak model widzi czat”. Wywołanie to też zwykłe tokeny: API wyłuskuje je i zwraca jako osobne pole z id, nazwą i argumentami, a powód zakończenia mówi, że model czeka na wynik. Kilka wywołań naraz wykonujesz współbieżnie i odsyłasz wszystkie wyniki, każdy z id swojego wywołania. Gdy kolejność ma znaczenie, wyłączasz równoległość (`parallel_tool_calls: false` w OpenAI, `disable_parallel_tool_use` w Anthropic).
- `tool_choice`: `auto` (domyślnie, model decyduje), `required` albo `any` (musi wywołać któreś), konkretne narzędzie (np. do wyciągania danych do schematu), `none` (nie wolno wywołać). Wymuszenie w każdej turze nie pozwoli modelowi skończyć, więc w pętli stosuje się je tylko w wybranych krokach. Wymuszenie nie wszędzie działa (stan na wrzesień 2026): Claude Opus 5.5 i Fable 5.1 odrzucają `any` i konkretne narzędzie błędem 400. Do wyciągania danych do schematu użyj tam structured outputs (temat „Wymuszanie formatu”).
- Część narzędzi wykonuje dostawca: wyszukiwanie w sieci albo uruchamianie kodu w piaskownicy dzieje się po jego stronie, a ty dostajesz gotowy wynik. Mniej kodu do napisania, mniej kontroli nad tym, co i gdzie się wykonało.
- Computer use i agenci przeglądarkowi to ta sama pętla z ekranem jako narzędziem: model dostaje zrzut ekranu, wypisuje akcję (kliknij w x, y, wpisz tekst), twój kod ją wykonuje i odsyła nowy zrzut. Każdy zrzut to wejście obrazowe, u Anthropic ok. 1000–1800 tokenów, i zostaje w historii, więc w długich sesjach stare zrzuty się usuwa. Każda strona, na którą patrzy agent, to niezaufane wejście: tekst na ekranie może nim sterować jak każdy wynik narzędzia (temat „Prompt injection”).

### Opis to jedyna instrukcja obsługi

- Model wybiera narzędzie tylko na podstawie nazwy, opisu i schematu, kodu nie widzi. Opis pisz jak dla nowej osoby w zespole: co narzędzie robi, kiedy go użyć, kiedy nie, w jakim formacie podać argumenty i co zwraca. Dwa narzędzia o podobnych opisach to dla modelu rzut monetą, co widać w wariancie z nakładającymi się narzędziami.
- Pomagają nazwy z przedrostkiem usługi (`kolej_status`, `kolej_rozklad`), jednoznaczne parametry (`user_id` zamiast `user`), enumy zamiast wolnego tekstu i przykładowe wywołania: w testach Anthropic przykłady w definicji podniosły poprawność złożonych argumentów z 72% do 90%. Lepiej kilka narzędzi pod konkretne zadania niż opakowanie każdego endpointu API.
- Wynik też projektujesz. Zwracaj tylko potrzebne pola, czytelne nazwy zamiast wewnętrznych UUID, a długie listy przycinaj z informacją, jak pobrać resztę. Każdy token wyniku zostaje w kontekście i jest wysyłany w każdej kolejnej turze, chyba że harness go wyczyści albo skompaktuje (temat „Context engineering i pamięć”).
- Tryb ścisły (`strict`) to constrained decoding z tematu „Wymuszanie formatu”: argumenty zawsze pasują do schematu. Sensownych wartości nie gwarantuje: model nadal potrafi zmyślić brakujący parametr albo wybrać zły dzień.

### Każde narzędzie kosztuje w każdym requeście

- Definicje to tekst doklejany do każdego requestu, więc płacisz za nie w każdej turze, także gdy żadne narzędzie nie zostanie użyte. Dostawca dolicza jeszcze własny ukryty prompt o obsłudze narzędzi, u Anthropic kilkaset tokenów, zależnie od modelu.
- Definicje stoją na początku promptu, więc dobrze się cache’ują (temat „Prompt caching”). Dodanie, usunięcie albo przestawienie narzędzia w trakcie rozmowy unieważnia cache wszystkiego, co stoi za nimi. OpenAI ma do tego `allowed_tools`: zawęża wybór w danej turze bez zmiany listy definicji.
- Więcej narzędzi to wyższy rachunek, mniej miejsca w kontekście i trudniejszy wybór. OpenAI zaleca mniej niż 20 funkcji naraz, zastrzegając, że to tylko luźna wskazówka. Anthropic podaje przykład pięciu serwerów MCP z 58 narzędziami, których definicje zajmowały ok. 55 tys. tokenów, zanim padło pierwsze pytanie (temat „MCP”). Przy takiej skali pomaga wyszukiwanie narzędzi: model widzi narzędzie do szukania, a pełne definicje dostaje dopiero wtedy, gdy są potrzebne.

### Błędy i bezpieczeństwo

- Błąd też jest wynikiem. Zamiast przerywać pracę, odeślij modelowi konkretny komunikat: co jest nie tak i jak to poprawić, a model zwykle poprawi się w następnym kroku. Argumenty sprawdzaj w kodzie, zanim cokolwiek wykonasz. Operacje zmieniające stan zabezpiecz kluczem idempotencji: po błędzie sieci kod albo model może ponowić to samo wywołanie, a ten sam bilet nie może zostać kupiony dwa razy.
- Narzędzie to uprawnienie. Model może wywołać je z błędnymi argumentami albo pod wpływem tekstu, który właśnie przeczytał, bo wyniki narzędzi (strony, maile, dokumenty) to niezaufane dane. Daj najmniejsze potrzebne prawa, a akcje nieodwracalne, jak przelew, usunięcie czy wysyłka, niech czekają na potwierdzenie przez człowieka, wymuszone w kodzie, nie w prompcie. Więcej w temacie „Prompt injection”.

### Sprawdź się

**Pytanie:** Jak działa function calling i jak projektować narzędzia dla modelu?

**Krótka odpowiedź:** Model niczego nie wykonuje. Z pytaniem dostaje definicje narzędzi: nazwę, opis i schemat argumentów w JSON Schema. Gdy uzna narzędzie za potrzebne, zamiast odpowiedzi wypisuje wywołanie w wyuczonym formacie, czasem kilka naraz. Twój kod waliduje argumenty, wykonuje wywołanie i odsyła wynik z id wywołania. Model wybiera głównie po opisie, więc opisy pisze się jak dokumentację, narzędzia nie powinny się nakładać, a wyniki mają być zwięzłe. Za definicje płaci się w każdym requeście. Błąd wraca jako wynik ze wskazówką, operacje zmieniające stan są idempotentne, a nieodwracalne zatwierdza człowiek.

### Pytania pogłębiające

- **Czym function calling różni się od structured output?** Od strony modelu to ten sam mechanizm: tekst w zadanym formacie. Różnica jest w tym, co dzieje się dalej. Structured output to końcowa odpowiedź dla twojego kodu. Wywołanie narzędzia to prośba, po której wynik wraca do modelu i rozmowa trwa dalej.
- **Ile narzędzi to za dużo?** Twardej granicy nie ma. Sygnałem są pomyłki w wyborze narzędzia na twoim zestawie ewaluacyjnym i rosnący koszt definicji. Wtedy scalasz podobne narzędzia, dzielisz pracę między subagentów z własnymi zestawami albo ładujesz definicje na żądanie przez wyszukiwanie narzędzi.
- **Co zrobić, gdy model podaje złe argumenty?** Najpierw poprawić opis i schemat: format, przykłady, enumy. Potem walidacja w kodzie i czytelny błąd odsyłany modelowi, żeby mógł się poprawić. Tryb ścisły usuwa błędy składni i typów, ale nie złe wartości.
- **Wynik narzędzia ma 50 tys. tokenów. Co robisz?** Nie wklejasz go w całości, bo zostanie w kontekście i pójdzie w każdej turze, dopóki czegoś nie wyczyścisz. Filtrujesz pola, stronicujesz, zwracasz podsumowanie z uchwytem do pełnych danych, a dużą treść zapisujesz do pliku, który agent przeszuka osobnym narzędziem.
- **Kiedy zamiast wielu wywołań dać modelowi narzędzie do uruchamiania kodu?** Gdy zadanie to wiele wywołań i obróbka danych, np. pobierz 50 rekordów, przefiltruj, policz. Model pisze skrypt, który sam woła narzędzia, a do kontekstu wraca tylko wynik końcowy. Anthropic podaje ok. 37% mniej tokenów na złożonych zadaniach badawczych. Ceną jest piaskownica do uruchamiania kodu i trudniejszy audyt.

### Źródła

- [Anthropic: Writing effective tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents)
- [OpenAI: Function calling (dokumentacja)](https://developers.openai.com/api/docs/guides/function-calling)
- [Anthropic: Advanced tool use (wyszukiwanie narzędzi)](https://www.anthropic.com/engineering/advanced-tool-use)
- [Dokumentacja Claude: Define tools (tool_choice i ograniczenia wymuszania)](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools)
- [Dokumentacja Claude: Computer use tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool)

Strona interaktywna: https://howaiworks.dev/pl/narzedzia/