eBPF monitoring for AI agent processes

The short version: “eBPF monitoring” is a stack of evidence boundaries

AgentSight v1.0.31 describes itself as a local-first, top/strace-like observability tool for AI agents. The product can connect prompts, model calls, and tool decisions with process execution, file activity, resource use, and network-facing evidence, but those facts do not all arrive through one BPF program. Linux eBPF is the system-observation mechanism for recorded and debug capture. TLS plaintext uses user-space probes against the runtime that owns encryption. Background monitoring samples live process state. Native Claude, Codex, Gemini, and other supported session sources provide higher-level agent semantics.

That distinction matters when a trace is incomplete. A missing native token field, a missed two-second process sample, an unsupported TLS binary, and an eBPF attachment failure are different failure modes. Treating them all as “eBPF missed it” produces bad debugging conclusions.

Choose the observation plane before you interpret the result

AgentSight path	Primary evidence	Platform / privilege	Important limit
`sudo agentsight record -- <command>`	A bounded saved run that combines system capture with reconstructed model/tool activity where supported.	Linux with eBPF support; probe setup is elevated while the monitored command remains the user workflow.	Coverage depends on the selected process family, probe support, runtime packaging, and the plaintext/parser path used by that agent.
`agentsight monitor`	Periodic process/resource aggregates plus bounded samples of process, open-descriptor file targets, and network endpoints.	Current background service path targets Linux process state.	It is sampled state, not a complete syscall or network-event ledger.
`agentsight top`, `report --local`, `vis`	Supported agent-native sessions plus live process snapshots; `top` can add eBPF when privilege is available.	Native-session paths work on Windows, macOS, and Linux without eBPF.	Native records have strong agent semantics but only the fields the provider persists locally.
`agentsight debug ssl` / TLS path	Plaintext bytes at a supported user-space TLS implementation before encryption or after decryption.	Linux user-space probe path; executable and TLS implementation matter.	A successful uprobe does not guarantee that the application protocol can be reconstructed as an LLM call.

Process-family scope is more useful than one PID

Coding agents rarely do all work in the original CLI process. A tool call can launch a shell, compiler, test runner, package manager, browser helper, language server, or MCP server, which can launch more descendants. The meaningful system unit is therefore the process family tied to the run, not only the visible parent PID.

This is where system observation adds information that an application trace may not contain. A native tool event can say that the agent chose a Bash command. A process-oriented view can show which executable actually ran underneath it, which descendants appeared, and where CPU or memory accumulated. Neither source should be stretched beyond its boundary: a process event cannot tell you why the model selected the tool, while a tool event is not automatically a complete ledger of descendant effects.

Background monitor data is sampled state, not a hidden event log

AgentSight v1.0.31 makes the sampling contract inspectable in collector/src/cmd_monitor.rs. The monitor refresh interval is two seconds and each refresh scans up to 25 matched live sessions. Every aggregate window can retain process/resource deltas and target counts. Detailed process, file, and network samples are intentionally bounded: detail is persisted when a sample crosses a 30-second bucket boundary, with edge lists capped to five entries per ranking side.

File targets in this path come from the process family's current /proc/<pid>/fd descriptors, with PID start-time checks used to avoid confusing PID reuse. Network targets are sampled IP:port endpoints derived from the Linux process/socket state. This is different from saying “AgentSight recorded every open, close, connect, and send.” A path that opened and closed between samples can be absent from the detail table; an endpoint missing from a sample is not proof that the session never contacted it.

The safe interpretation is positive and bounded: “this target was observed during this sampled window.” If a security or correctness conclusion depends on proving that no other path or endpoint was used, reproduce the task with a capture mode that observes the needed event boundary and state the remaining coverage assumptions.

Linux eBPF and portable native-session workflows complement each other

The v1.0.31 README draws a concrete platform line. record and the eBPF-backed debug commands require Linux with eBPF support. In contrast, top, bind, vis, and report can use agent-native session files on Windows, macOS, or Linux. On Linux, top can additionally enable eBPF capture when suitable sudo access is already available.

This means “AgentSight works without eBPF” and “AgentSight uses eBPF for system observation” are both true, but they answer different questions. Native session data is often the better source for prompt identity, provider-specific response structure, model metadata, tool semantics, and token fields. eBPF-backed capture is useful when the question crosses into independent process or file effects that the agent itself did not persist.

TLS plaintext is a user-space attachment problem

The TLS path is the easiest place to over-generalize from the word eBPF. Linux uprobes attach to a user-space object path and a symbol or offset. Agent runtimes can use shared OpenSSL, OpenSSL embedded in Node, stripped Bun/BoringSSL, rustls, Electron helper processes, or a protocol that is not TLS at all. AgentSight therefore has to resolve the executable and select a runtime-specific plaintext boundary before BPF can observe useful bytes.

The dedicated TLS diagnostics guide owns those runtime-specific details. The top-level rule here is simpler: “uses eBPF” does not mean ciphertext can be generically decoded in the kernel. The product observes plaintext where the supported runtime exposes an attachable boundary, then higher-level parsing decides whether those bytes can become model-call evidence.

Correlation is the product layer above the probes

Raw process events, file targets, sampled sockets, and plaintext buffers are not yet an agent explanation. AgentSight stores recorded runs as local SQLite artifacts and exposes them through the overview, timeline, process tree, metrics, reports, and other views. The useful operation is correlation: line a model or tool phase up with the process family and machine effects that happened in the same run, while keeping the original evidence source visible.

For an investigation, preserve provenance rather than flattening everything into one generic “agent event.” A provider-native prompt, an eBPF process event, a sampled monitor target, and a reconstructed TLS call have different completeness guarantees. Source identity is part of the result.

A practical verification sequence

Start with the least invasive source that can answer the question, then add a lower-level boundary only when the first source leaves an ambiguity. For a live agent, inspect top. For an existing local session, use report --local or vis. When you need a reproducible Linux system profile, record a bounded command and inspect the saved audit. Use the background monitor for longitudinal sampled state, not as a substitute for event-complete capture. Only move into TLS diagnostics when the investigation actually requires provider payload reconstruction.

Terminal

$ agentsight top
$ agentsight report --local
$ sudo agentsight record -- claude
$ agentsight report audit --json
$ agentsight monitor
$ sudo agentsight debug ssl --binary-path <resolved-binary> --verbose

Observation is not enforcement, and absence is the hardest claim

AgentSight is an observability and profiling system. Seeing a process, path, endpoint, or plaintext call is useful positive evidence. It does not by itself prove that the operation was authorized, and the absence of a row does not prove that no operation occurred outside the selected process family, sampling interval, probe coverage, runtime hook, or parser path.

Keep the AgentSight version, task boundary, command, platform, privilege mode, relevant binary/runtime identity, and capture limitations with any audit result. If the requirement is prevention rather than observation, pair the evidence with an enforcement mechanism at the control point that must block the action.