AgentSight - eBPF Observability for AI Agents Cheatsheet
AgentSight applies eBPF to a problem the AI tooling world has largely ignored: knowing what an autonomous agent actually did to your system. Application-level tracing shows prompts, tool calls, and token counts, but it only sees what the agent framework chose to report. AgentSight instead observes at the kernel level — syscalls, file access, process execution, network connections — with zero instrumentation of the agent itself. When a coding agent runs, you see the real system effects, not the narrated version.
Requirements
- Linux kernel with eBPF/BTF support (5.x+)
- Root or
CAP_BPF privileges
- The agent process running on the same host
Installation
| Method | Command |
|---|
| From source | git clone https://github.com/agent-sight/agentsight && make |
| Binary | download from GitHub Releases |
| Docker | run privileged with /sys/kernel mounted |
| Verify | agentsight --version |
Basic Usage
| Command | Description |
|---|
sudo agentsight trace --pid <pid> | Trace a running agent process |
sudo agentsight trace -- claude-code | Launch and trace a command |
sudo agentsight trace --comm python | Trace by process name |
--output trace.json | Write structured events |
--follow-children | Include spawned subprocesses |
What It Captures
| Category | Events |
|---|
| Process | exec, fork, exit — what the agent ran |
| Filesystem | open, read, write, unlink — what it touched |
| Network | connect, send, recv — where it reached out |
| Credentials | setuid, capability changes |
| Subprocess tree | Commands spawned by the agent |
Because tracing happens in the kernel, an agent cannot omit or misreport these events — a meaningful difference from framework-level logging.
Why Kernel-Level for Agents
| Question | App-level tracing | AgentSight |
|---|
| What files did it modify? | Only if the tool reported it | Every write, always |
| Did it call an unexpected host? | Only instrumented calls | All connections |
| What did the shell tool actually run? | The command string | The full process tree |
| Did it exceed its intended scope? | Hard to prove | Observable |
Filtering
| Flag | Effect |
|---|
--filter-path /home/user/project | Only events under a path |
--exclude-path /tmp | Ignore noisy paths |
--net-only | Network events only |
--exec-only | Process executions only |
--min-duration 10ms | Drop trivial events |
# What did the agent do outside its working directory?
sudo agentsight trace --pid $(pgrep -n agent) --exclude-path /workspace
Correlating with Agent Semantics
| Approach | How |
|---|
| Timestamps | Align kernel events with agent trace spans |
| Session markers | Emit a marker at task start/end |
| Export | Feed JSON into your observability stack |
| OpenTelemetry | Correlate with app-level spans by time window |
Pairing AgentSight with app-level tracing (e.g. Arize Phoenix or Langfuse) gives both the intent and the effect.
Security Use Cases
| Use | Detail |
|---|
| Scope verification | Prove an agent stayed within its sandbox |
| Incident review | Reconstruct exactly what a misbehaving agent did |
| Prompt injection impact | See what actions followed an injected instruction |
| Compliance evidence | Auditable record of agent system access |
| Aspect | AgentSight | Tracee/Falco | Langfuse/Phoenix |
|---|
| Layer | Kernel (eBPF) | Kernel (eBPF) | Application |
| Focus | AI agent behavior | General runtime security | Prompts/tokens/spans |
| Instrumentation | None required | None required | SDK required |
| Best for | What an agent really did | Host threat detection | Agent reasoning quality |
Built on the same eBPF foundation as Tracee and Falco, but scoped to agent behavior.
Resources
