TypeScript SDK

Send spans from Node.js / TypeScript agents to a local tj serve over HTTP.

The TypeScript SDK is a thin client that builds spans and POSTs them to a running tj serve. It’s the fastest path to instrument a JS/TS agent.

Install

npm install @tokenjam/sdk

Start the local server alongside your agent:

tj serve

Usage

import { TjClient, SpanBuilder } from "@tokenjam/sdk";

const client = new TjClient({
  baseUrl:      "http://127.0.0.1:7391",
  ingestSecret: process.env.TJ_INGEST_SECRET ?? "",
});

const span = new SpanBuilder("invoke_agent")
  .agentId("my-ts-agent")
  .model("gpt-4o-mini")
  .provider("openai")
  .inputTokens(450)
  .outputTokens(120)
  .build();

await client.send([span]);

The TJ_INGEST_SECRET is generated by tj onboard and stored in your config. tj doctor will print it.

Span fields

SpanBuilder supports the OTel GenAI SemConv attributes plus TokenJam extensions:

  • .agentId(string): required. Maps to service.name.
  • .model(string): required for cost calculation.
  • .provider(string): openai, anthropic, google, bedrock, etc.
  • .inputTokens(number) / .outputTokens(number)
  • .toolName(string): for tool-call spans.
  • .parentSpanId(string): link to a parent span.
  • .sessionId(string): group spans into a session.
  • .error(string): record a failure.

Spans are validated against the GenAI SemConv schema on ingest. Malformed spans surface as warnings in tj doctor.

Coming soon

Framework patches for LangChain JS, OpenAI Agents SDK (TypeScript), Vercel AI SDK, and Mastra are on the Roadmap.