📸 Agent Trace Format

A normalized JSON shape for capturing one agent run — input, tool calls, output, and a fingerprint. Used by agentsnap to diff runs and detect silent regressions.

Full example

{
  "version": 1,
  "model": "claude-sonnet-4-6",
  "input": "search for python tutorials",
  "output": "Here are 3 results.",
  "tools": [
    { "name": "web_search", "args": { "q": "python tutorials" }, "result_hash": "abc123" },
    { "name": "fetch_page", "args": { "url": "https://example.com" }, "result_hash": "def456" }
  ],
  "error": null,
  "fingerprint": { "node": "20.0", "agentsnap": "0.1.0" }
}

Fields

Field	Type	Notes
`version`	int	Schema version. Currently `1`.
`model`	string	Model identifier. Used to skip diffs across model upgrades.
`input`	string	The user prompt that started the run.
`output`	string	Final agent response.
`tools`	array	Ordered list of tool calls. Each entry is `{name, args, result_hash}`.
`tools[].name`	string	Tool identifier (dotted path like `filesystem.read_file`).
`tools[].args`	object	Args passed to the tool. Recorded literally.
`tools[].result_hash`	string	Hash of the tool's return value. Avoid storing PII / large payloads in the trace.
`error`	string \\| null	Run-level error message, if the run failed.
`fingerprint`	object	Environment metadata. `node` + `agentsnap` version are recommended; add your own keys.

Why hash the tool result?

Tool results are often large (files, API payloads, search results). Hashing keeps the trace small and avoids leaking PII into your snapshot store. The hash is enough to detect "the result changed" — for "how did it change?", re-run with full payloads enabled.

Diffing two traces

from agentsnap import diff

result = diff(baseline_trace, current_trace)
print(result.status)    # "match" | "drift" | "regression"
for change in result.changes:
    print(change.path, change.from_, "→", change.to)

Sample traces

The agent-trace-samples dataset has 10 example traces (good + regressed pairs) you can drop into your tests.