1. Lớp 1 — Scoped API key
Key là cổng đầu tiên. Trước khi bất kỳ nội dung nào được kiểm tra hoặc bất kỳ mô hình nào được gọi, gateway phân giải key gọi và quyết định liệu request có được phép hay không. Những gì key mang theo:model_limits— tập mô hình mà key có thể gọi. Một request cho mô hình ngoài danh sách bị từ chối ngay lập tức.allow_ips— IP allowlist tùy chọn. Một request từ nguồn không có trong danh sách bị từ chối.credit_limit_usd— giới hạn chi tiêu cứng. Một request sẽ đẩy key vượt quá giới hạn bị từ chối.expiry— ngày hết hạn cứng. Key hết hạn bị từ chối.environment— một tag (production,staging,dev, …) để tổ chức và nhận dạng key theo môi trường triển khai.guardrail_id— chính sách guardrail ràng buộc với key này (xem Lớp 2 và Lớp 4).firewall_policy_id— chính sách firewall ràng buộc với key này (xem Lớp 3).is_firewall_gateway— đánh dấu key là token có phạm vi firewall-gateway; bắt buộc cho các route evaluate và MCP gateway.
is_firewall_gateway và đọc
plaintext key yêu cầu Admin.
Để xem mô hình key đầy đủ, xem Phạm vi, key, chính sách, và workspace.
2. Lớp 2 — Input guardrail
Một khi key được xác thực, gateway chạy các quy tắc giai đoạn input của guardrail được ràng buộc đối với văn bản request — trước bất kỳ cuộc gọi mô hình thượng nguồn nào. Những gì nó thấy: Các message của caller như đã gửi. (Một prompt được tiêm nhiễm từ registry prompt được thêm vào sau, ở giai đoạn routing; quy tắc input không thấy nó.) Loại quy tắc có sẵn:keyword, regex, pii, max_chars,
external, llm_judge, grounding.
Hành động mà một quy tắc có thể tạo ra:
| Hành động | Điều gì xảy ra |
|---|---|
block | Request bị từ chối — HTTP 400 guardrail_blocked. Không tốn quota. Được đánh dấu skip-retry. |
mask | Match bị redact (vd: jane@acme.com → [EMAIL]). Văn bản đã sanitize tiếp tục đến mô hình. |
flag | Match được ghi lại; traffic không thay đổi. |
block ở giai đoạn này có nghĩa là mô hình không bao giờ được gọi.
Chi phí: không. Caller thấy một lỗi có cấu trúc nêu tên guardrail và
quy tắc đã kích hoạt.
Nơi cấu hình: Console → Guardrails, hoặc guardrail API. Yêu cầu
Developer+ để tạo hoặc sửa đổi. Xem Guardrails
để xem tham chiếu quy tắc đầy đủ.
3. Lớp 3 — Mô hình chạy
Nếu key hợp lệ và input guardrail pass, gateway chuyển tiếp request đến mô hình thượng nguồn. Đây là lớp duy nhất không có thực thi có thể cấu hình — nó đơn giản là mô hình đang làm công việc của mình. Firewall hoạt động trên các hành động mà mô hình tạo ra (Lớp 3 → Lớp 4 bên dưới), không phải trên chính mô hình. Routing, fallback, và cân bằng tải xảy ra ở đây một cách minh bạch.4. Lớp 4 — Agent Firewall (lời gọi tool và egress)
Sau khi mô hình phản hồi — hoặc inline, khi lời gọi tool được phát ra — Agent Firewall phán xét mọi hành động mà mô hình yêu cầu. Bốn bề mặt thực thi:| Bề mặt | Những gì firewall thấy |
|---|---|
inbound | Định nghĩa tool mà agent quảng bá cho mô hình. Chặn tool nguy hiểm trước khi mô hình có thể chọn nó. |
response | tool_calls mà mô hình phát ra trong phản hồi của nó. |
mcp | Một tools/call được dispatch qua Firewall MCP gateway hoặc evaluate hook. |
egress | Một đích đến mạng đi ra ngoài (host / IP / CIDR) được một tool báo cáo — bề mặt SSRF và data-exfiltration. |
| Verdict | Nó làm gì |
|---|---|
allow | Cuộc gọi tiếp tục. Được ghi log. |
audit | Cuộc gọi tiếp tục; được ghi lại để xem xét. default_verdict mặc định. |
deny | Cuộc gọi bị chặn — HTTP 400 firewall_blocked trên bề mặt inbound; lỗi tool trên mcp. |
sanitize | Các chuỗi con đã khớp bị redact khỏi đối số tool; cuộc gọi đã làm sạch tiếp tục. Trên inbound (chưa có đối số), leo thang thành deny. |
pending_approval | Cuộc gọi được giữ lại; một reviewer ngoài luồng phê duyệt hoặc từ chối; agent gửi lại với token phê duyệt dùng một lần. |
cap_cost | Deny một khi mức chi tiêu tích lũy của lần chạy agent vượt quá mức trần cents theo từng quy tắc. |
deny trên bề mặt inbound không tốn model token — block kích
hoạt trước cuộc gọi thượng nguồn. Một pending_approval giữ lại trả về
HTTP 400 firewall_approval_pending với approval id mà client poll dựa
vào.
Nơi cấu hình: Console → Firewall, hoặc firewall API. Yêu cầu
Developer+ để tạo hoặc sửa đổi chính sách và quy tắc. Xem
Firewall và Firewall rules
để xem ngôn ngữ quy tắc đầy đủ.
5. Lớp 5 — Output guardrail
Sau khi mô hình phản hồi (và sau khi mọi chu kỳ lời gọi tool hoàn thành), gateway chạy các quy tắc giai đoạn output của guardrail được ràng buộc đối với văn bản phản hồi trước khi nó đến caller. Cùng loại quy tắc và hành động áp dụng như ở Lớp 2. Mộtblock output
trả về HTTP 400 guardrail_blocked và hoàn trả quota đã tiêu trước —
caller không phải trả gì.
Streaming và output masking. Hành động
block được thực thi trên
cả phản hồi streaming và non-streaming — trên một stream, scanner cắt
giữa chừng và phát ra một thay thế. Hành động mask trên output hiện
chỉ áp dụng cho phản hồi non-streaming; trên một phản hồi streaming
chunk gốc đi qua mà không bị mask. Hãy xác minh tổ hợp stage/stream
của bạn trong sandbox guardrail trước khi phụ thuộc vào nó.6. Lớp 6 — Audit
Mọi match, verdict, và quyết định phê duyệt đều được ghi vào audit trail, tương quan với lần chạy agent và session gây ra nó. Đây không phải là bước thực thi riêng biệt — nó chạy song song với Lớp 2–5 — nhưng đây là lớp làm cho các lớp khác có trách nhiệm giải trình. Những gì được ghi log:- Guardrail match: loại quy tắc, hành động, giai đoạn, chuỗi chi tiết, và (nếu Log raw content được bật) chuỗi con đã khớp.
- Sự kiện firewall: bề mặt, tên tool, verdict, quy tắc đã khớp, mã lý do, các yếu tố rủi ro, và lần chạy/session mà cuộc gọi thuộc về.
- Quyết định phê duyệt: ai đã phê duyệt hoặc từ chối, khi nào, và liệu quy tắc cơ bản có thay đổi giữa lần giữ và quyết định không.
- Thay đổi chính sách: mọi tạo, cập nhật, xóa, và thay đổi autonomy level đều ghi một hàng audit có phiên bản.
7. Bảng tóm tắt
| Lớp | Những gì nó kiểm soát | Những gì nó thấy | Kết quả khi có hit | Nơi cấu hình |
|---|---|---|---|---|
| 1. Scoped key | Danh tính, truy cập mô hình, chi tiêu, IP, hạn sử dụng | Auth token của request | HTTP 4xx trước khi bất kỳ thứ gì chạy; không đo lường | Console → API Keys (Developer+) |
| 2. Input guardrail | Nội dung văn bản request | Message của caller | Block (HTTP 400 guardrail_blocked, không tính phí), mask, hoặc flag | Console → Guardrails (Developer+) |
| 3. Mô hình | — | — | — | Routing / channel config |
| 4. Agent Firewall | Lời gọi tool, MCP dispatch, egress | Tên tool, đối số, đích đến | allow / audit / deny / sanitize / pending_approval / cap_cost | Console → Firewall (Developer+) |
| 5. Output guardrail | Nội dung văn bản phản hồi | Phản hồi của mô hình | Block (HTTP 400, quota được hoàn trả), mask, hoặc flag | Console → Guardrails (Developer+) |
| 6. Audit | Quy gán và trail | Tất cả những điều trên | Mục nhập log bất biến | Console → Matches (Member) / Events & Runs (Developer+) |
8. Thứ tự phân giải chính sách
Đối với bất kỳ request nào, guardrail đang hoạt động và chính sách firewall được phân giải độc lập:- Gắn key — nếu key mang một
guardrail_idhoặcfirewall_policy_idtường minh, chính sách đó ràng buộc (khi nó tồn tại và được bật). - Mặc định workspace — nếu key không có gắn kết, guardrail hoặc
chính sách
is_defaultđã bật của workspace áp dụng. - Không có — không thực thi. Request giống hệt byte với một workspace chưa bao giờ bật tính năng này.
9. Fail-open và fail-closed
Hai hành vi — áp dụng cho các trường hợp khác nhau.Fail-open (lỗi thoáng qua): Nếu phân giải chính sách gặp lỗi
thoáng qua — DB trục trặc, mạng bị gián đoạn trên đường đến vendor
bên ngoài — gateway suy giảm về không thực thi thay vì làm gián
đoạn traffic. An toàn suy giảm; tính sẵn sàng được bảo toàn. Cấu hình
fail_open: false trên các quy tắc external hoặc llm_judge khi một
kiểm tra bị bỏ lỡ là không chấp nhận được đối với chính sách của bạn.Fail-closed (trường hợp mơ hồ): Ở nơi mà không thực thi sẽ đánh
bại chính quy tắc, engine fail closed: một báo cáo egress với đích đến
không thể phân giải bị từ chối; một kho phê duyệt không thể tiếp cận
giữ cuộc gọi thay vì cho nó qua; một skill mà quyền sở hữu của nó không
thể phân giải bị chặn. Tính sẵn sàng được bảo toàn trên con đường hạnh
phúc; an toàn không bị âm thầm bỏ qua trên các edge case quan trọng.10. Đào sâu
Guardrails
Tham chiếu quy tắc đầy đủ — loại, hành động, entity PII, LLM judge,
grounding, và sandbox test.
Firewall
Mô hình chính sách, verdict, bề mặt, shadow mode, phê duyệt HITL, và
phát hiện bất thường.
Firewall rules
Ngôn ngữ so khớp quy tắc — tool glob, mệnh đề đối số, danh sách
egress, và sanitizer.
Guardrails vs. Firewall
Lớp nào bắt mối đe dọa nào — và khi nào bạn cần cả hai.
Phạm vi, key, và chính sách
Mô hình key đầy đủ: những gì key mang và cách chính sách phân giải.
Enforcement modes
Fail-open vs. fail-closed — cây quyết định đầy đủ.