toolsnap 0.1.0

Record and replay LLM agent tool calls for deterministic testing

toolsnap

Zero dependency python decorator. Record your LLM agent's tool calls once. Replay them deterministically in every test run — no API keys, no network.

Why toolsnap?

LLM agents are non-deterministic at the model level, but their tool call trajectory i.e. which tools they call, in what order, with what arguments is the real testable surface. Existing approaches either hit live APIs on every test run (slow and expensive) or require writing brittle mocks upfront (tedious and disconnected from real behavior).

toolsnap takes a different approach: record first, assert after. Run your agent once against the real APIs, capture every tool call to a JSONL fixture, then replay that fixture in CI forever deterministically, offline, without credentials.

---

Installation

pip install toolsnap

Quick Start

Step 1: Decorate your tool with @snap

from toolsnap import snap
from strands import tool

@tool
@snap   # auto-saves to fixtures/search.jsonl
def search(query: str) -> list[str]:
    """Search the document store."""
    return real_search_api(query)

Step 2: Run your agent once to record real calls

python main.py
# fixtures/search.jsonl written

Step 3: Replay in tests with @replay

from toolsnap import replay
from strands import tool

@tool
@replay   # reads from fixtures/search.jsonl — no API call
def search(query: str) -> list[str]:
    """Search the document store."""
    ...

# No LLM API key. No database connection. The fixture drives everything.
pytest test.py   # fast, offline, deterministic