Agent turn reconstruction
Reconstructs multi-call agent activity into addressable turns so you can inspect the planner, tool calls, results, and follow-up actions together instead of as isolated HTTP requests.
Heron
Heron is a passive observability tool for AI agents and LLM APIs. It reconstructs agent turns, tool calls, and LLM interactions from network traffic without SDK changes or an in-path proxy.
Overview
Heron is a passive observability tool for AI agents and LLM APIs. It reconstructs agent turns, tool calls, and LLM interactions from network traffic so you can inspect performance without adding an SDK, proxy, or in-path instrumentation.
The product is designed for provider-side deployment where traffic is already decrypted, or for supported capture modes such as `.pcap` replay, live interface capture, ZMQ ingestion from cloud-probe, and an experimental Linux eBPF source for on-host TLS capture. The homepage positions it as a way to understand how agent workloads behave while keeping the observer out of the request path.
Heron also turns observed traffic into operational views: live metrics, topology graphs, and exportable turn data for training workflows. The docs and homepage describe use with OpenAI, Anthropic, Gemini, Claude Code, Codex CLI, and related agent traffic, while emphasizing that it works from the traffic itself rather than client-side integrations.
Core capabilities
Passive performance monitoring
Shows live metrics such as TTFT, latency, throughput, error rate, and per-agent mix from traffic reconstructed off the wire.
Multiple capture modes
Ingests traffic from a live network interface, a `.pcap` file, ZMQ cloud-probe input, or an experimental Linux eBPF source for on-host encrypted capture.
Service topology view
Classifies service topology from observed bytes on the wire and renders the inference fleet as a directed graph, including endpoints such as vLLM, SGLang, Ollama, llama.cpp, and LiteLLM.
Turn export for SFT
Exports agent turns or sessions as OpenAI-style messages JSONL for fine-tuning workflows, with tool calls, results, and reasoning preserved when supported by the wire format.
Agent and API decoding
Supports named profiles for Claude Code and OpenAI Codex CLI, plus a generic profile for other agents, and decodes OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Gemini AI Studio traffic.
Practical use cases
Debug agent behavior
Inspect individual agent runs as reconstructed turns so you can see the sequence of tool calls, LLM messages, and results that produced an outcome.
Track API performance
Monitor latency, TTFT, throughput, and error rate from provider-side traffic without modifying the clients that send requests.
Post-mortem analysis
Replay captured traffic from a `.pcap` file to analyze a past incident or review agent timelines after the live event has ended.
Understand service topology
Map an inference environment into a service graph to understand how clients, proxies, and backends such as vLLM or SGLang relate to one another.
Build fine-tuning datasets
Export observed turns as OpenAI-style JSONL when you want training data with tool calls and results preserved in a structured format.
Pros and Cons
Pros
- Works without SDK changes or workload cooperation, because it observes traffic passively.
- Can reconstruct full agent turns rather than leaving you with isolated HTTP calls.
- Supports live capture, pcap replay, cloud-probe ingestion, and an experimental eBPF source.
- Provides operational views such as live metrics, topology graphs, and exportable turn data.
- Can keep the console available after a pcap replay finishes, which is useful for inspection and batch workflows.
Cons
- Some capture modes depend on Linux-specific capabilities, such as CAP_NET_RAW for live interface capture or CAP_BPF for the experimental eBPF source.
- The homepage notes that the eBPF capture path is experimental and opt-in.
- The product is built around traffic that is already decrypted or otherwise observable; it is not described as a client-side SDK or in-path proxy.
FAQ
How does Heron collect traffic?
Heron is designed to observe traffic after it has already been decrypted or captured, so it does not sit in the request path. The docs describe live interface capture, replay from `.pcap` files, ZMQ ingestion from cloud-probe, and an experimental Linux eBPF source for on-host encrypted capture.
Which model and agent APIs does Heron support?
The homepage and docs describe support for OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Gemini AI Studio. The homepage also says it measures performance of OpenClaw, Claude, Codex, DeepAgents, and more.
Can Heron be used for offline replay or batch runs?
Heron can replay a `.pcap` file and keep the API and console available after replay finishes, or exit as soon as the pipeline drains with `--exit-after-drain`. The docs also note `--no-retention` for batch or CI runs when imported timestamps are older than the retention window.
What does Heron cost?
Heron is a GitHub repository and the site does not describe a separate commercial pricing page for Heron itself. The only pricing information in the provided sources is GitHub’s own plans page, which is unrelated to Heron’s licensing or support model.
Are there any platform or deployment constraints?
The homepage says Heron can run with no SDK changes and no proxy, and the docs mention Linux live capture, pcap replay, cloud-probe ingestion, and an experimental Linux eBPF source. Some deployment modes are Linux-specific or opt-in, so supported setups depend on the capture path you choose.
Quick Facts
- Category
- Developer Tool / AI Observability
- Primary use
- Passive monitoring of agent and LLM API traffic
- Deployment style
- Provider-side or on-host capture, no SDK changes required
- Supported sources
- Live interface, `.pcap`, cloud-probe ZMQ, experimental Linux eBPF
- Source domain
- github.com
- Project type
- Open-source GitHub repository
Heron Alternatives
AakarDev AI
AakarDev AI helps teams manage AI provider access, project setup, logs, and analytics in one dashboard. BYOK support included.
ByteAsk
ByteAsk is a terminal-first AI coding agent for C and C++ that edits repos and verifies changes with compilers, debuggers, sanitizers, and tests.
PromptScout
PromptScout tracks how ChatGPT, Gemini, Google AI Overviews, and Perplexity mention your brand or competitors, with source analysis and website audits.
CreateOS Sandbox
CreateOS Sandbox is an isolated compute environment for running code and agent workloads in Firecracker micro-VMs with private networking and SDK, CLI, or MCP control.
Sleek Analytics
Sleek Analytics is a privacy-friendly web analytics tool with real-time visitor tracking, Core Web Vitals, and revenue attribution.
hob
hob is an independent workspace for coding agents, with local control over sessions, terminals, history, routing, and follow-up work.