Audit — rilevamento di miglioramenti agentici

Gli audit sono job ricorrenti che analizzano i tuoi log degli agenti tra sessioni per trovare aree di miglioramento. Mentre un avviso monitora una metrica specifica che conosci già in quasi tempo reale, un audit indaga: secondo una pianificazione che stabilisci, esegue un passaggio deterministico delle policy sulla finestra temporale, quindi invia un agente di affidabilità basato su IA sulle tue sessioni — l’agente interroga direttamente i dati, legge i transcript sospetti, e (quando utile) esegue piccoli script di analisi, quindi redige raccomandazioni di miglioramento con le prove dietro ciascuna. Usa gli audit per rispondere a “cosa dovrei risolvere o migliorare nei miei agenti?” — e gli avvisi per ricevere una notifica istantanea quando una soglia specifica viene superata. Ogni miglioramento è collegato alle sessioni e alle query esatte dietro di esso, e un clic crea un avviso precompilato per rilevare ricorrenze. La superficie del dashboard è /<org-slug>/audits (sidebar → analyze → audits), controllata dai permessi audits:read / audits:write.

---

​

Come funziona un’esecuzione

Ogni esecuzione ha due livelli — una base deterministica e un’indagine agentia.

​

1. Il passaggio della policy (deterministico)

Prima che qualsiasi modello venga eseguito, l’audit esegue un piccolo catalogo di controlli delle policy SQL sulla finestra temporale: query aggregate delimitate che segnalano pattern noti come problematici e riportano quanti eventi / quali sessioni corrisponden — mai il testo corrispondente stesso. Il catalogo include:

• Perdita di segreti / credenziali nei payload degli eventi — chiavi di accesso AWS, chiavi API sk-…, chiavi private PEM, token JWT / bearer, e assegnamenti di credenziali KEY=….
• Marcatori di prompt injection — “ignora le istruzioni precedenti”, “rivela il tuo system prompt”, e simili.
• PII — numeri a forma di SSN (euristico).
• Negazioni di permessi degli strumenti e loop di chiamate di strumenti in fuga.

I risultati della policy vengono memorizzati come finding (tipo policy) che emergono sempre (non vengono mai ridotti dal limite per esecuzione), e vengono consegnati all’agente IA come piste iniziali. Poiché questo livello non richiede nessun modello, un audit produce comunque i suoi segnali di sicurezza più importanti anche se l’agente IA è indisponibile.

​

2. L’indagine agentia (IA)

L’audit quindi esegue un agente autonomo di affidabilità (lo stesso servizio Agents SDK di Claude che alimenta l’assistente del dashboard, con un prompt specifico per l’audit). Dato lo scope dell’audit (agenti selezionati × ambienti) e la finestra temporale, l’agente:

• esegue query SQL di sola lettura rispetto alle tue tabelle di analytics,
• legge una manciata di transcript di sessioni rappresentativi,
• facoltativamente scrive ed esegue brevi script Python in una sandbox chiusa in-pod (nessuna rete, nessun accesso al filesystem, segreti scrubati) per analisi che SQL non può esprimere — clustering di errori, calcolo di distribuzioni, sweep di payload già recuperati,
• e registra ogni miglioramento ben provato che trova.

Lavora attraverso diverse linee investigative — clustering di errori, drift rispetto a un baseline, fallimento degli obiettivi nei transcript, uso improprio degli strumenti, compromessi qualità/costo, e lacune di copertura — alla sensibilità dell’audit (bassa / media / alta). Ogni miglioramento deve citare prove: gli id di sessione che l’agente ha effettivamente ispezionato e/o la SQL che ha eseguito. Il server convalida che le sessioni citate esistono e scarta qualsiasi miglioramento senza prove sopravvissute, quindi l’agente indaga ma non inventa mai. Ogni miglioramento include:

• una raccomandazione (il cambiamento concreto da fare — un aggiustamento del prompt, una correzione dello schema dello strumento, una policy di ripetizione, una guardrail, copertura eval maggiore),
• un impatto previsto e una stima dello sforzo (basso / medio / alto),
• una magnitudine — big (un operatore dovrebbe ricevere una notifica), medium (appartiene alla relazione della esecuzione), o small (contesto del dashboard),
• un fingerprint stabile (dalla categoria del problema + scope, non dalle sessioni di questa esecuzione) così lo stesso problema viene tracciato da esecuzione a esecuzione mentre le prove cambiano,
• e, dove un semplice osservatore deterministico potrebbe catturare ricorrenze, un avviso suggerito che puoi creare in un clic.

Il livello IA è facoltativo ma consigliato. Se nessun agente IA è configurato per la pipeline di audit, le esecuzioni ancora si eseguono, persistono i finding della policy, e onestamente riportano “analisi non disponibile” per il livello agentia anziché passare silenziosamente.

​

Modalità di fallimento

I miglioramenti vengono classificati nel tuo catalogo di modalità di fallimento durevole dell’organizzazione (o propongono una nuova modalità). Le modalità danno ai pattern un’identità stabile tra le esecuzioni e il tracciamento della ricorrenza a lungo raggio.

​

Ciclo di vita della triage

Su una pagina di finding (/audits/<id>/findings/<finding-id>): Il rumore a basso segnale è controllato per audit con un limite di finding per esecuzione (top_k) sui miglioramenti agentici. I finding della policy bypassano il limite (sono rilevanti per la sicurezza e sempre mostrati). Qualsiasi cosa tagliata dal limite viene conteggiata nelle statistiche della esecuzione — nulla viene silenziosamente eliminato.

​

Pianificazione

• Cadenza (schedule_interval_secs): oraria a settimanale; giornaliera è la predefinita. Gli audit sono deliberatamente più rudi degli avvisi — un’indagine agentia scansiona intere finestre e viene eseguita per minuti.
• Finestra: o un lookback rolling fisso (ad es. “ogni esecuzione scansiona gli ultimi 7 giorni”) o since-last-run (la predefinita) — ogni esecuzione riprende da dove si è fermata l’esecuzione precedente riuscita, con un piccolo overlap così gli eventi di confine non vengono mai persi.
• L’esecuzione successiva viene pianificata un intervallo completo dopo che la precedente si completa, così un’esecuzione lenta non ammassa mai una seconda esecuzione concorrente dello stesso audit.
• Run now sulla pagina dell’audit lo rende dovuto immediatamente.

​

Selezione del modello

Quando crei un audit puoi scegliere quale modello l’indagine usa, dall’elenco di modelli che il tuo operatore ha configurato per il servizio agent. Con un singolo modello configurato, il picker lo mostra come didascalia; con diversi, scegli. Lasciarlo non impostato usa il default configurato.

​

Notifiche

Quando un’esecuzione emerge nuovi finding, l’audit notifica ai canali configurati della tua organizzazione — lo stesso gate alerts.enabled_channels e le impostazioni che la pipeline degli avvisi usa:

• Slack — un riassunto degli elementi significativi (big) nuovi con un deep link.
• Email — un report di audit progettato che elenca i nuovi miglioramenti (principale per gravità, raccomandazioni per elemento, deep link), inviato quando l’audit ha un canale email allegato e c’è almeno un finding nuovo.

I finding ricorrenti ma noti non notificano di nuovo.

​

Riferimento di configurazione

Le definizioni di audit vengono gestite nel dashboard (/audits/new) o tramite l’API. Le impostazioni per audit includono la cadenza e la finestra della pianificazione, lo scope ({"environments": [...], "agent_ids": [...]}), la sensibilità (low / medium / high), i canali di notifica, il limite di finding per esecuzione (top_k), e il modello (tramite llm_budget.model). Le impostazioni del server a livello di operatore (timeout, sandbox, l’URL del servizio agent) sono documentate in deployment.md.

​

API

Tutti gli endpoint hanno scope org e seguono l’autenticazione standard bearer-key (vedi api-keys.md). Per “audit eseguito ma non ha trovato nulla”, “la sandbox di codice è disabilitata”, e “email di audit non consegnata”, vedi troubleshooting.md.