1. Warstwa 1 — Klucz API o ograniczonym zakresie
Klucz jest pierwszą bramką. Zanim jakakolwiek treść zostanie sprawdzona lub jakikolwiek model wywołany, brama rozwiązuje wywołujący klucz i decyduje, czy żądanie jest w ogóle dozwolone. Co klucz ze sobą niesie:model_limits— zestaw modeli, które klucz może wywoływać. Żądanie dla modelu spoza listy jest natychmiast odrzucane.allow_ips— opcjonalna lista dozwolonych IP. Żądanie z niezapisanego źródła jest odrzucane.credit_limit_usd— twardy limit wydatków. Żądanie, które przekroczyłoby limit klucza, jest odrzucane.expiry— twardy termin ważności. Wygasłe klucze są odrzucane.environment— znacznik (production,staging,dev, …) do organizowania i identyfikowania klucza według środowiska wdrożenia.guardrail_id— polityka guardrail powiązana z tym kluczem (patrz Warstwa 2 i Warstwa 4).firewall_policy_id— polityka firewalla powiązana z tym kluczem (patrz Warstwa 3).is_firewall_gateway— flaga klucza jako tokenu o zakresie firewall-gateway; wymagana dla tras evaluate i bramy MCP.
is_firewall_gateway i odczyt plaintext klucza
wymagają Admin.
Pełny model kluczy znajdziesz w
Zakres, klucze, polityki i przestrzenie robocze.
2. Warstwa 2 — Guardrails wejściowe
Po walidacji klucza brama uruchamia reguły etapu wejściowego powiązanego guardrail wobec tekstu żądania — przed jakimkolwiek wywołaniem modelu nadrzędnego. Co widzi: Wiadomości wywołującego tak jak zostały przesłane. (Prompt wstrzyknięty z rejestru promptów jest dołączany później, na etapie routingu; reguły wejściowe go nie widzą.) Dostępne typy reguł:keyword, regex, pii, max_chars, external,
llm_judge, grounding.
Akcje, które reguła może wyprodukować:
| Akcja | Co się dzieje |
|---|---|
block | Żądanie jest odrzucane — HTTP 400 guardrail_blocked. Żaden limit nie jest naliczany. Oznaczone skip-retry. |
mask | Dopasowanie jest redagowane (np. jane@acme.com → [EMAIL]). Oczyszczony tekst kontynuuje do modelu. |
flag | Dopasowanie jest rejestrowane; ruch jest niezmieniony. |
block na tym etapie oznacza, że model nigdy nie jest wywoływany. Koszt: zero.
Wywołujący widzi ustrukturyzowany błąd nazywający guardrail i regułę, która
odpaliła.
Gdzie konfigurować: Konsola → Guardrails lub guardrail API. Wymaga
Developer+ do tworzenia lub modyfikacji. Zobacz
Guardrails dla pełnej referencji reguł.
3. Warstwa 3 — Model uruchamia się
Jeśli klucz jest ważny i guardrails wejściowe przeszły, brama przekazuje żądanie do modelu nadrzędnego. To jest jedyna warstwa bez konfigurowalnego egzekwowania — model po prostu wykonuje swoje zadanie. Firewall działa na akcjach, które model produkuje (Warstwa 3 → Warstwa 4 poniżej), nie na samym modelu. Routing, fallbacki i równoważenie obciążenia odbywają się tu transparentnie.4. Warstwa 4 — Agent Firewall (wywołania narzędzi i egress)
Po odpowiedzi modelu — lub inline, gdy emitowane są wywołania narzędzi — Agent Firewall ocenia każdą akcję, o którą model prosi. Cztery powierzchnie egzekwowania:| Powierzchnia | Co firewall widzi |
|---|---|
inbound | Definicje narzędzi, które agent ogłasza modelowi. Zablokuj niebezpieczne narzędzie, zanim model będzie mógł je wybrać. |
response | tool_calls, które model emituje w swojej odpowiedzi. |
mcp | tools/call dyspozytowane przez bramę Firewall MCP lub ewaluowane przez hook. |
egress | Wychodzący cel sieciowy (host / IP / CIDR) zgłoszony przez narzędzie — powierzchnia SSRF i eksfiltracji danych. |
| Werdykt | Co robi |
|---|---|
allow | Wywołanie kontynuuje. Zalogowane. |
audit | Wywołanie kontynuuje; zapisane do przeglądu. Domyślny default_verdict. |
deny | Wywołanie zablokowane — HTTP 400 firewall_blocked na powierzchni inbound; błąd narzędzia na mcp. |
sanitize | Dopasowane podłańcuchy są redagowane z argumentów narzędzia; oczyszczone wywołanie kontynuuje. Na inbound (brak jeszcze argumentów), eskaluje do deny. |
pending_approval | Wywołanie jest wstrzymane; zewnętrzny recenzent zatwierdza lub odrzuca; agent ponownie przesyła z jednorazowym tokenem zatwierdzenia. |
cap_cost | Odmów, gdy zakumulowane wydatki uruchomienia agenta przekroczą limit w centach per reguła. |
deny na powierzchni inbound nie kosztuje tokenów modelu — blokada odpala
przed wywołaniem nadrzędnym. Wstrzymanie pending_approval zwraca HTTP 400
firewall_approval_pending z id zatwierdzenia, na którym odpytuje klient.
Gdzie konfigurować: Konsola → Firewall lub firewall API. Wymaga
Developer+ do tworzenia lub modyfikacji polityk i reguł. Zobacz
Firewall i Reguły firewalla
dla pełnego języka reguł.
5. Warstwa 5 — Guardrails wyjściowe
Po odpowiedzi modelu (i po zakończeniu dowolnego cyklu wywołań narzędzi) brama uruchamia reguły etapu wyjściowego powiązanego guardrail wobec tekstu odpowiedzi, zanim dotrze do wywołującego. Te same typy reguł i akcje mają zastosowanie jak w Warstwie 2. Wyjściowyblock zwraca HTTP 400 guardrail_blocked i zwraca wstępnie pobraną
porcję — wywołujący nic nie płaci.
Streaming i maskowanie wyjścia. Akcja
block jest egzekwowana zarówno
na odpowiedziach strumieniowych, jak i niestrumieniowych — na strumieniu
skaner przerywa go w locie i emituje zamiennik. Akcja mask na wyjściu
obecnie ma zastosowanie tylko do odpowiedzi niestrumieniowych; na
odpowiedzi strumieniowej oryginalny chunk przechodzi bez maskowania.
Sprawdź swoją kombinację etap/stream w piaskownicy guardrail przed
poleganiem na tym.6. Warstwa 6 — Audyt
Każde dopasowanie, werdykt i decyzja o zatwierdzeniu jest zapisywana do śladu audytu, korelowana z uruchomieniem agenta i sesją, które ją spowodowały. To nie jest oddzielny krok egzekwowania — działa równolegle z Warstwami 2–5 — ale jest warstwą, która czyni inne odpowiedzialnymi. Co jest logowane:- Dopasowania guardrail: typ reguły, akcja, etap, łańcuch szczegółów i (jeśli Log raw content jest włączony) dopasowany podłańcuch.
- Zdarzenia firewalla: powierzchnia, nazwa narzędzia, werdykt, dopasowana reguła, kod powodu, czynniki ryzyka i uruchomienie/sesja, do której należy wywołanie.
- Decyzje o zatwierdzeniu: kto zatwierdził lub odrzucił, kiedy i czy podstawowa reguła zmieniła się między wstrzymaniem a decyzją.
- Zmiany polityk: każde tworzenie, aktualizacja, usunięcie i zmiana poziomu autonomii zapisuje wersjonowany wiersz audytu.
7. Tabela podsumowująca
| Warstwa | Co kontroluje | Co widzi | Wynik przy trafieniu | Gdzie konfigurować |
|---|---|---|---|---|
| 1. Klucz o zakresie | Tożsamość, dostęp do modelu, wydatki, IP, wygaśnięcie | Token auth żądania | HTTP 4xx przed czymkolwiek; bez pomiaru | Konsola → API Keys (Developer+) |
| 2. Guardrails wejściowe | Treść tekstu żądania | Wiadomości wywołującego | Block (HTTP 400 guardrail_blocked, bez opłaty), mask lub flag | Konsola → Guardrails (Developer+) |
| 3. Model | — | — | — | Routing / konfiguracja kanału |
| 4. Agent Firewall | Wywołania narzędzi, dyspozycja MCP, egress | Nazwa narzędzia, argumenty, cel | allow / audit / deny / sanitize / pending_approval / cap_cost | Konsola → Firewall (Developer+) |
| 5. Guardrails wyjściowe | Treść tekstu odpowiedzi | Odpowiedź modelu | Block (HTTP 400, limit zwrócony), mask lub flag | Konsola → Guardrails (Developer+) |
| 6. Audyt | Atrybuowanie i ślad | Wszystkie powyższe | Niezmienny wpis logu | Konsola → Matches (Member) / Events & Runs (Developer+) |
8. Kolejność rozwiązywania polityk
Dla każdego żądania aktywny guardrail i polityka firewalla są rozwiązywane niezależnie:- Dołączenie klucza — jeśli klucz niesie jawne
guardrail_idlubfirewall_policy_id, ta polityka wiąże (gdy istnieje i jest włączona). - Domyślny przestrzeni roboczej — jeśli klucz nie ma dołączenia,
stosuje się włączony guardrail lub polityka
is_defaultprzestrzeni roboczej. - Żadne — brak egzekwowania. Żądanie jest bajt-identyczne z przestrzenią roboczą, która nigdy nie włączyła tej funkcji.
9. Fail-open i fail-closed
Dwa zachowania — stosowane do różnych przypadków.Fail-open (błędy przejściowe): Jeśli rozwiązywanie polityki trafi na
błąd przejściowy — czkawkę bazy danych, chwilowy problem sieciowy na drodze
do zewnętrznego dostawcy — brama degraduje się do braku egzekwowania
zamiast wyłączać ruch. Bezpieczeństwo się degraduje; dostępność jest
zachowana. Skonfiguruj
fail_open: false na regułach external lub
llm_judge, gdy pominięte sprawdzenie jest nieakceptowalne dla twojej
polityki.Fail-closed (niejednoznaczne przypadki): Tam gdzie brak egzekwowania
zniweczyłby regułę, silnik fail closed: raport egress z nierozwiązywalnym
celem jest odmówiony; nieosiągalny magazyn zatwierdzeń wstrzymuje wywołanie
zamiast przepuszczać je; skill, którego własności nie da się rozwiązać, jest
blokowany. Dostępność jest zachowana na szczęśliwej ścieżce; bezpieczeństwo
nie jest po cichu pomijane w przypadkach, które mają znaczenie.10. Dogłębne analizy
Guardrails
Pełna referencja reguł — typy, akcje, encje PII, sędzia LLM, ugruntowanie
i piaskownica testowa.
Firewall
Model polityk, werdykty, powierzchnie, tryb cienia, zatwierdzenie HITL
i wykrywanie anomalii.
Reguły firewalla
Język dopasowania reguł — globy narzędzi, klauzule argumentów, listy
egress i sanityzatory.
Guardrails vs. Firewall
Która warstwa wychwytuje które zagrożenie — i kiedy potrzebujesz obu.
Zakres, klucze i polityki
Pełny model kluczy: co klucz ze sobą niesie i jak polityki się rozwiązują.
Tryby egzekwowania
Fail-open vs. fail-closed — pełne drzewo decyzyjne.