The EvalShift capture SDK installs inside your agent’s process and records what it actually does — model calls, tool calls, retrievals — then writes a CLI-valid trace to disk. It turns real production behavior into the source side of a migration suite, instead of hand-authoring JSONL traces.

It is a separate package from the CLI. The two never call each other: the SDK writes capture files, the CLI reads them.

## Install

The distribution is evalshift-sdk; the import name is evalshift (so the public API reads from evalshift import capture). It needs Python 3.10+ and has no required runtime dependencies — stdlib only, so it stays light enough to embed in any agent.

# uv (recommended)
uv add evalshift-sdk

# or pip
pip install evalshift-sdk

## Quickstart

Decorate your agent entry point. That’s the whole integration for a simple agent:

from evalshift import capture

@capture.agent(suite="support_agent")
def handle_ticket(query: str) -> str:
    ...  # your agent: model calls, tools, retrieval

handle_ticket("my refund hasn't arrived")

## Off by default

Capture is off unless EVALSHIFT_CAPTURE is set to a truthy value (1, true, yes, or on). With the gate off every entry point is a thin pass-through — zero files, zero overhead — so it is safe to leave the decorators in production code and flip the gate only where you want traces. The gate is re-read at every call, not frozen at decoration time, so enabling EVALSHIFT_CAPTURE after import works.

# nothing is recorded unless the gate is on
EVALSHIFT_CAPTURE=1 python run_agent.py
# -> .evalshift/captures/support_agent/cap_<id>.json

From here, see Instrumenting agents for tools, model calls, and async; Redaction for masking PII before it hits disk; and Config, sinks & hygiene for where files go and how the firehose self-manages.

## What ships today

The capture core (sync + async, sinks, redaction, hygiene) is shipped, along with:

• +The LangChain adapter — zero-instrument capture via a callback handler. See Framework adapters.
• +Capture lifecycle in the CLI — evalshift capture list / promote / clean / diff turns a capture into a golden suite case. See Captures → golden cases.
• +Suites from captures — the end-to-end capture → promote → run loop.
• +Schema migration — upgrade-on-read loaders keep schema_version 1.0.0 captures promotable under future versions.

## Roadmap

Still planned but not built yet:

• +More framework adapters — LlamaIndex and the OpenAI Agents SDK.