Najlepsze praktyki wywoływania narzędzi przez agenta: dlaczego Twój agent wybiera złe narzędzie

Najlepsze praktyki wywoływania narzędzi przez agenta: dlaczego Twój agent wybiera złe narzędzie

Najlepsze praktyki wywoływania narzędzi przez agenta to jedyne, co oddziela działające demo od agenta, który po cichu wywołuje złe narzędzie na produkcji. Zespół inżynierski Anthropic zmierzył, że przepisanie jednego opisu skróciło wynik narzędzia z 206 tokenów do 72, a Claude Code ma teraz sztywny limit 25 000 tokenów na każdą odpowiedź narzędzia, bo ten wyciek jest realny. Twój agent zawodzi na cztery sposoby: złe narzędzie, złe argumenty, niekontrolowane pętle i wyciek tokenów. Każdy z nich ma poprawkę, którą wdrożysz jeszcze w tym tygodniu.

Kluczowe wnioski:

• Wywoływanie narzędzi przez agenta zawodzi na dokładnie cztery sposoby: złe narzędzie, złe argumenty, niekontrolowane pętle i wyciek tokenów.
• Opisy narzędzi to jedyna instrukcja, którą model widzi w momencie wyboru, więc to one naprawiają większość błędnych wywołań.
• Płaskie schematy skrojone pod zadanie, z walidowanymi danymi wejściowymi, eliminują większość awarii argumentów.
• Zwięzłe odpowiedzi narzędzi i pętla ewaluacji przy każdej zmianie trzymają koszt tokenów i regresje w ryzach.

Dlaczego wywoływanie narzędzi przez agenta zawodzi na produkcji?

Wywoływanie narzędzi przez agenta zawodzi na cztery sposoby: model wybiera złe narzędzie, zapisuje złe argumenty, kręci się w niekontrolowanej pętli albo traci tokeny przez rozdęte odpowiedzi. Każda awaria uderza w inny krok pętli wywołania, więc kolejność napraw ma znaczenie. Zacznij od wyboru, bo błędnie wybrane narzędzie zatruwa każdy kolejny krok.

Cała recepta w skrócie:

Przerób je w tej kolejności. Praktyki 1 i 2 zajmują jedno popołudnie i usuwają większość błędnych wywołań narzędzi i argumentów, które widzisz dzisiaj. Opis narzędzia to nie jest dokumentacja. To jedyna instrukcja, jaką model dostaje w momencie wyboru.

Faza 1: Zaprojektuj narzędzia, których model naprawdę potrafi użyć

Najtańsze zyski niezawodności w wywoływaniu narzędzi przez agenta siedzą w definicjach narzędzi, nie w promptach ani w wyborze modelu. Model nigdy nie czyta Twojej dokumentacji API ani README-a. Widzi nazwę, opis i schemat JSON, i na tej podstawie podejmuje decyzję. Dopracuj te trzy elementy, a trafność wyboru wzrośnie, zanim w ogóle tkniesz cokolwiek innego.

Praktyka 1: Pisz opisy, na których model może działać

Pisz opisy narzędzi jako instrukcje dla modelu, nie jako dokumentację API. Opis, który zadowala programistę ("wrapper REST na endpoint użytkowników"), nie daje modelowi niczego, na czym mógłby oprzeć decyzję. Zarówno przewodnik inżynierski Anthropic o pisaniu narzędzi, jak i ich najlepsze praktyki definicji narzędzi promują ten sam wzorzec: powiedz, kiedy użyć narzędzia, co zwraca i kiedy go NIE używać.

{
  "name": "get_user",
  "description": "Fetches a user profile. Use ONLY when you already have a user_id. Do NOT use to search or list users; call search_users instead. Returns name, email, plan. Errors if user_id is not a valid UUID."
}

w przeciwieństwie do wersji, którą wdraża większość zespołów:

{
  "name": "get_user",
  "description": "Gets a user."
}

Dwie zasady wykonują tu większość pracy. Po pierwsze, nazywaj parametry tak, by ich znaczenie było jednoznaczne: user_id, nigdy user ani id, bo user zachęca model do przekazania nazwy lub e-maila tam, gdzie należy się UUID. Po drugie, jawnie formułuj wykluczenia. "Do NOT use to search users" zapobiega większej liczbie błędnych wywołań niż dowolna ilość pozytywnego opisu, ponieważ modele mylą nakładające się narzędzia znacznie częściej, niż źle rozumieją pojedyncze, wyraźnie ograniczone narzędzia. Mechanikę po stronie dostawców, czyli jak te definicje trafiają do API OpenAI, Anthropic i Google, znajdziesz w naszym przewodniku po function calling u wielu dostawców.

Praktyka 2: Trzymaj schematy płaskie i skrojone pod zadanie

Trzymaj schematy wejściowe płaskie, z każdym polem, którego zadanie naprawdę potrzebuje, i bez tych, których nie potrzebuje. Zagnieżdżone obiekty z opcjonalnymi gałęziami to miejsce, gdzie lęgną się awarie argumentów: model musi wywnioskować strukturę, której nigdy nie widział na przykładach. Przewodnik OpenAI po function calling akceptuje dowolny JSON Schema, ale "dozwolone" nie znaczy "niezawodne".

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "ticket": {
        "type": "object",
        "properties": {
          "details": {
            "type": "object",
            "properties": {
              "title": { "type": "string" },
              "meta": { "type": "object" }
            }
          }
        }
      }
    }
  }
}

Spłaszcz go do poziomu zadania:

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "medium", "high"] },
      "assignee_id": { "type": "string" }
    },
    "required": ["title", "priority"]
  }
}

Wyliczenia (enum) biją wolny tekst w każdym polu o ograniczonym zbiorze wartości. Tablice required biją opcjonalne wszystko. Jeśli model prawie zawsze potrzebuje danego pola, ustaw je jako required w schemacie narzędzia, nawet gdy Twoje API nazywa je opcjonalnym. Nie odwzorowujesz swojego API. Projektujesz powierzchnię, którą jeden konkretny model potrafi poprawnie wypełnić.

Faza 2: Zarządzaj zestawem narzędzi, nie tylko narzędziami

Jakość pojedynczych narzędzi przestaje wystarczać, gdy agent nosi ich więcej niż garść, bo błędy wyboru rosną wraz z rozmiarem listy, którą czyta model.

Praktyka 3: Zamykaj wieloetapowe sekwencje API w atomowe narzędzia

Sklej każdą stałą sekwencję wywołań API w jedno atomowe narzędzie. Wpis inżynierski Anthropic podaje schedule_event i get_customer_context jako wzorzec: jedno wywołanie, które robi całą robotę, bije trzy wywołania, które agent musi za każdym razem poprawnie połączyć w łańcuch. Każde ogniwo łańcucha to kolejna tura, w której model może utknąć, błędnie spróbować ponownie albo wpaść w pętlę.

# What the agent does WITHOUT an atomic tool: 3 calls, 3 chances to fail
calendar = call_tool("list_calendars", {})
free = call_tool("find_free_slot", {"calendar_id": calendar["items"][0]["id"], "duration": 30})
call_tool("create_event", {"calendar_id": calendar["items"][0]["id"], "start": free["start"]})

# One atomic tool: the sequence lives in your code, not the model's head
call_tool("schedule_event", {"duration": 30, "attendees": ["[email protected]"]})

Reguła praktyczna: jeśli model musi zawsze wywołać B po A, to A i B są jednym narzędziem w dwóch kostiumach.

Praktyka 4: Dynamicznie nadawaj przestrzenie nazw, przycinaj i filtruj narzędzia

Nadawaj przestrzenie nazw każdej nazwie narzędzia i pokazuj każdemu agentowi tylko ten podzbiór, którego potrzebuje jego bieżące zadanie. Generyczne nazwy kolidują w chwili, gdy podłączysz dwie integracje. Wyobraź sobie agenta spiętego z dwoma serwerami MCP, z których każdy wystawia narzędzie o nazwie search: dwa identyczne czasowniki, żadnego sposobu, by je rozróżnić. Anthropic dokumentuje mierzalne zyski w ewaluacji dzięki prefiksom:

Przycinanie liczy się tak samo jak nazewnictwo. Agent wsparcia nie potrzebuje załadowanych narzędzi billingowych, gdy odpowiada na pytanie o hasło. Wzorzec planista-pracownik, w którym planista kieruje zadanie do pracownika ładującego tylko istotne narzędzia, to standardowa poprawka; how-to LangGraph o dynamicznym ładowaniu narzędzi przeprowadza przez implementację. Ile narzędzi to za dużo? Traktuj 5-10 na agenta jako zakres roboczy, nie prawo: trafność spada wraz ze wzrostem listy, a lekarstwem jest filtrowanie, nie większy model. Jeśli dopiero wybierasz warstwę routingu i filtrowania, porównaj opcje w naszym zestawieniu najlepszych bibliotek function calling.

Faza 3: Kontroluj, co wraca i co wychodzi

Pętla działa w obie strony, a większość zespołów projektuje tylko połowę wychodzącą. To, co zwracają Twoje narzędzia, decyduje, ile okna kontekstu przetrwa do następnej tury, a to, co odrzuca Twoja walidacja, decyduje, czy model uczy się na błędach, czy je powtarza.

Praktyka 5: Zwracaj zwięzłe wyniki o wysokiej wartości sygnału

Zwracaj najmniejszy wynik, na którym model może działać, z czytelnymi dla człowieka identyfikatorami zamiast surowych ID. Wpis inżynierski Anthropic opisuje narzędzie, którego domyślny wynik liczył 206 tokenów; zwięzłe ustawienie response_format ścięło ten sam wynik do 72 tokenów, czyli mniej więcej do jednej trzeciej. Pomnóż to przez dziesiątki wywołań na zadanie, a otrzymasz odpowiedź, czy Twój agent w ogóle kończy pracę.

// Before: 206 tokens (shape per Anthropic's documented example)
{
  "status": "success",
  "data": {
    "id": "8f14e45f-ceea-3f9c-a2f3-90c1b5e0a7d2",
    "object": "task", "created_at": "2026-07-02T09:14:00Z",
    "updated_at": "2026-07-11T16:40:12Z", "completed_at": null,
    "assignee": {"id": "c9a1...f2", "object": "user"},
    "projects": [{"id": "b7d3...91", "object": "project"}],
    "permalink": "https://app.asana.com/0/.../f"
  }
}

// After: 72 tokens
{ "task": "Fix login redirect", "assignee": "Dana Kim", "project": "Web App", "due": "2026-07-20" }

Jeszcze dwa szczegóły z tego samego źródła: Anthropic wspiera enum response_format (detailed kontra concise) w definicjach narzędzi, więc możesz zadeklarować oczekiwany kształt zamiast parsować strumień z węża strażackiego. A Claude Code ogranicza odpowiedzi narzędzi do 25 000 tokenów, czyli sztywnego sufitu, który i tak przycina rozdęte wyniki. Anthropic raportuje też, jako własne ustalenie, że rozwiązywanie UUID-ów do nazw semantycznych mierzalnie ograniczyło halucynacje przy pobieraniu danych, dlatego payload "po" powyżej mówi "Dana Kim", a nie c9a1...f2. Rozdęte odpowiedzi to także problem kosztowy; pełny obraz znajdziesz w naszym przewodniku po redukcji kosztów API LLM.

Praktyka 6: Waliduj każde wywołanie i spraw, by błędy uczyły model

Waliduj każde wywołanie narzędzia po stronie serwera i zwracaj błędy zawierające poprawkę. Artykuł Martina Fowlera o function calling ujmuje to bez ogródek: nigdy nie ufaj danym wyjściowym modelu. Model przekaże stringi tam, gdzie należy się enum, i wymyśli ID, które nie istnieją.

def create_ticket(args):
    if args.get("priority") not in {"low", "medium", "high"}:
        return {"error": f"priority must be one of: low, medium, high. Got '{args.get('priority')}'. Pass priority='medium' for normal issues."}
    if not is_valid_uuid(args.get("assignee_id")):
        return {"error": "assignee_id must be a UUID. Call list_team_members to get valid IDs, then retry."}
    return db.create_ticket(**args)

Komunikat błędu to cała gra. Porównaj:

# Unhelpful: the model retries the same bad call
{"error": "invalid input"}

# Helpful: the model knows exactly what to change
{"error": "priority must be one of: low, medium, high. Got 'urgent'. Use 'high'."}

Każdy błąd walidacji, który zwraca Twoje narzędzie, to prompt, który piszesz dla następnej próby modelu. Błędy, które nazywają ograniczenie i wskazują narzędzie naprawcze, zamieniają pętlę ponowień w jednorazową naprawę. To także Twoja pierwsza linia obrony bezpieczeństwa; nasz przewodnik po guardrailach LLM omawia to dogłębnie.

Faza 4: Jak to zabezpieczyć, a potem uczynić mierzalnym?

Bezpieczeństwo i pomiar to ta sama faza, ponieważ niezabezpieczona destrukcyjna akcja i niemierzona regresja objawiają się tak samo: jako incydenty, których nie dało się przewidzieć. Zabezpiecz bramkami akcje, których nie da się cofnąć, a potem oprzyrządowanie na wszystkim, żeby kolejna zmiana narzędzia była decyzją z dowodami, a nie nadzieją.

Praktyka 7: Bramkuj destrukcyjne akcje za potwierdzeniem człowieka

Oddziel narzędzia do odczytu od narzędzi do zapisu i postaw bramkę potwierdzenia przez człowieka na wszystkim, co destrukcyjne. Adnotacje narzędzi w specyfikacji MCP istnieją dokładnie po to: destructiveHint oznacza narzędzia wykonujące destrukcyjne aktualizacje, a openWorldHint flaguje narzędzia dotykające systemów zewnętrznych, dzięki czemu klient może zapytać przed wykonaniem. Używaj ich.

Ten tryb awarii nie jest hipotetyczny. Laurent Kubaski udokumentował przypadek w swoim opisie tool callingu z lipca 2025, z podlinkowanym oryginalnym raportem, w którym użytkownik poprosił Copilota w Excelu o działanie na wierszu 4, a agent zadziałał na wierszu 8. Żadna bramka potwierdzenia nie stała między błędnym wierszem a zapisem. Poprawką jest wzorzec, który AWS dokumentuje dla Bedrock Agents: agent przygotowuje akcję, zwraca ją do akceptacji i wykonuje dopiero po potwierdzeniu przez człowieka. Cursor robi tak samo przy edycji plików. Ograniczaj uprawnienia do odczytu tam, gdzie zadanie potrzebuje tylko odczytu, i traktuj bramki potwierdzenia jako część swojej powierzchni ataku iniekcyjnego, czyli temat naszego przewodnika po zapobieganiu prompt injection.

Praktyka 8: Uruchamiaj pętlę ewaluacji przy każdej zmianie narzędzia

Uruchamiaj mały zestaw ewaluacyjny przed i po każdej zmianie narzędzia i czytaj metryki w stałej kolejności. Przewodnik optymalizacyjny Paragon proponuje czterometrykowy układ, który warto przyjąć:

Cookbook ewaluacji narzędzi Anthropic, zbudowany na realnych ewaluacjach MCP dla Slacka i Asany, pokazuje, jak wyglądają dobre i złe zadania ewaluacyjne:

# Weak: vague, many valid paths, impossible to score
"Use the Asana tools to organize some work."

# Strong: one correct tool, checkable arguments, binary outcome
"Create a task titled 'Renew TLS cert' in project 'Infra' assigned to [email protected], due 2026-08-15. Expect exactly one create_task call with those four fields."

Nasza interpretacja, oznaczona jako taka: opublikowane liczby podpowiadają kolejność pracy. Najpierw sprawdzaj poprawność narzędzia, bo własne pomiary Anthropic pokazują, że zmiany opisów i nazw bezpośrednio ją przesuwają (przepisanie 206 do 72 tokenów, ustalenie o halucynacjach UUID-do-nazwy), a wydajność zadania zostaw na koniec, ponieważ głównie odzwierciedla awarie, które trzy pierwsze metryki już wyłapały. Na zestaw startowy zaprojektuj 15-30 zadań, dwa lub trzy na narzędzie, każde z jednym oczekiwanym wywołaniem i binarnym warunkiem zaliczenia. Taki rozmiar wystarczy, by wyłapać regresję po przepisaniu opisu bez tygodnia etykietowania, a slackową i asanową konfigurację z cookbooka czytamy jako dowód, że tak mały zestaw jest zamierzonym punktem startu, a nie skrótem. Głębsza mechanika czeka w naszym przewodniku po ewaluacji agentów AI na produkcji, a jeśli wyniki ewaluacji mówią, że same narzędzia są w porządku, ale orkiestracja już nie, to jest moment, by ponownie przemyśleć wybór frameworku w świetle najlepszych frameworków agentów AI.

Wywoływanie narzędzi przez agenta a MCP: jaka jest różnica?

MCP to standard transportu i rejestru, nie warstwa niezawodności, więc te same osiem praktyk obowiązuje niezależnie od tego, czy narzędzia docierają przez MCP, czy są zdefiniowane inline. Natywne wywoływanie narzędzi to kontrakt z dostawcą modelu: jak model emituje tool_call i czyta tool_result. MCP standaryzuje, jak narzędzia docierają do modelu; nie robi niczego w kwestii tego, czy model wybierze właściwe.

Serwer MCP wystawiający narzędzie o nazwie search z opisem "searches things" zawodzi identycznie jak funkcja inline zdefiniowana tak samo. Najpierw napraw definicję, potem martw się o transport. Nasz przewodnik po Model Context Protocol pokrywa stronę protokołu od początku do końca.

Jak Techsy stosuje tych osiem praktyk

Przy każdym projekcie agenta dla klienta wymuszamy trzy z nich, zanim cokolwiek innego trafi na produkcję: opisy pisane jako instrukcje (praktyka 1), bramki walidacji na każdym narzędziu do zapisu (praktyka 6) i zestaw ewaluacyjny uruchamiany przed wdrożeniem, a nie po incydencie (praktyka 8). Te trzy pokrywają błędne wywołania narzędzi, błędne wywołania argumentów i regresje, które przywracają jedno i drugie, a tam zaczynał się każdy incydent produkcyjny agenta, który debugowaliśmy. Pozostałe pięć praktyk dochodzi w miarę wzrostu agenta. Jeśli Twój agent wyszedł poza etap demo i wybiera złe narzędzia, umów się na bezpłatną konsultację, a powiemy Ci, którą z ośmiu praktyk naprawić najpierw.

O autorze

Mert Batur jest współzałożycielem Techsy.io, gdzie zespół wdraża agentów AI, systemy automatyzacji i pipeline'y głosowe/SDR dla klientów B2B. Pisze o stosie narzędzi LLM, którego zespół Techsy naprawdę używa na produkcji. Połącz się na LinkedIn.

Często zadawane pytania

Czym jest wywoływanie narzędzi przez agenta?

Wywoływanie narzędzi przez agenta to mechanizm, w którym LLM decyduje się wywołać zewnętrzną funkcję, emituje ustrukturyzowany tool_call i czeka, aż Twój kod zwróci tool_result, na którym może dalej rozumować. To właśnie zamienia model czatowy w agenta, który potrafi odpytywać bazy danych, wywoływać API i podejmować działania: model wybiera narzędzie i argumenty, a Twój egzekutor je uruchamia.

Jak działa pętla wywoływania narzędzi przez agenta?

Pętla ma pięć kroków: żądanie użytkownika trafia do modelu, model wybiera narzędzie i zapisuje tool_call, Twój egzekutor je uruchamia, tool_result wraca do modelu, a model albo odpowiada, albo wystawia kolejne wywołanie. Ten cykl powtarza się, aż zadanie zostanie ukończone. Cztery tryby awarii z tego przewodnika siedzą każdy w konkretnym kroku tej pętli.

Dlaczego mój agent wybiera złe narzędzie?

Zwykle dlatego, że dwa narzędzia się nakładają, a ich opisy nie mówią, które jest które. Model wybiera wyłącznie na podstawie nazw i opisów, więc "gets a user" kontra "finds users" czyta się jak zamienniki. Napraw to liniami wykluczeń ("nie używaj do wyszukiwania"), nazwami z przestrzeniami nazw i mniejszą liczbą narzędzi w kontekście. Test Kubaskiego na czterech modelach pokazał, że nawet silne modele źle routują na niejednoznacznych listach.

Jak zmusić agenta tool calling do strukturyzowania danych wyjściowych?

Ograniczaj schemat, nie prompt. Używaj enumów dla pól o ograniczonym zbiorze, tablic required dla wszystkiego, czego potrzebuje zadanie, i płaskich obiektów zamiast zagnieżdżonych. Dla odpowiedzi końcowej, a nie wywołania narzędzia, funkcje dostawców, takie jak structured outputs OpenAI i tryby tool-choice Anthropic, wymuszają konkretny kształt. Nasz przewodnik po structured outputs pokrywa obie ścieżki z kodem.

Wywoływanie narzędzi przez agenta a MCP: jaka jest różnica?

Natywne wywoływanie narzędzi to kontrakt między Twoim kodem a jednym dostawcą modelu: format komunikatów tool_call i tool_result. MCP to warstwa protokołu, która standaryzuje, jak narzędzia są wykrywane i dostarczane do dowolnego kompatybilnego klienta. MCP zmienia hydraulikę, nie niezawodność. Źle opisane narzędzie zawodzi tak samo obiema ścieżkami, co wyjaśnia nasz przewodnik po Model Context Protocol.

Ile narzędzi to za dużo dla agenta LLM?

Traktuj 5-10 narzędzi na agenta jako zakres roboczy, nie prawo. Trafność wyboru spada wraz ze wzrostem widocznej listy, szczególnie gdy nazwy lub opisy się nakładają. Lekarstwem nie jest większy model, tylko filtrowanie: ładuj wyłącznie podzbiór potrzebny bieżącemu zadaniu, używając podziału planista-pracownik. Nadawaj przestrzenie nazw wszystkiemu, żeby dwie integracje nigdy nie wystawiały jednocześnie gołego search.

Jaki model jest najlepszy do tool callingu?

Nie ma jednej odpowiedzi, a publikowane benchmarki szybko się starzeją w tej dziedzinie. Frontowe modele OpenAI, Anthropic i Google wszystkie przechodzą podstawowe zadania tool use, podczas gdy mniejsze modele sparowane z dobrze zaprojektowanymi narzędziami często kończą zadania niemal równie często za ułamek kosztu tokenów. Zbuduj zestaw ewaluacyjny 15-30 zadań z praktyki 8 i testuj kandydatów na własnych narzędziach.

Jak obniżyć koszt tokenów z tool callingu?

Przytnij to, co wraca. Zwracaj zwięzłe wyniki o wysokiej wartości sygnału zamiast surowych payloadów API: Anthropic udokumentował cięcie z 206 do 72 tokenów po jednej zmianie response_format. Rozwiązuj UUID-y do nazw, wyrzucaj pola, których model nigdy nie używa, i pamiętaj, że każdy wynik narzędzia ponownie wchodzi do okna kontekstu w każdej kolejnej turze. Mniej wywołań, dzięki atomowym narzędziom, usuwa całe wyniki z rachunku.

Jak oceniać jakość tool callingu?

Punktuj cztery metryki w kolejności: poprawność narzędzia (właściwe narzędzie?), trafność danych wejściowych (poprawne argumenty?), ukończenie zadania (cel osiągnięty?) i wydajność zadania (liczba tokenów i wywołań?). Napisz 15-30 zadań, każde oczekujące jednego konkretnego wywołania ze sprawdzalnymi argumentami i binarnym warunkiem zaliczenia. Uruchamiaj zestaw przed i po każdej zmianie narzędzia, żeby przepisanie opisu nigdy nie trafiło na produkcję bez pomiaru.

Podsumowanie

Najpierw diagnozuj, potem optymalizuj. Twój agent wybiera złe narzędzie z jednego z czterech powodów, a trzy z ośmiu praktyk powyżej, opisy, płaskie schematy i filtrowanie, naprawiają awarie wyboru, które napędzają większość incydentów produkcyjnych. Zacznij od nich, bo kosztują jedno popołudnie i to dzięki nim ten problem w ogóle da się naprawić. Trzymaj błędy walidacji informacyjne, bramkuj wszystko, co destrukcyjne, za potwierdzeniem człowieka i uruchamiaj pętlę ewaluacji przy każdej zmianie, żeby mierzyć, zanim zmienisz model. Problem złego narzędzia to nie jest problem modelu. To problem projektowania narzędzi, a projekt należy do Ciebie.