Tool tracking
After init(), the SDK patches document.modelContext.registerTool. Each tool you register is wrapped so that every call to its execute function is timed and recorded. Your tool still receives the same input and returns the same result.
What is recorded
| Event | Sent when | Contains |
|---|---|---|
tool_call | Every execute() | Tool name, status (success, error or cancelled), duration, arguments, page URL |
tool_registered / tool_unregistered | A tool is added or removed | The tool's descriptor |
tools_snapshot | The set of tools changes | Every tool's name, description, input schema and annotations |
custom | You call AgentStats.track() | Event name and props. See Conversions |
Snapshots power schema-change alerts: if you change a tool's description or add a parameter, the dashboard shows the diff.
Sessions
An agent session is a run of tool calls without a gap longer than sessionTimeoutMs (30 minutes by default). Sessions let you see multi-step workflows and build funnels such as search_products → add_to_cart → checkout.
Tools registered before init
If a tool is registered before init() runs, for example by a third-party script, wrap it yourself:
document.modelContext.registerTool(AgentStats.wrap(myTool))
You can also turn off automatic patching with autoInstrument: false and wrap only the tools you want.
Other methods
| Method | What it does |
|---|---|
AgentStats.init(options) | Start the SDK. Call once. |
AgentStats.wrap(tool) | Return an instrumented copy of a tool. |
AgentStats.track(name, props?) | Record a custom event. |
AgentStats.flush() | Send queued events now. Returns a promise. |
AgentStats.snapshot() | Return the current tool descriptors. |
AgentStats.getClient() | Return the client instance, or null before init(). |
Events are batched and sent every 2 seconds. When the page is hidden or closed, the queue is sent with sendBeacon so nothing is lost on navigation.