Procedura

Kontrakt narzędzi (Function Calling)

Narzędzie dla chatbota to nie „endpoint” — to kontrakt wykonawczy. Model jest tylko klientem tego kontraktu, a nie jego autorem. Ta procedura opisuje podejście contract‑first: schemat, walidacje, uprawnienia, niezawodność, błędy i rollout.

Czas czytania: ~18 min Rodzina: Wdrożenie i governance Zastosowanie: integracje i automatyzacje Aktualizacja: 5 stycznia 2026
Kryteria gotowości
  • Wejście/wyjście da się opisać schematem (bez „magii”).
  • Każde wywołanie ma politykę: kto, kiedy i w jakim trybie.
  • Obsługa błędów jest jawna i stabilna (taksonomia).
  • Narzędzie jest obserwowalne: trace, logi, audyt, metryki.
  • Nie ma sekretów w promptach; uprawnienia są delegowane.
Ważne: traktuj argumenty generowane przez model jak untrusted input. To nie jest „źródło prawdy”, tylko propozycja do weryfikacji.

1. Cel i definicje

W praktyce „function calling” sprowadza się do tego, że model w pewnym momencie generuje strukturę danych (najczęściej JSON), która ma zostać użyta do uruchomienia konkretnego narzędzia. To system decyduje, czy i jak tę strukturę wykonać.

Narzędzie
Funkcja o jasno zdefiniowanym celu, schemacie i ograniczeniach.
Wywołanie narzędzia
Propozycja (args) + kontekst wykonawczy (user, scope, tryb, trace).
Kontrakt
Schemat wejścia/wyjścia + reguły błędów + polityki + gwarancje.

2. Obraz całości: contract‑first

Kontrakt narzędzi: schemat → walidacja → wykonanie → wynik + audyt
Contract‑first redukuje „zaskoczenia”: model proponuje, system wykonuje zgodnie z kontraktem.

3. Krok 0 — granice narzędzia

Zanim zapiszesz schemat, doprecyzuj granice. Dobre narzędzie ma jasne „tak” i równie jasne „nie”. W przeciwnym razie model będzie próbował „rozsądnie dopowiedzieć” brakujące reguły.

  • Cel: co narzędzie robi (jedno zdanie, bez złożonych alternatyw).
  • Zakres: jakie zasoby może dotknąć (np. projekt, tenant, przestrzeń).
  • Zakazy: czego narzędzie nigdy nie robi (np. usuwanie, masowe operacje).
  • Tryb: suggest/execute/approve; kiedy wymagane jest potwierdzenie.
  • Odpowiedzialność: kto jest właścicielem biznesowym i technicznym.

4. Krok 1 — schemat wejścia i wyjścia

Schemat powinien być ciasny: typy, długości, dozwolone wartości, formaty dat, wzorce. Im więcej „wolnej” tekstowej przestrzeni, tym więcej ryzyka. 

{
  "name": "create_ticket",
  "description": "Utwórz zgłoszenie helpdesk w imieniu użytkownika.",
  "parameters": {
    "type": "object",
    "additionalProperties": false,
    "required": ["title", "description", "priority"],
    "properties": {
      "title": { "type": "string", "minLength": 8, "maxLength": 120 },
      "description": { "type": "string", "minLength": 20, "maxLength": 2000 },
      "priority": { "type": "string", "enum": ["low", "normal", "high"] },
      "labels": {
        "type": "array",
        "items": { "type": "string", "maxLength": 24 },
        "maxItems": 8
      }
    }
  }
}
Antywzorzec: „description: string” bez limitów i bez additionalProperties: false. To prosta droga do argumentów „wymyślonych”, nieprzetestowanych i niebezpiecznych.

5. Krok 2 — walidacja, normalizacja, odmowa

Walidacja nie kończy się na schemacie. W praktyce potrzebujesz również normalizacji (np. daty, identyfikatory), mapowania aliasów i jawnych odmów w sytuacjach niejednoznacznych.

WarstwaCo robiEfekt uboczny
Schema Typy, wymagane pola, enumy, limity. Wczesna blokada przypadkowych argumentów.
Normalizacja Ujednolica formaty (daty, waluty, identyfikatory). Mniej „wariantów” w logach i testach.
Reguły biznesowe Sprawdza kontekst (np. user ma prawo tworzyć ticket w tym projekcie). Odmowa z powodem, a nie „błąd 500”.

6. Krok 3 — uprawnienia i bezpieczeństwo

Narzędzie powinno działać w imieniu użytkownika (delegacja) albo w jasno ograniczonym serwisowym zakresie. Sekrety i tokeny nie mogą „przeciekać” do promptu. To domena warstwy wykonawczej.

Praktyka: rozdziel „to, co model widzi” od „to, co system może wykonać”. Model może poprosić o wykonanie, ale nie ma dostępu do sekretów, a bramka (Tool Gateway) egzekwuje politykę.

7. Krok 4 — niezawodność wykonania

  • Timeout: każde wywołanie ma budżet czasu; brak odpowiedzi to kontrolowany błąd.
  • Retry: tylko dla operacji idempotentnych; w innych przypadkach — resume.
  • Idempotency key: wymagany dla akcji, które mogą się powtórzyć (np. „create”).
  • Paginacja: nie „ściągaj wszystkiego”; preferuj strony i limity.
// Przykładowe metadane wykonawcze (systemowe, nie w promptach)
{
  "tool": "create_ticket",
  "tool_call_id": "tc_01H...",
  "trace_id": "tr_7f3a...",
  "actor": { "user_id": "u_123", "roles": ["employee"] },
  "mode": "approve",
  "idempotency_key": "idem_2026-01-05_u123_create_ticket_9b8f"
}

8. Krok 5 — taksonomia błędów

Model nie powinien „zgadywać”, co poszło nie tak. Zwracaj błędy w formie, którą model może obsłużyć: kod + krótki opis + (opcjonalnie) pole, którego dotyczy problem. 

{
  "ok": false,
  "error": {
    "code": "POLICY_DENIED",
    "message": "Operacja wymaga trybu approve.",
    "hint": "Poproś użytkownika o potwierdzenie i ponów wywołanie w trybie approve."
  }
}

9. Krok 6 — obserwowalność i audyt

Bez śladu wykonawczego nie ma odpowiedzialności. Minimalny standard: trace_id, tool_call_id, arg hash, wynik (skrócony), czas, polityka, użytkownik. Dodatkowo: redakcja PII w logach.

Uwaga: logi narzędzi szybko stają się „magazynem danych”. Jeżeli nie macie reguł retencji i redakcji — zaczniecie gromadzić dane, których nie chcieliście.

10. Krok 7 — testy i regresje

  • Zestaw złoty: kilkanaście reprezentatywnych wywołań + oczekiwane odpowiedzi.
  • Testy graniczne: długości, enumy, brak pól, niepoprawne formaty.
  • Symulacja: dry‑run w bramce (bez dotykania produkcji).
  • Testy bezpieczeństwa: injection do argumentów, próby exfiltracji, „prompt hijacking”.

11. Krok 8 — rollout

Nowe narzędzie wdrażaj jak funkcję produktu: feature flag, canary, metryki błędów, obserwowalność kosztu i czasu. Jeśli w 48 godzin nie potraficie powiedzieć, jak działa — to znaczy, że nie działa.

12. Powiązane

Szablon kontraktu (skrót)
  1. Nazwa, opis, zakres i zakazy.
  2. Schemat args + additionalProperties=false.
  3. Schemat odpowiedzi: ok, dane, błąd.
  4. Polityka: tryb (suggest/execute/approve) + uprawnienia.
  5. Idempotency + timeouts + retry.
  6. Logi: trace/tool_call_id + redakcja danych.
Powiązane wzorce

Jeśli budujesz narzędzia, potrzebujesz również bramki wykonawczej.

Przejdź do Tool Gateway