AgentSight: Zero-Instrumentation LLM Agent Observability with eBPF

AgentSight is a observability tool designed specifically for monitoring LLM agent behavior through SSL/TLS traffic interception and process monitoring. Unlike traditional application-level instrumentation, AgentSight observes at the system boundary using eBPF technology, providing tamper-resistant insights into AI agent interactions with minimal performance overhead.

✨ Zero Instrumentation Required - No code changes, no new dependencies, no SDKs. Works with any AI framework or application out of the box.

Quick Start

wget https://github.com/eunomia-bpf/agentsight/releases/latest/download/agentsight && chmod +x agentsight
# Record agent behavior from claude
sudo ./agentsight record -c "claude"
# Record agent behavior from gemini-cli (comm is "node")
sudo ./agentsight record -c "node"
# For Python AI tools
sudo ./agentsight record -c "python"
# Record claude or gemini activity with NVM Node.js, if bundle OpenSSL statically
sudo ./agentsight record --binary-path /usr/bin/node -c node

Visit http://127.0.0.1:7395 to view the recorded data.

Real-time process tree visualization showing AI agent interactions and file operations

Real-time timeline visualization showing AI agent interactions and system calls

Real-time metrics visualization showing AI agent memory and CPU usage

Visit http://127.0.0.1:7395 to view the captured data in real-time.

🚀 Why AgentSight?

Traditional Observability vs. System-Level Monitoring

Challenge	Application-Level Tools	AgentSight Solution
Framework Adoption	❌ New SDK/proxy for each framework	✅ Drop-in daemon, no code changes
Closed-Source Tools	❌ Limited visibility into operations	✅ Complete visibility into prompts & behaviors
Dynamic Agent Behavior	❌ Logs can be silenced or manipulated	✅ Kernel-level hooks, tamper-resistant
Encrypted Traffic	❌ Only sees wrapper outputs	✅ Captures real unencrypted requests/responses
System Interactions	❌ Misses subprocess executions	✅ Tracks all process behaviors & file operations
Multi-Agent Systems	❌ Isolated per-process tracing	✅ Global correlation and analysis

AgentSight captures critical interactions that application-level tools miss:

• Subprocess executions that bypass instrumentation
• Raw encrypted payloads before agent processing
• File operations and system resource access
• Cross-agent communications and coordination

🏗️ Architecture

┌─────────────────────────────────────────────────┐
│              AI Agent Runtime                   │
│   ┌─────────────────────────────────────────┐   │
│   │    Application-Level Observability      │   │
│   │  (LangSmith, Helicone, Langfuse, etc.)  │   │
│   │         🔴 Tamper Vulnerable             │   │
│   └─────────────────────────────────────────┘   │
│                     ↕ (Can be bypassed)         │
├─────────────────────────────────────────────────┤ ← System Boundary
│  🟢 AgentSight eBPF Monitoring (Tamper-proof)   │
│  ┌─────────────────┐  ┌─────────────────────┐   │
│  │   SSL Traffic   │  │    Process Events   │   │
│  │   Monitoring    │  │    Monitoring       │   │
│  └─────────────────┘  └─────────────────────┘   │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│         Rust Streaming Analysis Framework       │
│  ┌─────────────┐  ┌──────────────┐  ┌────────┐  │
│  │   Runners   │  │  Analyzers   │  │ Output │  │
│  │ (Collectors)│  │ (Processors) │  │        │  │
│  └─────────────┘  └──────────────┘  └────────┘  │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│           Frontend Visualization                │
│     Timeline • Process Tree • Event Logs       │
└─────────────────────────────────────────────────┘

Core Components

1. eBPF Data Collection (Kernel Space)

   • SSL Monitor: Intercepts SSL/TLS read/write operations via uprobe hooks
   • Process Monitor: Tracks process lifecycle and file operations via tracepoints
   • <3% Performance Overhead: Operates below application layer with minimal impact

2. Rust Streaming Framework (User Space)

   • Runners: Execute eBPF programs and stream JSON events (SSL, Process, Agent, Combined)
   • Analyzers: Pluggable processors for HTTP parsing, chunk merging, filtering, logging
   • Event System: Standardized event format with rich metadata and JSON payloads

3. Frontend Visualization (React/TypeScript)

   • Timeline View: Interactive event timeline with zoom and filtering
   • Process Tree: Hierarchical process visualization with lifecycle tracking
   • Log View: Raw event inspection with syntax highlighting
   • Real-time Updates: Live data streaming and analysis

Data Flow Pipeline

eBPF Programs → JSON Events → Runners → Analyzer Chain → Frontend/Storage/Output

Usage

Prerequisites

• Linux kernel: 4.1+ with eBPF support (5.0+ recommended)
• Root privileges: Required for eBPF program loading
• Rust toolchain: 1.88.0+ (for building collector)
• Node.js: 18+ (for frontend development)
• Build tools: clang, llvm, libelf-dev

Installation

Option 1: Using Docker (Recommended)

# Pull the latest Docker image
docker pull ghcr.io/eunomia-bpf/agentsight:latest

# Or build locally
git clone https://github.com/eunomia-bpf/agentsight.git --recursive
cd agentsight
make build  # Build the agentsight binary first
docker build -t agentsight:local -f dockerfile .

Run with Docker:

# Basic monitoring with web UI (access at http://localhost:7395)
docker run --privileged --pid=host -p 7395:7395 -v /sys:/sys:ro \
  ghcr.io/eunomia-bpf/agentsight:latest record --comm claude

# Monitor Python AI tools (requires library mounts for SSL capture)
docker run --privileged --pid=host --network=host \
  -v /sys:/sys:ro -v /lib:/lib:ro -v /usr/lib:/usr/lib:ro \
  ghcr.io/eunomia-bpf/agentsight:latest record --comm python3

# Save logs to host directory
docker run --privileged --pid=host -p 7395:7395 -v /sys:/sys:ro \
  -v $(pwd)/logs:/logs \
  ghcr.io/eunomia-bpf/agentsight:latest record --comm node --log-file /logs/record.log

# Use custom port
docker run --privileged --pid=host -p 8080:8080 -v /sys:/sys:ro \
  ghcr.io/eunomia-bpf/agentsight:latest record --comm claude --server-port 8080

Docker Requirements:

• --privileged: Required for eBPF (loads kernel programs)
• --pid=host: Access host processes for monitoring
• -v /sys:/sys:ro: Read-only access to kernel interfaces
• -v /lib:/lib:ro -v /usr/lib:/usr/lib:ro: Required for Python SSL monitoring in docker (eBPF needs to read shared libraries to attach uprobes)
• -p 7395:7395 or --network=host: Expose web UI port (default: 7395)

Option 2: Build from Source

# Clone repository with submodules
git clone https://github.com/eunomia-bpf/agentsight.git --recursive
cd agentsight

# Install system dependencies (Ubuntu/Debian)
make install

# Build all components (frontend, eBPF, and Rust)
make build

# Or build individually:
# make build-frontend  # Build frontend assets
# make build-bpf       # Build eBPF programs
# make build-rust      # Build Rust collector

Usage Examples

Basic Monitoring

# Monitor all SSL traffic from system applications
sudo ./agentsight record -c "python"  # For Python AI tools
sudo ./agentsight record -c "claude"  # For Claude Code
sudo ./agentsight record -c "node"    # For Node.js AI tools like gemini-cli

# Combined SSL and process monitoring with web interface
sudo ./agentsight trace --ssl --process --server

NVM Node.js Applications

For Node.js installed via NVM, use the --binary-path option:

# Monitor Node.js applications with statically-linked SSL
sudo ./agentsight ssl --binary-path ~/.nvm/versions/node/v20.0.0/bin/node --comm node

# Record with custom binary path
sudo ./agentsight record -c node -- --binary-path ~/.nvm/versions/node/v20.0.0/bin/node

Direct eBPF Program Usage

# Run eBPF programs directly for development/testing
sudo ./bpf/sslsniff --binary-path ~/.nvm/versions/node/v20.0.0/bin/node --verbose
sudo ./bpf/process -c python

Web Interface Access

All monitoring commands with --server flag provide web visualization at:

• Timeline View: http://127.0.0.1:7395/timeline
• Process Tree: http://127.0.0.1:7395/tree
• Raw Logs: http://127.0.0.1:7395/logs

Testing with Python Scripts

To test AgentSight with Python scripts inside containers (like script/test-python/test_openai.py):

# 1. Start AgentSight in Docker (captures SSL traffic from host Python processes)
docker run --privileged --pid=host --network=host \
  -v /sys:/sys:ro -v /lib:/lib:ro -v /usr/lib:/usr/lib:ro \
  -v $(pwd)/logs:/logs \
  ghcr.io/eunomia-bpf/agentsight:latest \
  record --comm python3 --log-file /logs/capture.log

# 2. In another terminal, run your Python script on the host
python3 your_script.py

# 3. View captured traffic at http://localhost:7395 or check logs/capture.log

Why library mounts are needed:

• Python uses dynamically-linked SSL libraries (libssl.so.3, libcrypto.so.3)
• eBPF uprobes need to read these libraries from /lib and /usr/lib to attach to SSL functions
• With --pid=host, the container monitors host processes but needs access to host libraries

Alternative: Run agentsight directly on host (simpler for testing):

sudo ./agentsight record --comm python3 --server-port 7395

❓ Frequently Asked Questions

General

Q: How does AgentSight differ from traditional APM tools?
A: AgentSight operates at the kernel level using eBPF, providing tamper-resistant monitoring that agents cannot bypass. Traditional APM requires instrumentation that can be compromised.

Q: What's the performance impact?
A: Minimal impact (<3% CPU overhead). eBPF runs in kernel space with optimized data collection.

Q: Can agents detect they're being monitored?
A: Detection is extremely difficult since monitoring occurs at the kernel level without code modification.

Technical

Q: Which Linux distributions are supported?
A: Any distribution with kernel 4.1+ and eBPF support. Tested on Ubuntu 20.04+, CentOS 8+, RHEL 8+.

Q: Can I monitor multiple agents simultaneously?
A: Yes, use combined monitoring modes for concurrent multi-agent observation with correlation.

Q: How do I filter sensitive data?
A: Built-in analyzers can remove authentication headers and filter specific content patterns.

Q: Why doesn't AgentSight capture traffic from my NVM Node.js application?
A: NVM Node.js binaries statically link OpenSSL instead of using system libraries. Use the --binary-path option to attach directly to your Node.js binary: --binary-path ~/.nvm/versions/node/v20.0.0/bin/node

Troubleshooting

Q: "Permission denied" errors
A: Ensure you're running with sudo or have CAP_BPF and CAP_SYS_ADMIN capabilities.

Q: "Failed to load eBPF program" errors
A: Check kernel version and eBPF support. Update vmlinux.h for your architecture if needed.

🤝 Contributing

We welcome contributions! See our development setup:

# Clone with submodules
git clone --recursive https://github.com/eunomia-bpf/agentsight.git

# Install development dependencies  
make install

# Run tests
make test

# Frontend development
cd frontend && npm run dev

# Build debug versions with AddressSanitizer
make -C bpf debug

Key Resources

• CLAUDE.md - Project guidelines and architecture
• collector/DESIGN.md - Framework design details
• docs/why.md - Problem analysis and motivation

📄 License

MIT License - see LICENSE for details.

---

💡 The Future of AI Observability: As AI agents become more autonomous and capable of self-modification, traditional observability approaches become insufficient. AgentSight provides the independent, tamper-resistant monitoring foundation needed for safe AI deployment at scale.