Kontrakt narzędzia dla agenta AI

Kontrakt narzędzia dla agenta AI, po angielsku tool contract, opisuje dokładnie, jak model może wywołać funkcję lub API oraz czego może oczekiwać w odpowiedzi. Składa się zwykle z nazwy, krótkiego opisu przeznaczenia, schematu wejścia, reguł walidacji, opisu wyniku i zachowania przy błędzie. W praktyce jest to umowa między trzema stronami: modelem, który wybiera narzędzie, aplikacją, która wykonuje wywołanie, i zewnętrznym systemem, takim jak CRM, kalendarz czy baza wiedzy. Model może zaproponować wywołanie, ale nie powinien sam decydować, że dowolny tekst jest poprawnym numerem klienta, kwotą lub adresem odbiorcy.

To pojęcie jest szersze niż function calling. Function calling opisuje mechanizm, w którym model zwraca ustrukturyzowaną prośbę o uruchomienie funkcji. Kontrakt narzędzia odpowiada na pytanie, czy ta funkcja została zaprojektowana tak, aby prośba była możliwa do zrozumienia, zweryfikowania i bezpiecznego wykonania. Model ma dostać mało narzędzi o wyraźnie różnych celach, a każde musi mówić prostym językiem, co robi i czego nie robi. Niejasne nazwy typu processData lub updateRecord prowokują błędny wybór, bo model nie zna intencji ukrytej w kodzie.

Dobrze zaprojektowany input schema precyzuje typy, wymagane pola, dopuszczalne wartości i format. Dla narzędzia tworzącego follow-up warto rozdzielić przygotowanie szkicu od wysyłki: create_follow_up_draft może wymagać identyfikatora kontaktu i celu wiadomości, a send_follow_up powinno wymagać identyfikatora zatwierdzonego szkicu oraz jawnej akceptacji człowieka. Nie przyjmuj wolnego pola tekstowego tam, gdzie system oczekuje daty, identyfikatora lub jednej z kilku statusów. Schemat pomaga modelowi, lecz serwer i tak musi ponownie walidować dane. Opis narzędzia nie jest kontrolą dostępu.

Równie ważny jest kontrakt wyniku. Zamiast zwracać modelowi komunikat „ok”, zwróć ustrukturyzowany rezultat: status, identyfikator utworzonego rekordu, czy akcja wymaga akceptacji oraz bezpieczny komunikat dla użytkownika. Gdy wywołanie nie przejdzie, błąd powinien wyjaśniać, co da się poprawić, na przykład „brakuje identyfikatora kontaktu” albo „data musi być w przyszłości”. Nie zwracaj sekretów, pełnych odpowiedzi z prywatnego API ani nieufnego HTML. Wynik narzędzia staje się częścią kontekstu modelu, więc może zostać wykorzystany w kolejnej decyzji.

Przykład dla soloprzedsiębiorcy: agent ma pomóc po rozmowie sprzedażowej. Zamiast jednego narzędzia „obsłuż leada”, udostępnij trzy. find_contact wyszukuje kontakt według maila. create_crm_note zapisuje podsumowanie wyłącznie przy prawidłowym identyfikatorze kontaktu. create_follow_up_draft tworzy szkic, ale nie wysyła go. Każde narzędzie ma osobny schemat oraz minimalne uprawnienia. Agent może pokazać szkic człowiekowi, a dopiero odrębna, zatwierdzona akcja wykonuje wysyłkę. Taki podział ogranicza skutki złej interpretacji i ułatwia znalezienie miejsca błędu w logach.

Kontrakt powinien określać granice bezpieczeństwa. Zasada najmniejszych uprawnień oznacza, że narzędzie ma dostęp tylko do danych i akcji koniecznych dla danego zadania. Operacje z nieodwracalnym skutkiem, takie jak wysłanie wiadomości, zmiana ceny, usunięcie rekordu lub przekazanie danych na zewnątrz, wymagają dodatkowej kontroli i zwykle potwierdzenia człowieka. Specyfikacja MCP zaleca walidację wejść, kontrolę dostępu, limity wywołań, sanityzację wyników i prezentowanie potwierdzeń dla wrażliwych operacji. To obowiązuje niezależnie od tego, czy agent korzysta z MCP, OpenAI czy własnego endpointu.

Najczęstszy błąd to traktowanie schematu jako instrukcji dla modelu, a nie jako kontraktu egzekwowanego przez kod. Model może źle odczytać opis, użytkownik może podać niepoprawne dane, a treść z narzędzia może zawierać prompt injection. Drugi błąd to zbyt szerokie narzędzie, które jednocześnie czyta, zmienia i wysyła dane. Trzeci to brak wersji kontraktu. Zmiana nazwy pola lub znaczenia statusu bez wersjonowania potrafi zepsuć działający workflow i utrudnia audyt. Zmiany traktuj jak zmianę API: testuj na reprezentatywnych przypadkach, zapisuj wersję i wdrażaj z możliwością cofnięcia.

Od czego zacząć? Wybierz jedną akcję o małym ryzyku, na przykład pobranie danych projektu lub utworzenie szkicu notatki. Napisz nazwę w formie czasownika i rzeczownika, dopisz jedno zdanie „kiedy używać”, zdefiniuj wymagane parametry oraz konkretny wynik. Następnie sprawdź pięć przypadków: poprawne dane, brak wymaganego pola, zły format, brak uprawnień i awaria usługi. Dopiero potem dodaj akcję zmieniającą dane. Połącz kontrakt z testami i rejestrem audytowym, aby po błędzie zobaczyć, którą wersję narzędzia agent wywołał i z jakimi parametrami.