1. 레이어 1 — 범위 지정 API 키
키가 첫 번째 게이트입니다. 콘텐츠를 검사하거나 모델을 호출하기 전에, 게이트웨이는 호출하는 키를 해석하고 요청이 허용되는지 결정합니다. 키가 담고 있는 것:model_limits— 키가 호출할 수 있는 모델 집합. 목록에 없는 모델에 대한 요청은 즉시 거부됩니다.allow_ips— 선택적 IP 허용 목록. 목록에 없는 소스에서 온 요청은 거부됩니다.credit_limit_usd— 하드 지출 한도. 키를 한도 이상으로 올릴 요청은 거부됩니다.expiry— 하드 만료 날짜. 만료된 키는 거부됩니다.environment— 키를 배포 환경별로 구성하고 식별하는 태그 (production,staging,dev, …).guardrail_id— 이 키에 바인딩되는 guardrail 정책 (레이어 2와 레이어 4 참조).firewall_policy_id— 이 키에 바인딩되는 firewall 정책 (레이어 3 참조).is_firewall_gateway— 키를 firewall-gateway-scoped 토큰으로 표시합니다; evaluate 및 MCP 게이트웨이 라우트에 필요합니다.
is_firewall_gateway와 평문 키 읽기는 Admin 필요.
전체 키 모델은 범위, 키, 정책, 워크스페이스를
참조하세요.
2. 레이어 2 — 입력 guardrails
키가 검증되면, 게이트웨이는 업스트림 모델 호출 전에 — 바인딩된 guardrail의 input-stage 규칙을 요청 텍스트에 대해 실행합니다. 보는 것: 제출된 그대로의 호출자 메시지. (레지스트리 프롬프트에서 주입된 프롬프트는 나중에 라우팅 단계에서 추가됩니다; 입력 규칙은 그것을 보지 않습니다.) 사용 가능한 규칙 타입:keyword, regex, pii, max_chars, external,
llm_judge, grounding.
규칙이 생성할 수 있는 액션:
| 액션 | 무슨 일이 일어나는가 |
|---|---|
block | 요청이 거부됩니다 — HTTP 400 guardrail_blocked. 쿼터가 청구되지 않습니다. skip-retry로 표시됩니다. |
mask | 매치가 삭제됩니다 (예: jane@acme.com → [EMAIL]). 정화된 텍스트가 모델로 계속됩니다. |
flag | 매치가 기록됩니다; 트래픽은 변경되지 않습니다. |
block은 모델이 결코 호출되지 않음을 의미합니다. 비용: 없음.
호출자는 guardrail과 발동된 규칙을 명시하는 구조화된 오류를 봅니다.
구성 위치: 콘솔 → Guardrails, 또는 guardrail API. 생성 또는 수정은
Developer+ 필요. 전체 규칙 레퍼런스는 Guardrails
참조.
3. 레이어 3 — 모델 실행
키가 유효하고 입력 guardrails가 통과되면, 게이트웨이는 요청을 업스트림 모델로 전달합니다. 이것은 구성 가능한 강제가 없는 유일한 레이어입니다 — 단순히 모델이 작업을 수행하는 것입니다. Firewall은 모델이 생성하는 액션에 대해 작동합니다 (아래 레이어 3 → 레이어 4), 모델 자체에 대해서는 아닙니다. 라우팅, 폴백, 로드 밸런싱이 여기서 투명하게 일어납니다.4. 레이어 4 — Agent Firewall (툴 호출과 egress)
모델이 응답한 후 — 또는 툴 호출이 발행될 때 인라인으로 — Agent Firewall은 모델이 요청하는 모든 액션을 판단합니다. 네 가지 강제 표면:| 표면 | Firewall이 보는 것 |
|---|---|
inbound | 에이전트가 모델에 광고하는 툴 정의. 모델이 선택하기 전에 위험한 툴을 차단합니다. |
response | 모델이 응답에서 발행하는 tool_calls. |
mcp | Firewall MCP 게이트웨이 또는 evaluate 훅을 통해 디스패치된 tools/call. |
egress | 툴이 보고하는 아웃바운드 네트워크 목적지 (호스트 / IP / CIDR) — SSRF와 데이터 유출 표면. |
| 판정 | 무슨 일이 일어나는가 |
|---|---|
allow | 호출이 진행됩니다. 로깅됨. |
audit | 호출이 진행됩니다; 검토를 위해 기록됩니다. 기본 default_verdict. |
deny | 호출이 차단됩니다 — inbound 표면에서 HTTP 400 firewall_blocked; mcp에서 툴 오류. |
sanitize | 매치된 부분 문자열이 툴 인자에서 삭제됩니다; 정화된 호출이 진행됩니다. inbound에서 (아직 인자 없음), deny로 상향됩니다. |
pending_approval | 호출이 보류됩니다; 대역 외 검토자가 승인하거나 거부합니다; 에이전트가 일회용 승인 토큰으로 재제출합니다. |
cap_cost | 에이전트 실행의 누적 지출이 규칙별 센트 한도를 초과하면 거부합니다. |
inbound 표면에서의 deny는 모델 토큰 비용 없이 발동합니다 — 업스트림
호출 전에 차단이 발동합니다. pending_approval 보류는 클라이언트가 폴링하는
승인 id와 함께 HTTP 400 firewall_approval_pending을 반환합니다.
구성 위치: 콘솔 → Firewall, 또는 firewall API. 정책과 규칙 생성 또는
수정은 Developer+ 필요. 전체 규칙 언어는 Firewall과
Firewall 규칙 참조.
5. 레이어 5 — 출력 guardrails
모델이 응답한 후 (그리고 툴 호출 사이클이 완료된 후), 게이트웨이는 바인딩된 guardrail의 output-stage 규칙을 호출자에게 도달하기 전에 응답 텍스트에 대해 실행합니다. 레이어 2와 동일한 규칙 타입과 액션이 적용됩니다. 출력block은 HTTP 400
guardrail_blocked를 반환하고 사전 소모된 쿼터를 환불합니다 — 호출자는
아무것도 지불하지 않습니다.
스트리밍과 출력 마스킹.
block 액션은 스트리밍과 비스트리밍 응답 모두에서
강제됩니다 — 스트림에서 스캐너는 도중에 끊고 대체 메시지를 발행합니다.
출력에 대한 mask 액션은 현재 비스트리밍 응답에만 적용됩니다; 스트리밍
응답에서 원본 청크는 마스킹되지 않은 채로 통과합니다. 의존하기 전에
guardrail 샌드박스에서 스테이지/스트림 조합을 검증하세요.6. 레이어 6 — 감사
모든 매치, 판정, 승인 결정이 감사 추적에 기록되고, 그것을 유발한 에이전트 실행과 세션과 연관됩니다. 이것은 별도의 강제 단계가 아닙니다 — 레이어 2–5와 병렬로 실행됩니다 — 하지만 이것이 다른 것들을 책임지게 만드는 레이어입니다. 로깅되는 것:- Guardrail 매치: 규칙 타입, 액션, 스테이지, 상세 문자열, 그리고 (Log raw content가 활성화된 경우) 매치된 부분 문자열.
- Firewall 이벤트: 표면, 툴 이름, 판정, 매치된 규칙, 이유 코드, 위험 요인, 그리고 호출이 속하는 실행/세션.
- 승인 결정: 누가 승인하거나 거부했는지, 언제, 그리고 보류와 결정 사이에 기저 규칙이 변경되었는지.
- 정책 변경: 모든 생성, 업데이트, 삭제, 자율성 수준 변경이 버전 관리된 감사 행을 씁니다.
7. 요약 표
| 레이어 | 제어하는 것 | 보는 것 | 히트 시 결과 | 구성 위치 |
|---|---|---|---|---|
| 1. 범위 지정 키 | 신원, 모델 접근, 지출, IP, 만료 | 요청의 인증 토큰 | 아무것도 실행되기 전 HTTP 4xx; 계량 없음 | 콘솔 → API Keys (Developer+) |
| 2. 입력 guardrails | 요청 텍스트 콘텐츠 | 호출자 메시지 | 차단 (HTTP 400 guardrail_blocked, 청구 없음), 마스킹, 또는 플래그 | 콘솔 → Guardrails (Developer+) |
| 3. 모델 | — | — | — | 라우팅 / 채널 구성 |
| 4. Agent Firewall | 툴 호출, MCP 디스패치, egress | 툴 이름, 인자, 목적지 | allow / audit / deny / sanitize / pending_approval / cap_cost | 콘솔 → Firewall (Developer+) |
| 5. 출력 guardrails | 응답 텍스트 콘텐츠 | 모델의 응답 | 차단 (HTTP 400, 쿼터 환불), 마스킹, 또는 플래그 | 콘솔 → Guardrails (Developer+) |
| 6. 감사 | 귀속과 추적 | 위의 모두 | 변경 불가 로그 항목 | 콘솔 → Matches (Member) / Events & Runs (Developer+) |
8. 정책 해석 순서
모든 요청에 대해, 활성 guardrail과 firewall 정책은 독립적으로 해석됩니다:- 키 연결 — 키에 명시적
guardrail_id또는firewall_policy_id가 있으면, 그 정책이 존재하고 활성화된 경우 바인딩됩니다. - 워크스페이스 기본값 — 키에 연결이 없으면, 워크스페이스의 활성화된
is_defaultguardrail 또는 정책이 적용됩니다. - 둘 다 아님 — 강제 없음. 요청은 기능을 한 번도 활성화하지 않은 워크스페이스와 바이트 단위로 동일합니다.
9. 페일 오픈과 페일 클로즈
두 가지 동작 — 서로 다른 경우에 적용됩니다.페일 오픈 (일시적 오류): 정책 해석이 일시적 오류에 부딪히면 — 데이터베이스
문제, 외부 벤더로 가는 네트워크 문제 — 게이트웨이는 트래픽을 중단시키기보다
강제 없음으로 저하됩니다. 안전성은 저하되지만 가용성은 보존됩니다.
놓친 검사가 정책에서 용납되지 않을 때
external 또는 llm_judge 규칙에서
fail_open: false를 구성하세요.페일 클로즈 (모호한 경우): 강제하지 않는 것이 규칙을 무력화할 경우,
엔진은 페일 클로즈합니다: 해석 불가능한 목적지가 있는 egress 보고는
거부되고; 도달 불가능한 승인 저장소는 호출을 통과시키기보다 보류하고;
소유권을 해석할 수 없는 스킬은 차단됩니다. 행복한 경로에서 가용성은
보존되며; 중요한 엣지 케이스에서 안전성이 조용히 건너뛰어지지 않습니다.10. 심층 분석
Guardrails
전체 규칙 레퍼런스 — 타입, 액션, PII 엔티티, LLM 심판, 그라운딩, 테스트
샌드박스.
Firewall
정책 모델, 판정, 표면, 섀도우 모드, HITL 승인, 이상 탐지.
Firewall 규칙
규칙 매칭 언어 — 툴 glob, 인자 절, egress 목록, 새니타이저.
Guardrails vs. Firewall
어느 레이어가 어느 위협을 잡는지 — 그리고 언제 둘 다 필요한지.
범위, 키, 정책
전체 키 모델: 키가 담고 있는 것과 정책이 해석되는 방법.
강제 모드
페일 오픈 vs. 페일 클로즈 — 전체 결정 트리.