Vai al contenuto principale
Hai una chiave che il tuo agent usa su api.orcarouter.ai, e vuoi che ogni chiamata a tool che quella chiave fa venga governata — bloccata, auditata, sanitizzata o messa in attesa di approvazione — senza toccare il codice del tuo agent. È una configurazione dell’agent firewall in due passi: crea una policy del firewall una volta, poi punta la chiave su di essa. Dalla chiamata successiva in poi, ogni tool che la chiave emette viene controllato rispetto alla policy nel gateway. Questa pagina è il percorso crea-e-collega. Per il modello completo di policy (superfici, verdetti, risoluzione) vedi la Panoramica del Firewall; per la grammatica delle regole vedi Regole del Firewall.
Tutta la configurazione di policy e chiavi avviene nella console (o nelle rotte di gestione /api/workspace/firewall/*, che usano la tua sessione / token di accesso — non una chiave di relay sk-orca-…). Solo le chiamate /v1/* del tuo agent usano la chiave di relay. Creare e collegare una policy è un’azione Developer+.

​
1. Configurazione dell’agent firewall in breve

Una policy del firewall è un oggetto nominato, con scope a livello di workspace: un elenco ordinato di regole più un verdetto di default per tutto ciò che nessuna regola corrisponde. Una chiave aderisce a una policy attraverso il suo campo firewall_policy_id. Nient’altro nel tuo stack cambia.

Crea la policy

Nominala, scegli un verdetto di default, aggiungi regole — oppure parti da un livello di autonomia / preset e modifica.

Collega una chiave

Imposta il firewall_policy_id della chiave sulla policy, o marca la policy come default del workspace così ogni chiave non collegata la eredita.

​
2. Crea una policy nella console

  1. Apri Security → Firewall → Policies e scegli New policy.
  2. Nominala (univoca nel workspace) e lascia Enabled attivo.
  3. Scegli un verdetto di default — vedi §3.
  4. Aggiungi regole nell’editor delle regole, oppure parti vuoto e lascia che Discovered tools guidi la creazione dal traffico reale più avanti.
  5. Salva. La policy esiste ma non governa nulla finché una chiave non la punta o non la rendi il default del workspace.
Non vuoi scrivere a mano le regole per prima cosa? Applica un livello di autonomia (balanced è il punto di partenza consigliato) — materializza righe di policy e di guardrail reali e modificabili che puoi poi mettere a punto. Oppure parti da una regola da un preset integrato e modificala. In ogni caso arrivi allo stesso posto: una policy nominata che colleghi a una chiave.

​
3. Scegli il verdetto di default

Il verdetto di default è ciò che la policy fa quando nessuna regola corrisponde a una chiamata a tool. È il pavimento della tua postura. Accetta esattamente tre valori:
default_verdictQuando nessuna regola corrisponde…
audit (default)Consenti la chiamata, ma registrala. Osserva tutto, blocca nulla — il punto di partenza sicuro.
allowConsenti e logga, nessun record di revisione.
denyBlocca tutto ciò che una regola non permette esplicitamente — una postura default-deny da abbinare a regole di allow.
deny è default-deny: ogni chiamata a tool che le tue regole non consentono esplicitamente viene bloccata. Potente, ma fermerà chiamate che hai dimenticato di mettere in allowlist. Fai il rollout di una policy default-deny sotto shadow mode prima e osserva il feed degli eventi prima di applicarla.
I verdetti che una regola può produrre (allow, audit, deny, sanitize, pending_approval, cap_cost) sono trattati in Verdetti — il verdetto di default è limitato ai tre sopra.

​
4. Collega la policy a una chiave

Una chiave aderisce a una policy attraverso il suo firewall_policy_id. Nella console:
  1. Apri Keys, modifica la chiave che il tuo agent usa.
  2. Imposta Firewall policy sulla policy che hai creato (questo scrive firewall_policy_id).
  3. Salva. La chiamata successiva che quella chiave fa viene governata.
Il binding vive sulla chiave, nel gateway — il tuo agent continua a inviare lo stesso Authorization: Bearer sk-orca-… e lo stesso corpo di richiesta. Non c’è alcuna modifica al codice di tool-calling del tuo agent. 
# Your agent's relay call is unchanged. The attached policy is enforced
# at the gateway before any tool call in the response is dispatched.
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "delete the staging table"}],
    "tools": [{"type": "function", "function": {"name": "db.query"}}]
  }'
Se una regola nega una chiamata a tool sulla superficie inbound, quella chiamata torna come HTTP 400 con codice firewall_blocked, nominando il tool e la motivazione — vedi com’è fatto un block.

​
5. Risoluzione: collegata → default del workspace

Per ogni chiamata a tool, il gateway risolve quale policy si applica in quest’ordine:
Se il firewall_policy_id della chiave chiamante punta a una policy che esiste ed è abilitata, quella policy si applica.
Altrimenti, si applica la policy is_default abilitata del workspace (se ne è impostata una). Al massimo una policy per workspace può essere il default; promuovere un nuovo default declassa il vecchio nella stessa transazione.
Nessun collegamento e nessun default significa nessuna policy. Con l’observe mode attivo la chiamata viene consentita e loggata come un gap di copertura; con esso disattivato la chiamata viene consentita silenziosamente.
Una policy collegata e disabilitata ricade sul default del workspace — non disattiva l’applicazione. (Questo differisce dai guardrails, dove un collegamento disabilitato si risolve in nessuno.) Per togliere una chiave dallo scope del firewall, scollegala (imposta firewall_policy_id a 0), non limitarti a disabilitare la sua policy.
Per rendere una policy il default per ogni chiave non collegata, modificala e impostala come default del workspace anziché collegare le chiavi una a una — vedi Gestisci le policy.

​
6. Verifica che abbia avuto effetto

Prima di farci affidamento, conferma che la policy scatti nel modo che ti aspetti:
  • Testala — la scheda sandbox Test esegue un dry-run della policy contro una chiamata a tool di esempio e restituisce il verdetto, la regola corrispondente e la motivazione. Nulla viene dispatchato o persistito. Vedi Testa le regole.
  • Osserva il feed degli eventi — una volta che la chiave riceve traffico live, Events mostra ogni valutazione, filtrabile per verdetto, superficie, tool ed esecuzione.
Fai il rollout di qualsiasi policy applicativa dietro shadow mode prima: valuta e logga esattamente come farebbe in produzione, ma declassa ogni verdetto applicativo a audit e prefissa la motivazione [shadow] would …. Disattiva la shadow una volta che il feed degli eventi la mostra scattare su ciò che ti aspetti e su nulla che non vuoi.

​
Dove andare dopo

Scrivere regole

Il linguaggio di matching completo — glob di tool, clausole sugli argomenti, elenchi egress, sanitizer.

Allow-listing dei tool

Abbina un verdetto di default deny a regole di allow esplicite.

Gestisci le policy

Default, abilita/disabilita, versioning e revert.

Perché zero trust

Perché governare le azioni — non solo il testo — conta per gli agent.
Per le minacce che una policy è pensata per fermare, vedi chiamate a tool pericolose e agenzia eccessiva.