trace-sdk 0.3.1

Local version control for AI agent behavior.

Trace

Trace is local version control for AI agent behavior. It captures structured agent runs, compares behavior across runs, and restores the configuration that produced a trusted run.

import trace_sdk as trace

@trace.track(agent="planner", config={"model": "mock-v1"})
def run_agent(request):
    tools = trace.wrap_tools({"lookup": lookup})
    result = tools["lookup"](request)
    trace.decision("lookup_done", status=result["status"])
    return result

Commands

trace log
trace show <id>
trace diff <id_a> <id_b>
trace diff <id_a> <id_b> --json
trace revert <id>
trace revert <id> --agent budget_agent
trace serve
trace clear

Runs are stored in .trace/runs/. Config restored by trace revert is stored in .trace/config.json.

Development

uv sync --extra dev
uv run pytest
uv run python examples/demo_agent.py --variant stable
uv run python examples/demo_agent.py --variant drift
uv run trace log

TraceHub lives in tracehub/. Build it with npm install && npm run build; trace serve serves the built assets from tracehub/dist.