TypeSafe AI

TypeSafe AI answers typed questions about a piece of state — yes/no, scores, and labeled choices — through its systemOne API, returning answers whose TypeScript types are inferred from the questions you ask. Arize AX captures every call through the @arizeai/openinference-instrumentation-typesafe instrumentor, which emits one OpenInference LLM span per TypeSafeClient.systemOne call with the request and answers as JSON, the resolved model, and token usage.

This is the TypeScript / JavaScript guide. For the Python instrumentor, see TypeSafe AI.

client.models.list() is not instrumented — only systemOne produces spans. SDK retries are folded into one span rather than emitting a span per attempt.

Prerequisites

Node.js 20+
@typesafe-ai/sdk 0.6.0 or newer — the range the instrumentor patches
An Arize AX account (sign up)
A TYPESAFE_API_KEY from TypeSafe AI

Launch Arize AX

Sign in to your Arize AX account.
From Space Settings, copy your Space ID and API Key. You will set them as ARIZE_SPACE_ID and ARIZE_API_KEY below.

Install

npm install @typesafe-ai/sdk tsx typescript \
  @arizeai/openinference-instrumentation-typesafe \
  @arizeai/openinference-semantic-conventions \
  @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/resources \
  @opentelemetry/sdk-trace-base \
  @opentelemetry/sdk-trace-node \
  @opentelemetry/semantic-conventions

Configure credentials

export ARIZE_SPACE_ID="<your-space-id>"
export ARIZE_API_KEY="<your-api-key>"
export ARIZE_PROJECT_NAME="typesafe-tracing-example"
export TYPESAFE_API_KEY="<your-typesafe-api-key>"

Setup tracing

Register a NodeTracerProvider that ships spans to Arize AX, then hand it to TypeSafeInstrumentation and patch the SDK with manuallyInstrument.

// instrumentation.ts
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
import * as TypeSafe from "@typesafe-ai/sdk";
import {
  TypeSafeInstrumentation,
} from "@arizeai/openinference-instrumentation-typesafe";
import {
  SEMRESATTRS_PROJECT_NAME,
} from "@arizeai/openinference-semantic-conventions";

const projectName =
  process.env.ARIZE_PROJECT_NAME ?? "typesafe-tracing-example";

export const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: projectName,
    [SEMRESATTRS_PROJECT_NAME]: projectName,
  }),
  spanProcessors: [
    new SimpleSpanProcessor(
      new OTLPTraceExporter({
        url: "https://otlp.arize.com/v1/traces",
        headers: {
          "arize-space-id": process.env.ARIZE_SPACE_ID ?? "",
          "arize-api-key": process.env.ARIZE_API_KEY ?? "",
        },
      }),
    ),
  ],
});

provider.register();

const instrumentation = new TypeSafeInstrumentation({
  tracerProvider: provider,
});

instrumentation.manuallyInstrument(TypeSafe);

console.log("Arize AX tracing initialized for TypeSafe AI.");

manuallyInstrument(TypeSafe) patches TypeSafeClient.prototype, so it covers ESM, bundlers, and modules imported before the instrumentor was enabled — import instrumentation.ts first and the rest of your code can keep importing TypeSafeClient normally. On CommonJS you can instead let Node’s require hook patch the SDK, by installing @opentelemetry/instrumentation and passing the instrumentor to its registerInstrumentations({ instrumentations: [instrumentation] }) in place of the manuallyInstrument call. That path only works when instrumentation.ts runs before the SDK is required, which is why the snippet above uses manuallyInstrument.

Run TypeSafe AI

// example.ts

// Importing instrumentation first ensures tracing is set up before the
// TypeSafe client is used.
import { provider } from "./instrumentation";

import { choice, TypeSafeClient } from "@typesafe-ai/sdk";

// The client reads TYPESAFE_API_KEY from the environment and defaults to
// the jev-latest model.
const client = new TypeSafeClient();

const { data } = await client
  .systemOne({
    state: { document: "I was charged twice. Please fix this ASAP." },
    questions: {
      category: choice("What is this ticket about?", {
        billing: null,
        technical: null,
        other: null,
      }),
    },
  })
  .withResponse();

console.log(data.answers.category.choice, data.answers.category.confidence);

// Flush any pending spans before the process exits.
await provider.forceFlush();

Run the example with npx tsx example.ts. The instrumented systemOne still returns an SDK APIPromise, so await, withResponse(), and map() behave exactly as they do without tracing.

Expected output

Arize AX tracing initialized for TypeSafe AI.
billing 1

Verify in Arize AX

Open your Arize AX space and select project typesafe-tracing-example.
You should see a new trace within ~30 seconds containing a single TypeSafeClient.systemOne LLM span. Its input is the JSON request (state plus questions), its output is the JSON result (model, answers, usage), and it carries llm.request.model_name (jev-latest, which this instrumentor fills in from the client default when the call omits model), llm.response.model_name (the resolved version, for example jev-1.13.0), and prompt, completion, and total token counts.
If no traces appear, see Troubleshooting.

Check from the skill, CLI, or SDK

Confirm spans are actually reaching your Arize AX project. Use whichever fits your workflow — the skill and CLI work for any framework; the SDK check is shown for each language.

Arize skill (agent)
AX CLI
SDK

Install the Arize Skills plugin and let your coding agent check for you:

npx skills add Arize-ai/arize-skills

Then prompt your agent:

Use the arize-trace skill to export and analyze recent traces from my project. Confirm spans are arriving, and summarize any errors or latency issues.

Export recent spans for your project — any rows mean traces are landing:

ax spans export "$ARIZE_PROJECT_NAME" --space "$ARIZE_SPACE_ID" \
  --limit 5 --stdout | jq 'length'

A non-zero count confirms spans reached Arize AX. Run ax auth login first if you have not authenticated. See the ax spans reference.

Query the project’s spans and check that at least one came back.

import os
from arize import ArizeClient

client = ArizeClient(api_key=os.environ["ARIZE_API_KEY"])
resp = client.spans.list(
    project=os.environ["ARIZE_PROJECT_NAME"],
    space=os.environ["ARIZE_SPACE_ID"],
    limit=5,
)
count = len(resp.spans)
print(
    f"{count} span(s) found" if count else "No spans yet — recheck setup"
)

// Reads ARIZE_API_KEY from the environment.
import { listSpans } from "@arizeai/ax-client";

const { data: spans } = await listSpans({
  project: process.env.ARIZE_PROJECT_NAME!,
  space: process.env.ARIZE_SPACE_ID!,
  limit: 5,
});
const count = spans.length;
console.log(
  count ? `${count} span(s) found` : "No spans yet — recheck setup",
);

client, err := arize.NewClient(
    arize.Config{APIKey: os.Getenv("ARIZE_API_KEY")},
)
if err != nil {
    log.Fatal(err)
}
resp, err := client.Spans.List(ctx, spans.ListRequest{
    Project: os.Getenv("ARIZE_PROJECT_NAME"),
    Space:   os.Getenv("ARIZE_SPACE_ID"),
    Limit:   5,
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%d span(s) found\n", len(resp.Spans))

SDK span references: Python · TypeScript · Go.

Mask sensitive payloads

The request state is the document you are asking about, so it often carries customer data. Pass traceConfig to drop inputs, outputs, or both before the span leaves your process:

const instrumentation = new TypeSafeInstrumentation({
  tracerProvider: provider,
  traceConfig: {
    hideInputs: true,
    hideOutputs: true,
  },
});

Model name and token counts are still recorded, so cost and latency dashboards keep working with payloads masked. See the instrumentor README for the full list of masking options.

Troubleshooting

No traces in Arize AX. Confirm ARIZE_SPACE_ID and ARIZE_API_KEY are set in the same shell that runs example.ts. Enable OpenTelemetry debug logs with export OTEL_LOG_LEVEL=debug and re-run.
Spans missing but systemOne returns answers. manuallyInstrument(TypeSafe) must run before the first systemOne call, so instrumentation.ts has to be imported before any code that calls the SDK.
No span for models.list(). Expected — the instrumentor only wraps systemOne.
401 from TypeSafe. Verify TYPESAFE_API_KEY is set and valid; the client reads it from the environment unless you pass apiKey explicitly.
SDK fails to install or import. The TypeSafe SDK requires Node.js 20+. Check with node --version.
Process exits before spans flush. Spans are exported asynchronously; always await provider.forceFlush() (or provider.shutdown()) before the process exits.

OpenTelemetry

LLM Providers

Agent Frameworks

Coding Agents

Platforms

Orchestration

Evaluation

Prerequisites

Launch Arize AX

Install

Configure credentials

Setup tracing

Run TypeSafe AI

Expected output

Verify in Arize AX

Check from the skill, CLI, or SDK

Mask sensitive payloads

Troubleshooting

Resources

TypeSafe AI Documentation

OpenInference TypeSafe Instrumentor (JS/TS)

Runnable TypeSafe Tracing Examples

TypeSafe AI SDK on npm

TypeSafe AI (Python) tracing

​Prerequisites

​Launch Arize AX

​Install

​Configure credentials

​Setup tracing

​Run TypeSafe AI

​Expected output

​Verify in Arize AX

​Check from the skill, CLI, or SDK

​Mask sensitive payloads

​Troubleshooting

​Resources

TypeSafe AI Documentation

OpenInference TypeSafe Instrumentor (JS/TS)

Runnable TypeSafe Tracing Examples

TypeSafe AI SDK on npm

TypeSafe AI (Python) tracing

Prerequisites

Launch Arize AX

Install

Configure credentials

Setup tracing

Run TypeSafe AI

Expected output

Verify in Arize AX

Check from the skill, CLI, or SDK

Mask sensitive payloads

Troubleshooting

Resources