AgentSight - Osservabilità eBPF per Agenti IA Cheatsheet
AgentSight applica eBPF a un problema che il mondo dell”IA ha ampiamente ignorato: sapere cosa un agente autonomo ha effettivamente fatto al tuo sistema. Il tracing a livello applicativo mostra prompt, chiamate di tool e conteggi di token, ma vede solo quello che il framework dell”agente ha scelto di segnalare. AgentSight invece osserva a livello kernel — syscall, accesso ai file, esecuzione di processi, connessioni di rete — con zero strumentazione dell”agente stesso. Quando un agente di codifica viene eseguito, vedi gli effetti di sistema reali, non la versione narrata.
Requisiti
- Kernel Linux con supporto eBPF/BTF (5.x+)
- Privilegi root o
CAP_BPF
- Il processo dell”agente in esecuzione sullo stesso host
Installazione
| Metodo | Comando |
|---|
| Dal sorgente | git clone https://github.com/agent-sight/agentsight && make |
| Binario | scarica da GitHub Releases |
| Docker | esegui con privilegio con /sys/kernel montato |
| Verifica | agentsight --version |
Utilizzo di Base
| Comando | Descrizione |
|---|
sudo agentsight trace --pid <pid> | Traccia un processo agente in esecuzione |
sudo agentsight trace -- claude-code | Avvia e traccia un comando |
sudo agentsight trace --comm python | Traccia per nome di processo |
--output trace.json | Scrivi eventi strutturati |
--follow-children | Includi sottoprocessi generati |
Cosa Cattura
| Categoria | Eventi |
|---|
| Processo | exec, fork, exit — cosa ha eseguito l”agente |
| Filesystem | open, read, write, unlink — cosa ha toccato |
| Rete | connect, send, recv — dove ha raggiunto |
| Credenziali | setuid, cambiamenti di capacità |
| Albero dei sottoprocessi | Comandi generati dall”agente |
Poiché il tracing avviene nel kernel, un agente non può omettere o misreportare questi eventi — una differenza significativa dal logging a livello di framework.
Perché Kernel-Level per Agenti
| Domanda | Tracing a livello app | AgentSight |
|---|
| Quali file ha modificato? | Solo se il tool l”ha segnalato | Ogni scrittura, sempre |
| Ha chiamato un host inaspettato? | Solo le chiamate strumentate | Tutte le connessioni |
| Cosa ha effettivamente eseguito lo strumento shell? | La stringa di comando | L”albero completo dei processi |
| Ha superato il suo scopo previsto? | Difficile da provare | Osservabile |
Filtrazione
| Flag | Effetto |
|---|
--filter-path /home/user/project | Solo eventi sotto un percorso |
--exclude-path /tmp | Ignora percorsi rumorosi |
--net-only | Solo eventi di rete |
--exec-only | Solo esecuzioni di processi |
--min-duration 10ms | Scarta eventi triviali |
# Cosa ha fatto l''agente al di fuori della sua directory di lavoro?
sudo agentsight trace --pid $(pgrep -n agent) --exclude-path /workspace
Correlazione con la Semantica dell”Agente
| Approccio | Come |
|---|
| Timestamp | Allinea gli eventi kernel con gli span di traccia dell”agente |
| Marcatori di sessione | Emetti un marcatore all”inizio/fine del task |
| Esportazione | Alimenta JSON nel tuo stack di osservabilità |
| OpenTelemetry | Correla con span a livello app per finestra temporale |
Accoppiare AgentSight con il tracing a livello app (ad es. Arize Phoenix o Langfuse) dà sia l”intento che l”effetto.
Casi di Utilizzo della Sicurezza
| Utilizzo | Dettaglio |
|---|
| Verifica di ambito | Prova che un agente è rimasto dentro la sua sandbox |
| Revisione degli incidenti | Ricostituisci esattamente cosa ha fatto un agente non conforme |
| Impatto dell”iniezione di prompt | Vedi quali azioni hanno seguito un”istruzione iniettata |
| Evidenza di conformità | Record auditable dell”accesso dell”agente al sistema |
| Aspetto | AgentSight | Tracee/Falco | Langfuse/Phoenix |
|---|
| Livello | Kernel (eBPF) | Kernel (eBPF) | Applicazione |
| Foco | Comportamento dell”agente IA | Rilevamento di minacce generale | Prompt/token/span |
| Strumentazione | Nessuna richiesta | Nessuna richiesta | SDK richiesto |
| Migliore per | Cosa ha effettivamente fatto un agente | Rilevamento di minacce host | Qualità del ragionamento dell”agente |
Costruito sulla stessa base eBPF di Tracee e Falco, ma focalizzato sul comportamento dell”agente.
Risorse
