TracerYX Python SDK

TracerYX traces agent runs and enforces an authenticated boundary policy before tools send data. It supports Python 3.9+ without required framework dependencies.

Install

pip install traceryx

Trace and guard

from traceryx import TracerYX

tracer = TracerYX(
    api_key="console-issued-org-key",
    endpoint="https://console.example.com",
    agent_name="support-agent",
)

def send(payload):
    return {"sent": True}

run = tracer.run(input={"request": "resolve delayed shipment"})
with run:
    with run.tool("lookupCustomer", input={"customerId": "cust-2048"}) as span:
        span.set_output({"status": "delayed"})
    result = tracer.guard(
        send,
        {"email": "alice@example.com", "summary": "refund issued"},
        tool_name="sendResolution",
        destination="support.traceryx.local",
    )
    run.set_output(result)

packet = run.seal()
tracer.shutdown()

The run context enqueues its root event on exit. Call run.seal() afterward; sealing flushes that run and returns the evidence packet, or None if the run is incomplete or delivery failed.

The guard fetches policy on demand and caches it for no more than 60 seconds. Enforce mode blocks before invocation and raises PolicyStopped, or passes a transformed copy for redact/hash decisions. Shadow mode records the would-be decision and passes the original payload. PolicyUnavailable is raised when fresh policy cannot be authenticated or validated, including when telemetry is disabled.

Use async with tracer.run(), await tracer.aguard(...), run.aseal(), tracer.aflush(), and tracer.ashutdown() for async code. trace_agent and trace_tool decorators preserve sync and async callables. A traced tool used outside a run behaves as a no-op wrapper.

Privacy and delivery

privacy="redacted" is the default. privacy="full" explicitly permits input/output capture, while sensitive metadata and user exception messages still stay out of events. privacy="hash_only" (also accepted as "hash-only") emits fingerprints for input/output values. Inputs are copied and never mutated for telemetry.

Redaction is heuristic and cannot guarantee detection of every secret. It covers sensitive dictionary keys, email, card, SSN, Bearer/JWT/token/private-key patterns, nested containers, cycles, depth, item counts, and long strings.

The bounded background queue defaults to 1,000 events. It sends gzip batches of up to 100 events and 1 MiB, retries only network/408/429/5xx failures with exponential jitter, respects Retry-After, and disables telemetry after a 401. flush() and shutdown() return False on loss or timeout without raising into application code. Counters are available at tracer.counters.

Only localhost may use HTTP. Redirects are never followed, preventing API credentials from being forwarded.

Integrations

TracedOpenAI explicitly wraps an existing OpenAI client and instruments chat.completions.create without a global monkeypatch:

from openai import OpenAI
from traceryx.integrations.openai import TracedOpenAI

openai = TracedOpenAI(OpenAI(), tracer)
with tracer.run():
    response = openai.chat.completions.create(
        model="gpt-4.1-mini",
        messages=[{"role": "user", "content": "Hello"}],
    )

Pass TracerYXCallbackHandler(tracer) in LangChain callback configuration. Framework packages are optional: install traceryx[openai] or traceryx[langchain].

examples/deterministic_agent.py is an externally instrumented tool-using loop without a paid model. It verifies tracing and policy integration, not live model-provider behavior.