Wzorzec

Tool Gateway

Tool Gateway to bramka narzędziowa, która stoi pomiędzy modelem a systemami produkcyjnymi. Jej rola jest prosta: traktować wyjście modelu jak niezaufane wejście i wykonać działanie dopiero po walidacji, autoryzacji, ograniczeniach oraz pełnym logowaniu.

Czas czytania: ~16 min Rodzina: Bezpieczeństwo i ryzyko Zastosowanie: chatboty narzędziowe Aktualizacja: 5 stycznia 2026
W skrócie
  • Model nie wykonuje akcji bez warstwy kontroli (allowlist, RBAC, limity).
  • Kontrakt narzędzia jest walidowany (schemat wejścia/wyjścia, typy, zakresy).
  • Dane wrażliwe są redagowane przed wywołaniem i przed zapisaniem logów (DLP/PII).
  • Każde wywołanie ma ślad audytowy: kto, kiedy, dlaczego, jakie parametry i jaki wynik.
Sygnały, że bramki brakuje
  • „Niewinne” funkcje zaczynają wykonywać operacje o skutkach ubocznych.
  • Brak spójnych błędów: raz timeout, raz „nie wyszło”, raz cisza.
  • Nie da się odpowiedzieć na pytanie: kto uruchomił akcję i na jakiej podstawie.

1. Definicja i zakres

W systemach narzędziowych (tool-using chatbots) model potrafi generować nie tylko tekst, ale również intencje wywołań: wyszukaj, policz, pobierz rekord, utwórz zgłoszenie, zaktualizuj status. To nie jest problem — problemem jest sytuacja, w której takie intencje są wykonywane bez kontroli.

Zasada bezpieczeństwa: wyjście modelu jest niezaufane. Nawet jeśli brzmi wiarygodnie, musi przejść przez te same bramki, co dowolne dane wejściowe z internetu.

Tool Gateway jest więc wzorcem architektonicznym: to usługa (lub moduł), która przyjmuje propozycję wywołania, sprawdza ją względem polityk i kontraktu, a następnie dopiero uruchamia narzędzie.

2. Minimalna architektura

Diagram Tool Gateway
Wzorzec: model rozmawia, ale akcje wykonuje bramka. W praktyce to różnica między „asystentem” a „systemem produkcyjnym”.

Architektura minimalna ma trzy obowiązkowe elementy:

(A) Kontrakt narzędzi
Schemat wejścia i wyjścia; jawne pola; jawne błędy; brak „domyślnych domysłów”.
(B) Polityka wykonania
Allowlist narzędzi, RBAC, limity, tryby: suggest/execute/approve.
(C) Ślad audytowy
Logi oraz korelacja: kto uruchomił, jaki kontekst, jaki wynik, jakie wrażliwe dane zostały zamaskowane.

3. Warstwy kontroli w Tool Gateway

Warstwa Co robi Co chroni
Allowlist narzędzi Model może wywołać wyłącznie jawnie zarejestrowane funkcje. Przed „wymyślonymi” narzędziami i eskalacją na nieautoryzowane akcje.
Walidacja schematu Sprawdza typy, zakresy, wymagane pola, formaty (np. daty, ID). Przed wstrzyknięciem danych, błędami wykonania, niejawnością parametrów.
RBAC / uprawnienia Sprawdza, czy użytkownik (a nie „model”) ma prawo do operacji. Przed wykonaniem akcji w cudzym imieniu i „przeskokiem” poziomów dostępu.
DLP / redakcja Maskuje PII/secrets w parametrach i logach; minimalizuje payload. Przed wyciekiem danych (w narzędziach, logach, cache, w odpowiedzi).
Idempotency & limity Zapobiega wielokrotnemu wykonaniu; narzuca limity i timeouty. Przed „lawiną” akcji na retrach, kosztami i skutkami ubocznymi.
Audit log Zapisuje: kto, kiedy, jakie narzędzie, parametry (po redakcji), wynik, błędy. Przed brakiem odpowiedzialności i brakiem możliwości odtworzenia zdarzeń.
Uwaga praktyczna: „walidacja schematu” nie jest kosmetyką. To mechanizm, który ogranicza model do obszaru, który potraficie utrzymać i audytować.

4. Tryby wykonania: Suggest, Execute, Approve

Najprostsza forma kontroli to rozróżnienie:

  • Suggest — model proponuje akcję (np. „utwórz ticket”), ale system jej nie wykonuje.
  • Execute — system wykonuje akcję automatycznie, jeśli spełnione są warunki (policy).
  • Approve — akcje wysokiego ryzyka prze让zą przez człowieka (human-in-the-loop).
Dobra praktyka: zacznijcie od trybu Suggest i dopiero po stabilizacji kontraktu przechodźcie na Execute. W praktyce to najtańszy test bezpieczeństwa.

5. Bezpieczeństwo: prompt injection i exfiltracja

Tool Gateway nie zastępuje higieny promptów, ale znacząco zmniejsza wpływ prompt injection, ponieważ akcje i tak muszą przejść przez politykę. Kluczowe reguły:

  1. Separacja tajemnic: tokeny i klucze API nie mogą być elementem promptu. Są po stronie bramki.
  2. Least privilege: narzędzia działają na uprawnieniach użytkownika lub ściśle ograniczonej roli serwisowej.
  3. Blokada „free-form”: parametry narzędzi nie mogą być dowolnym tekstem bez walidacji.
  4. Ograniczenia domeny: wyszukiwanie, scraping, e-mail — zawsze z allowlistą i kontrolą URL/domen.
// Przykład: minimalny zapis zdarzenia wywołania narzędzia (po stronie bramki)
{
  "trace_id": "01HR...",
  "actor": { "user_id": "u_123", "tenant": "acme" },
  "tool": "crm.search_customer",
  "mode": "execute",
  "args_redacted": { "email": "***@***.com", "limit": 5 },
  "decision": { "allowed": true, "policy": "crm.readonly.v2" },
  "result_meta": { "records": 2, "latency_ms": 143 },
  "error": null,
  "timestamp": "2026-01-05T11:20:04Z"
}

6. Obserwowalność i audyt

Bez obserwowalności narzędzia działają „na wiarę”, a to w systemach językowych jest zaproszeniem do chaosu. Minimalny zestaw metryk i logów:

  • Tool call rate (na użytkownika, na narzędzie, na tenant).
  • Latency i rozkład timeoutów (P50/P95/P99).
  • Rate limit hits (czy bramka „gasi pożary” czy narzędzia są źle zaprojektowane).
  • Error taxonomy: walidacja / autoryzacja / błąd narzędzia / błąd integracji.
  • Replay capability: możliwość odtworzenia wywołania na danych z logów (po redakcji).
Najczęstszy błąd: logowanie „pełnych” parametrów, a dopiero potem myślenie o prywatności. W bramce obowiązuje odwrotnie: najpierw redakcja, potem zapis.

7. Checklist wdrożeniowy Tool Gateway

Kontrakt
  • Wejście opisane schematem.
  • Wyjście w formacie deterministycznym.
  • Jawna taksonomia błędów.
Polityka
  • Allowlist narzędzi i metod.
  • RBAC w kontekście użytkownika.
  • Tryb approve dla high-risk.
Operacje
  • Timeouty i retry z idempotency.
  • Logi po redakcji + trace_id.
  • Monitoring i alerty.

8. Powiązane

Reguła wykonawcza

Jeśli nie potraficie opisać narzędzia schematem i polityką, to nie jest to narzędzie gotowe dla chatbota. To jest „ręczny skrót” przebrany za automatyzację.

Następny krok

Jeśli Tool Gateway jest „bramką”, to kontrakt narzędzi jest jej „prawem”.

Przejdź do kontraktu narzędzi