TanStack AI

About the TanStack AI integration

@telemetry-dev/tanstack-ai is a chat() middleware. Each chat() call becomes its own OpenTelemetry trace: a root span (chat, or invoke_agent once tools are used), a chat span per agent-loop iteration, and an execute_tool span per tool call. Conversations are correlated through gen_ai.conversation.id — lifted from metadata.sessionId, falling back to the chat's threadId.

Key features

• Add one middleware: Drop telemetryDev() into the middleware array and every run streams to telemetry.dev.
• Full token breakdowns: Input/output per iteration plus cache-read, cache-write, and reasoning tokens; when the adapter reports no cost, it's computed server-side from pricing tables.
• Tool calls captured: Arguments and results per tool call, with failed calls recording an exception event.
• Concurrency-safe by design: One telemetryDev() instance at module scope handles overlapping chat() calls; per-run state is keyed by middleware context.
• Errors still flush: Runs that error or abort close their open spans with error status — instrumentation can never break your chat.

Get started

import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import { telemetryDev } from "@telemetry-dev/tanstack-ai";

const stream = chat({
  adapter: openaiText("gpt-4o"),
  messages,
  metadata: { userId: "u_123", sessionId: "s_456" },
  middleware: [telemetryDev()],
});

Set TELEMETRY_DEV_API_KEY and you're done — no key means the middleware is a complete no-op. On serverless platforms, pass telemetryDev({ waitUntil: (p) => ctx.waitUntil(p) }) so the flush outlives the response. Requires @tanstack/ai >= 0.28.0.