GitHubBook a demoStart routing
Browse docs

SDK overview

What the Python and TypeScript instrumentation SDKs add over the base-URL swap — trace/agent tagging and typed, honest receipts — and when to reach for one.

On this page

The base-URL swap already gets you routing and the x-tt-* receipt headers on every response. The SDKs are an optional convenience layer on top: they emit the trace headers for you, read back a typed receipt, and never fabricate a dollar. Both bindings — Python and TypeScript — implement the same contract against a shared byte-equality conformance corpus.

What the SDK adds

Over a plain base-URL swap, the SDK gives you:

  1. Header emission — a deterministic, charset-guarded, byte-capped x-tt-* map from the ambient context; it never throws (it coerces-or-drops).
  2. Context/identity scopes — mint and propagate x-tt-trace-id/step-id/parent-id across async boundaries (Python contextvars; TypeScript AsyncLocalStorage).
  3. Agent & dimension tagging in one place — the same wire columns the dashboard filters on.
  4. Typed receipt read-back — an immutable Receipt with mode / decision / cache / refusal / model-rewrite, and a deep link to the ledger record.
  5. Auto-injecting, origin-scoped transport — Python httpx/requests adapters, a TS fetch/wrapFetch — that never touch the body, method, URL, or auth.
  6. An exporter seam, a first-run doctor (check()), a ledger pull + feedback write to your own admin plane, and framework adapters (Python: LangChain, CrewAI, OTel; TS: OTel).
  7. Zero runtime dependencies, never-throws, no phone-home — the core opens no sockets; only the lazily-imported admin transport talks to your admin plane.
What the SDK adds: headers out, a typed receipt back, the dollar pulledYour agent plus the SDK emits x-tt-* headers to the data plane on port 8787, which forwards byte-faithfully to the upstream provider (headers stripped) and stamps an x-tt-request-id on the response. The SDK parses a typed receipt whose cost is always null in v1, then ledger.fetch(req_id) reads the honest dollar from the decision ledger via the admin plane on port 9090. The SDK forwards and reads; it never computes a price.Your agent+ TokenTriage SDKpython / typescriptData plane127.0.0.1:8787byte-faithful proxyUpstreamprovideremits x-tt-*forward · strippedresp + x-tt-request-idTyped Receiptcost = null (v1)carries req_idAdmin plane127.0.0.1:9090your deployment onlyDecision ledgerdecisions.jsonlthe honest dollartt.receipt(resp)ledger.fetch(req_id)readsThe SDK forwards and reads — it never computes a price client-side

When to use it

  • Reach for the SDK when you control the HTTP client and want per-step / per-agent attribution, typed receipts, or the ledger pull — especially in framework code (LangGraph, CrewAI, custom agents).
  • Skip it when a plain base-URL swap is enough (you just want costing and routing), or for Claude Code, where wrap already injects a per-session trace header.