Transport & Batching

How events get from your agent to the backend — reliably and efficiently.

Overview

The Transport class handles all HTTP communication between the SDK and the backend. It's designed for reliability and minimal overhead:

Batching: Events are buffered and sent in batches to reduce HTTP overhead
Background flushing: A daemon thread periodically flushes the buffer
Retry with backoff: Failed sends are retried with the events re-queued
Bounded buffer: Hard cap (5000 events) prevents unbounded memory growth
Thread-safe: All buffer operations are protected by a lock

Configuration

When using agentlens.init(), the transport is created with defaults. For custom configuration, create a Transport directly:

from agentlens.transport import Transport
from agentlens.tracker import AgentTracker

transport = Transport(
    endpoint="http://localhost:3000",  # Backend URL
    api_key="my-key",                 # Sent as X-API-Key header
    batch_size=10,                    # Flush every N events
    flush_interval=5.0,               # Or every N seconds
    max_retries=3,                    # Retry failed sends N times
)

tracker = AgentTracker(transport=transport)

Parameter	Type	Default	Description
`endpoint`	`str`	`"http://localhost:3000"`	Backend URL (trailing slash is stripped)
`api_key`	`str`	`"default"`	API key for the `X-API-Key` header
`batch_size`	`int`	`10`	Flush when buffer reaches this size
`flush_interval`	`float`	`5.0`	Background flush interval in seconds
`max_retries`	`int`	`3`	Max consecutive failures before dropping events

Flush Behavior

Events are flushed (sent to the backend) when either condition is met:

The buffer reaches batch_size events
The background thread timer fires (every flush_interval seconds)
transport.flush() or agentlens.end_session() is called explicitly

⚠️ Process exit

If your process exits without calling end_session(), events still in the buffer may be lost. The background flush thread is a daemon thread — it won't keep the process alive.

Retry Logic

When a flush fails (HTTP error or network issue):

The events are prepended back into the buffer (preserving any events that arrived during the HTTP call)
A consecutive failure counter is incremented
If failures exceed max_retries, the events are dropped and a warning is logged
The counter resets on any successful flush

Buffer Overflow Protection

If the backend is down for an extended period, events buffer up. To prevent unbounded memory growth, the buffer is hard-capped at 5000 events. When this limit is exceeded, the oldest events are dropped.

# This is handled automatically — you don't need to do anything.
# If it happens, you'll see this in logs:
# WARNING agentlens.transport - Event buffer exceeded 5000 entries; dropped 42 oldest events

Graceful Shutdown

Call transport.close() (or agentlens.end_session()) for a clean shutdown:

# This happens automatically when you call end_session()
# For manual control:
transport.flush()   # Send all buffered events
transport.close()   # Flush + stop background thread + close HTTP client

Tuning Tips

💡 High-throughput agents

If your agent generates many events rapidly, increase batch_size to 50-100 to reduce HTTP requests. Each request sends all buffered events in one POST.

💡 Low-latency dashboards

If you need events to appear on the dashboard immediately, decrease flush_interval to 1.0 seconds. This increases HTTP traffic but reduces the delay between event creation and visibility.