diff --git a/src/lib/integrations.mjs b/src/lib/integrations.mjs
index 122baba17..60ef42d0b 100644
--- a/src/lib/integrations.mjs
+++ b/src/lib/integrations.mjs
@@ -69,6 +69,7 @@ export const integrations = [
{ id: 'mcp', name: 'Model Context Protocol', href: '/docs/integrations/traceai/mcp', category: 'frameworks', summary: 'Trace MCP client and server interactions.', method: 'traceAI SDK', logo: 'mcp', aliases: ['MCP'] },
{ id: 'mastra', name: 'Mastra', href: '/docs/integrations/traceai/mastra', category: 'frameworks', summary: 'Trace TypeScript agents and workflows in Mastra.', method: 'traceAI SDK', logo: 'mastra' },
{ id: 'vercel-ai-sdk', name: 'Vercel AI SDK', href: '/docs/integrations/traceai/vercel', category: 'frameworks', summary: 'Capture model and tool calls from the Vercel AI SDK.', method: 'traceAI SDK', logo: 'vercel' },
+ { id: 'tanstack-ai', name: 'TanStack AI', href: '/docs/integrations/frameworks/tanstack-ai', category: 'frameworks', summary: 'Send otelMiddleware chat, model-call and tool spans from Node.js.', method: 'OpenTelemetry', logo: 'generic-framework', aliases: ['TanStack'] },
{ id: 'agentscope', name: 'AgentScope', href: '/docs/integrations/frameworks/agentscope', category: 'frameworks', summary: 'Export native agent, model and tool spans.', method: 'OpenTelemetry', logo: 'agentscope' },
{ id: 'apollo-graphql', name: 'Apollo Server', href: '/docs/integrations/frameworks/apollo-graphql', category: 'frameworks', summary: 'Trace GraphQL operations and resolvers in Server 4.', method: 'OpenTelemetry', logo: 'apollo', aliases: ['Apollo GraphQL'] },
{ id: 'embabel', name: 'Embabel', href: '/docs/integrations/frameworks/embabel', category: 'frameworks', summary: 'Export JVM agent spans with the observability starter.', method: 'OpenTelemetry', logo: 'embabel', aliases: ['Spring Boot', 'Java', 'Kotlin'] },
diff --git a/src/pages/docs/integrations/frameworks/tanstack-ai.mdx b/src/pages/docs/integrations/frameworks/tanstack-ai.mdx
new file mode 100644
index 000000000..0e195164a
--- /dev/null
+++ b/src/pages/docs/integrations/frameworks/tanstack-ai.mdx
@@ -0,0 +1,576 @@
+---
+title: "TanStack AI tracing with Future AGI"
+description: "Send the OpenTelemetry spans TanStack AI's own otelMiddleware creates to Future AGI with a tracer provider from @traceai/fi-core. Covers what is captured, the metadata-only default, the content opt-in, sessions, errors and apps that already run OpenTelemetry."
+---
+
+## About
+
+This page is for **TanStack AI**, the TypeScript AI framework from TanStack: npm package `@tanstack/ai` with provider adapters such as `@tanstack/ai-openai`, repository `TanStack/ai`, MIT. It covers server-side `chat()` calls in Node.js.
+
+TanStack AI creates OpenTelemetry spans itself. Its `otelMiddleware` (exported from `@tanstack/ai/middlewares/otel`, not from `@tanstack/ai`) opens a span for each `chat()` call, one per model call and one per tool call, and writes token usage onto the spans. It does not create a tracer provider or an exporter: you pass it a tracer. This recipe gets that tracer from [`@traceai/fi-core`](/docs/quickstart/setup-observability)'s `register()`, which exports to Future AGI, and wraps the middleware in one file, `tracing.mjs`, that sets Future AGI span kinds, counts tokens once, keeps error text and stack traces out of the spans, and can send a conversation id as the session. There is no `@traceai/tanstack-ai` package and you do not need one.
+
+This is not the [Vercel AI SDK integration](/docs/integrations/traceai/vercel), which traces `ai` (the Vercel package) through `@traceai/vercel`, and it is not the [OpenAI instrumentor](/docs/integrations/traceai/openai), which patches the OpenAI SDK client. TanStack AI's adapters call the provider themselves, so this recipe works at the level of `chat()` for every adapter. It does not use the OpenInference TanStack middleware that some other backends document; registering both would duplicate every span.
+
+
+This recipe is pinned to `@tanstack/ai` 0.69.0. It was run end to end against a self-hosted Future AGI stack with a real OpenAI model (`gpt-4o-mini`, 2026-10-17) and with a real model behind an OpenAI-compatible endpoint, using `@tanstack/ai-openai`'s `openaiChatCompletions` adapter. On 2026-10-29 the `tracing.mjs` and `route.mjs` on this page, installed fresh from the pins in step 1, answered a tool-calling question through an OpenAI-compatible endpoint, and the hosted `api.futureagi.com` endpoint accepted every exported span (HTTP 200). The verified scope is server-side Node.js with the OpenAI Chat Completions adapter; other adapters, browsers and edge runtimes are outside it.
+
+
+| | |
+| --- | --- |
+| Tested with | `@tanstack/ai` 0.69.0 (published 2026-10-13) with `@tanstack/ai-openai` 0.30.0, `@tanstack/openai-base` 0.14.0, `@opentelemetry/sdk-trace-node` 2.12.0. Also `@tanstack/ai` 0.64.0 with `@tanstack/ai-openai` 0.26.0 and the SDK at 2.11.0: `otelMiddleware` is byte-identical from 0.64.0 to 0.69.0. `@traceai/fi-core` 1.0.0, `@opentelemetry/api` 1.9.1. Node 22.18.0 and 26.8.1. |
+| Model | OpenAI `gpt-4o-mini` with a real key; a model behind an OpenAI-compatible endpoint (`OPENAI_BASE_URL`). The spans do not depend on the model. |
+| Future AGI | Self-hosted stack on localhost, 2026-10-16. Hosted `api.futureagi.com`, 2026-10-29: the four spans of a tool-calling run (chat root, two model calls, one tool call) were accepted with HTTP 200. |
+| Outside the verified scope | Adapters other than OpenAI Chat Completions, media activities (image, speech, transcription), browser packages (`@tanstack/ai-client`, React, Vue, Solid), TanStack sandbox and code-mode packages, Cloudflare and other edge runtimes, `chat({ stream: false })` (see [Limitations](#limitations)). |
+| TanStack source used | `otelMiddleware` and `usage-attributes` in the published 0.64.0 and 0.69.0 packages (`dist/esm/middlewares/`), read 2026-10-16. |
+| Source | The runnable example, the same `tracing.mjs`, and its contract tests are in [traceAI `typescript/examples/tanstack-ai`](https://github.com/future-agi/traceAI/tree/dev/typescript/examples/tanstack-ai). |
+
+## 1. Install
+
+```bash
+npm install @tanstack/ai@0.69.0 @tanstack/ai-openai@0.30.0 @traceai/fi-core@1.0.0 @opentelemetry/api@1.9.1
+```
+
+Then pin the SDK version the recipe was tested on, in your app's `package.json`:
+
+```json title="package.json"
+{
+ "overrides": {
+ "@opentelemetry/sdk-trace-node": "2.12.0",
+ "@tanstack/openai-base": "0.14.0"
+ }
+}
+```
+
+npm reads `overrides`; pnpm uses `pnpm.overrides` and Yarn `resolutions`. The recipe moves the chat span's summed usage by editing the SDK span's attributes object, which is not public OpenTelemetry API, so it is pinned to the versions it was tested on (2.11.0 and 2.12.0). TanStack's adapter packages move in lockstep with `@tanstack/ai`, so the `@tanstack/openai-base` pin keeps an install from mixing versions.
+
+## 2. Set environment variables
+
+```bash
+export FI_API_KEY="YOUR_API_KEY" # sent as X-Api-Key
+export FI_SECRET_KEY="YOUR_SECRET_KEY" # sent as X-Secret-Key
+export FI_PROJECT_NAME="my-chatbot" # the Observe project the traces land in
+# Self-hosted Future AGI only. Traces go to $FI_BASE_URL/tracer/v1/traces.
+# export FI_BASE_URL="http://localhost:4318" # default: https://api.futureagi.com
+export OPENAI_API_KEY="YOUR_OPENAI_KEY" # read by @tanstack/ai-openai
+```
+
+Set `FI_BASE_URL` to the origin only; `register()` adds `/tracer/v1/traces`. Keep every key on the server. Never import `tracing.mjs` into a browser bundle.
+
+## 3. Add the recipe file
+
+Save this as `tracing.mjs` (or `tracing.ts`, it is plain ES module JavaScript) next to your route code. It is the same file as the example's `src/tracing.mjs`.
+
+```js title="tracing.mjs"
+// Future AGI tracing for TanStack AI. This is a recipe, not a package:
+// TanStack AI's own otelMiddleware creates the spans, and @traceai/fi-core
+// only supplies the tracer provider and the exporter.
+import { SpanStatusCode } from "@opentelemetry/api";
+import { register, ProjectType } from "@traceai/fi-core";
+// otelMiddleware is exported from this subpath only, not from "@tanstack/ai"
+// (@tanstack/ai 0.64.0 to 0.69.0, src/middlewares/index.ts).
+import { otelMiddleware } from "@tanstack/ai/middlewares/otel";
+
+export const GEN_AI_SPAN_KIND = "gen_ai.span.kind";
+
+/**
+ * Register the Future AGI tracer provider.
+ *
+ * register() exports OTLP/HTTP to {FI_BASE_URL}/tracer/v1/traces, sends
+ * FI_API_KEY and FI_SECRET_KEY as the X-Api-Key and X-Secret-Key headers, and
+ * sets the project_name and project_type resource attributes the collector
+ * requires. A batch without project_name is dropped.
+ *
+ * `batch: true` is not passed: with @traceai/fi-core 1.0.0 on
+ * @opentelemetry/sdk-trace(-base) 2.11.0 it does not attach the batch
+ * processor, so spans go through register()'s default SimpleSpanProcessor.
+ *
+ * `setGlobalTracerProvider: false`: the recipe passes this provider's tracer
+ * to otelMiddleware, so it never needs the global provider, and leaving the
+ * global slot alone keeps an app's own OpenTelemetry setup (and its other
+ * spans) where it was. Removing the recipe is then dropping the middleware
+ * and calling shutdownTraces().
+ */
+export function registerFutureAgiTracing() {
+ return register({
+ projectType: ProjectType.OBSERVE,
+ projectName: process.env.FI_PROJECT_NAME ?? "tanstack-ai-example",
+ setGlobalTracerProvider: false,
+ });
+}
+
+function describe(error) {
+ const errors = Array.isArray(error) ? error : [error];
+ return errors.map((e) => e?.message ?? String(e)).join("; ");
+}
+
+/** How long the route waits for span export before it answers anyway. */
+export const FLUSH_TIMEOUT_MS = 2000;
+
+/**
+ * Wait for in-flight span exports, at most `timeoutMs`. Call it in the
+ * route's finally. Never throws: an unreachable collector is logged, and a
+ * collector that does not answer within the bound is logged and left to
+ * finish in the background (OTLP/HTTP gives up after its own 10 s timeout).
+ *
+ * This is for serverless routes, where the process may be frozen once the
+ * response is sent. In a long-lived server, do not await a flush on the
+ * request path at all: the SimpleSpanProcessor already exports each span when
+ * it ends, so call shutdownTraces() when the process stops instead.
+ */
+export async function flushTraces(tracerProvider, { timeoutMs = FLUSH_TIMEOUT_MS } = {}) {
+ let timer;
+ const timedOut = new Promise((resolve) => {
+ timer = setTimeout(() => resolve(true), timeoutMs);
+ timer.unref?.();
+ });
+ try {
+ const flushed = tracerProvider.forceFlush().then(() => false);
+ if (await Promise.race([flushed, timedOut])) {
+ console.error(
+ `[futureagi] span export still pending after ${timeoutMs} ms; not waiting`,
+ );
+ flushed.catch((error) => {
+ console.error(`[futureagi] span export failed: ${describe(error)}`);
+ });
+ }
+ } catch (error) {
+ console.error(`[futureagi] span export failed: ${describe(error)}`);
+ } finally {
+ clearTimeout(timer);
+ }
+}
+
+/** Stop the exporter at process exit (shutdown flushes first). Never throws. */
+export async function shutdownTraces(tracerProvider) {
+ try {
+ await tracerProvider.shutdown();
+ } catch (error) {
+ console.error(`[futureagi] tracer shutdown failed: ${describe(error)}`);
+ }
+}
+
+/**
+ * Future AGI span kinds for the spans otelMiddleware emits.
+ *
+ * Keyed on the middleware's span scope (`info.kind`), not on
+ * gen_ai.operation.name: at @tanstack/ai 0.64.0 only iteration spans carry
+ * gen_ai.operation.name ("chat"); the root and tool spans do not.
+ *
+ * - iteration (one provider model call) -> LLM
+ * - tool (one tool execution) -> TOOL
+ * - chat root that ran more than one iteration -> AGENT, else CHAIN
+ *
+ * The root's kind is set in onSpanEnd because attributeEnricher runs for the
+ * root when chat() starts, before the iteration count is known. A root with
+ * no kind would be stored by Future AGI as observation type "unknown". Media
+ * "generation" spans get no kind.
+ *
+ * Usage: TanStack sums every model call's gen_ai.usage.* keys onto the root
+ * (otel.ts applyRootUsage, set just before onSpanEnd): input, output and
+ * total tokens, cost, cache read/creation and reasoning tokens. Future AGI
+ * promotes gen_ai.usage.* (and gen_ai.cost.*) into its token and cost
+ * columns on any span and sums them over the whole trace, so leaving the
+ * root's copy would count each call twice. When the model-call spans carry
+ * usage, every gen_ai.usage. key on the root moves to
+ * tanstack.ai.root_usage., and every gen_ai.cost. key to
+ * tanstack.ai.root_usage.cost.. If no model-call span reported
+ * usage, the root keeps it, because then it is the only copy.
+ */
+const PROMOTED_PREFIXES = ["gen_ai.usage.", "gen_ai.cost."];
+
+function rootUsageKey(key) {
+ return key.startsWith("gen_ai.usage.")
+ ? `tanstack.ai.root_usage.${key.slice("gen_ai.usage.".length)}`
+ : `tanstack.ai.root_usage.${key.slice("gen_ai.".length)}`;
+}
+
+function moveRootUsage(span) {
+ // Internal dependency: OpenTelemetry has no public API to remove a span
+ // attribute. This edits the SDK span's `attributes` object, which the
+ // exporter reads at end(). Tested with @opentelemetry/sdk-trace 2.11.0
+ // (SpanImpl, reached through sdk-trace-node and sdk-trace-base 2.11.0,
+ // which package.json "overrides" pins). `delete` does not lower SpanImpl's
+ // private attribute count, so under a tight attributeCountLimit the
+ // tanstack.ai.root_usage.* copy can be dropped. The promoted key still
+ // leaves the root, so a trace's usage is never counted twice.
+ const attributes = span?.attributes;
+ if (!attributes) return;
+ for (const key of Object.keys(attributes)) {
+ if (!PROMOTED_PREFIXES.some((prefix) => key.startsWith(prefix))) continue;
+ const value = attributes[key];
+ delete attributes[key];
+ span.setAttribute(rootUsageKey(key), value);
+ }
+}
+
+export const SESSION_ID = "session.id";
+export const GEN_AI_PROVIDER_NAME = "gen_ai.provider.name";
+
+/**
+ * TanStack adapter name (`adapter.name`, which otelMiddleware copies to
+ * gen_ai.system) -> gen_ai.provider.name, the key fi-collector reads first for
+ * a span's provider. Names from the published adapters: openaiChatCompletions
+ * is "openai-chat", openaiText "openai", @tanstack/ai-gemini "gemini" and
+ * "gemini-text-interactions", @tanstack/ai-grok "grok". Any other adapter
+ * (OpenRouter, a custom one) leaves the provider unset. Future AGI prices a
+ * call from gen_ai.request.model and its tokens, not from the provider.
+ */
+const ADAPTER_PROVIDERS = {
+ openai: "openai",
+ "openai-chat": "openai",
+ anthropic: "anthropic",
+ gemini: "google",
+ "gemini-text-interactions": "google",
+ grok: "xai",
+ groq: "groq",
+ ollama: "ollama",
+};
+
+/**
+ * Span kinds, usage and session for the spans otelMiddleware emits.
+ *
+ * With `threadIdAsSession: true`, every span also gets
+ * session.id = ctx.threadId, the `threadId` the caller passed to chat().
+ * It is exported verbatim, so pass an opaque id (a UUID), never an email
+ * address or user name.
+ * Set it only when the caller passed one: chat() otherwise generates a
+ * fresh thread-- id per call, which would make every request its
+ * own session. @traceai/fi-core's setSession() only sets a context value;
+ * neither otelMiddleware nor the plain SDK tracer register()'s provider
+ * hands out reads it, so the recipe uses TanStack's own threadId instead.
+ */
+export function futureAgiSpanKinds({ threadIdAsSession = false, joinActiveTrace = false } = {}) {
+ const iterationsByRun = new WeakMap();
+ const usageOnIterations = new WeakSet();
+ // TanStack starts the chat root under the active OpenTelemetry context, so in
+ // an app with its own provider and context manager (an HTTP server span, a
+ // framework's own tracing) the root's parent is a span that is exported
+ // elsewhere. Future AGI then has no root for the trace, and the trace is
+ // missing from the Tracing list. The root starts a new trace unless the
+ // caller asks to join the active one (when that app's spans also go to
+ // Future AGI). Model-call and tool spans are parented explicitly by
+ // TanStack, so they follow the root either way.
+ const onBeforeSpanStart = joinActiveTrace
+ ? undefined
+ : (info, options) => (info.kind === "chat" ? { ...options, root: true } : options);
+ const kindAttributes = (info) => {
+ if (info.kind === "iteration") {
+ iterationsByRun.set(info.ctx, info.iteration + 1);
+ return { [GEN_AI_SPAN_KIND]: "LLM" };
+ }
+ if (info.kind === "tool") {
+ return { [GEN_AI_SPAN_KIND]: "TOOL" };
+ }
+ return {};
+ };
+ return {
+ ...(onBeforeSpanStart ? { onBeforeSpanStart } : {}),
+ attributeEnricher(info) {
+ const attributes = kindAttributes(info);
+ const adapter = info.ctx?.provider;
+ const provider = Object.hasOwn(ADAPTER_PROVIDERS, adapter) ? ADAPTER_PROVIDERS[adapter] : undefined;
+ if (provider && (info.kind === "chat" || info.kind === "iteration")) {
+ attributes[GEN_AI_PROVIDER_NAME] = provider;
+ }
+ if (threadIdAsSession && info.ctx?.threadId) {
+ attributes[SESSION_ID] = info.ctx.threadId;
+ }
+ return attributes;
+ },
+ onSpanEnd(info, span) {
+ if (info.kind === "iteration" && span?.attributes?.["gen_ai.usage.input_tokens"] !== undefined) {
+ usageOnIterations.add(info.ctx);
+ }
+ if (info.kind === "chat") {
+ span.setAttribute(GEN_AI_SPAN_KIND, (iterationsByRun.get(info.ctx) ?? 0) > 1 ? "AGENT" : "CHAIN");
+ if (usageOnIterations.has(info.ctx)) {
+ moveRootUsage(span);
+ }
+ }
+ },
+ };
+}
+
+export const ERROR_TYPE = "error.type";
+/** TanStack's own fixed status text for an aborted run; kept as is. */
+const CANCELLED = "cancelled";
+const REDACTION_FAILED = "[redaction_failed]";
+
+/** A provider error code (RUN_ERROR code, HTTP status) or the error's class name. */
+export function errorType(error) {
+ const code = error?.code;
+ if ((typeof code === "string" && code) || (typeof code === "number" && Number.isFinite(code))) {
+ return String(code);
+ }
+ const name = error?.name;
+ return typeof name === "string" && name ? name : "Error";
+}
+
+function errorText(error) {
+ if (typeof error === "string") return error;
+ const message = error?.message;
+ return typeof message === "string" ? message : undefined;
+}
+
+/**
+ * Wrap the tracer otelMiddleware uses, so error details are exported the way
+ * content is.
+ *
+ * otelMiddleware calls span.recordException(error) and sets the error's
+ * message as the span status whatever captureContent is. That text comes
+ * from the provider or from your tool, and the exception event carries the
+ * stack trace, with local file paths and the user name. Through this
+ * tracer:
+ *
+ * - a stack trace is never exported;
+ * - with content capture off (the default), the error's message is not
+ * exported either: the exception event keeps only exception.type, the
+ * span status message is that type, and the span gets error.type (the
+ * provider's error code, such as "400" or "context_overflow", or the
+ * error class name);
+ * - with captureContent: true, the message is exported, passed through the
+ * same `redact` as content (a redactor that throws yields
+ * "[redaction_failed]").
+ *
+ * Only the public Tracer and Span API is used: each span is the SDK span
+ * behind a Proxy that replaces recordException and setStatus.
+ */
+export function futureAgiErrorPrivacy(tracer, { captureContent = false, redact = (text) => text } = {}) {
+ const safeRedact = (text) => {
+ try {
+ return redact(text);
+ } catch {
+ return REDACTION_FAILED;
+ }
+ };
+ const wrap = (span) => {
+ let lastType;
+ const proxy = new Proxy(span, {
+ get(target, property) {
+ if (property === "recordException") {
+ return (exception, time) => {
+ lastType = errorType(exception);
+ target.setAttribute(ERROR_TYPE, lastType);
+ const text = captureContent ? errorText(exception) : undefined;
+ target.recordException(
+ text ? { name: lastType, message: safeRedact(text) } : { name: lastType },
+ time,
+ );
+ };
+ }
+ if (property === "setStatus") {
+ return (status) => {
+ let next = status;
+ if (
+ status?.code === SpanStatusCode.ERROR &&
+ typeof status.message === "string" &&
+ status.message !== CANCELLED
+ ) {
+ next = {
+ code: status.code,
+ message: captureContent ? safeRedact(status.message) : (lastType ?? "Error"),
+ };
+ }
+ target.setStatus(next);
+ return proxy;
+ };
+ }
+ const value = Reflect.get(target, property, target);
+ return typeof value === "function" ? value.bind(target) : value;
+ },
+ });
+ return proxy;
+ };
+ return {
+ startSpan: (name, options, context) => wrap(tracer.startSpan(name, options, context)),
+ startActiveSpan: (...args) => tracer.startActiveSpan(...args),
+ };
+}
+
+/**
+ * The one middleware to pass to chat().
+ *
+ * Content capture is off by default: no prompt, completion, system prompt,
+ * tool argument or result, and no error message, reaches a span, and a
+ * stack trace never does (see futureAgiErrorPrivacy).
+ *
+ * Options:
+ * - `threadIdAsSession: true` when this chat() call gets the caller's
+ * `threadId` (see futureAgiSpanKinds).
+ * - `captureContent: true` to opt in to message, tool and error text
+ * (TanStack's own option), with an optional `redact(text)`.
+ * - `joinActiveTrace: true` to keep TanStack's chat root under the app's
+ * active span (only when the app's own spans also go to Future AGI).
+ */
+export function futureAgiOtelMiddleware(
+ tracer,
+ { threadIdAsSession = false, captureContent = false, redact, joinActiveTrace = false } = {},
+) {
+ return otelMiddleware({
+ tracer: futureAgiErrorPrivacy(tracer, { captureContent, ...(redact ? { redact } : {}) }),
+ captureContent,
+ ...(redact ? { redact } : {}),
+ ...futureAgiSpanKinds({ threadIdAsSession, joinActiveTrace }),
+ });
+}
+```
+
+## 4. Trace a route
+
+Register the provider once per process, build the middleware per request, read `chat()`'s stream to the end, and flush in `finally`:
+
+```js title="route.mjs"
+import { chat, toolDefinition } from "@tanstack/ai";
+import { openaiChatCompletions } from "@tanstack/ai-openai";
+import {
+ flushTraces,
+ futureAgiOtelMiddleware,
+ registerFutureAgiTracing,
+} from "./tracing.mjs";
+
+// Once per process. register() reads FI_API_KEY, FI_SECRET_KEY, FI_BASE_URL.
+const tracerProvider = registerFutureAgiTracing();
+
+// A server tool, so a question about the weather produces a tool span.
+// Replace it with your own tools; each one that runs gets an execute_tool span.
+const getWeather = toolDefinition({
+ name: "get_weather",
+ description: "Get the current weather for a city.",
+ inputSchema: {
+ type: "object",
+ properties: { city: { type: "string" } },
+ required: ["city"],
+ },
+}).server(async ({ city }) => ({ city, forecast: "sunny", celsius: 21 }));
+
+// `signal` is the request's abort signal: `request.signal` in a Fetch API
+// handler, or an AbortController you abort on `res.on("close")` in node:http.
+export async function chatRoute(question, { threadId, signal } = {}) {
+ const middleware = futureAgiOtelMiddleware(
+ tracerProvider.getTracer("tanstack-ai"),
+ { threadIdAsSession: Boolean(threadId) },
+ );
+ // When the client disconnects, abort chat() so its spans end as cancelled
+ // and export. Without this chat() never learns the client left.
+ const abortController = new AbortController();
+ const abort = () => abortController.abort();
+ signal?.addEventListener("abort", abort, { once: true });
+ if (signal?.aborted) abort();
+ try {
+ let text = "";
+ let runError = null;
+ for await (const chunk of chat({
+ adapter: openaiChatCompletions(process.env.OPENAI_MODEL ?? "gpt-4o-mini"),
+ messages: [{ role: "user", content: question }],
+ tools: [getWeather],
+ middleware: [middleware],
+ abortController,
+ ...(threadId ? { threadId } : {}),
+ })) {
+ if (chunk.type === "RUN_ERROR") runError ??= chunk;
+ else if (chunk.type === "TEXT_MESSAGE_CONTENT") text += chunk.delta ?? "";
+ }
+ if (runError) throw new Error(runError.message);
+ return text;
+ } finally {
+ signal?.removeEventListener("abort", abort);
+ await flushTraces(tracerProvider); // waits at most 2 s, never throws
+ }
+}
+```
+
+Never stop reading the stream with a `break`, an early `return` or a dropped response body: TanStack ends its spans only when the run finishes, fails or is aborted, so the whole trace would be lost. Abort the `abortController` instead. When you stream to the client with `toServerSentEventsResponse(stream, { abortController })`, pass it the same controller you passed to `chat()`.
+
+In a long-lived server you can leave out the per-request flush (register()'s default `SimpleSpanProcessor` exports each span when it ends) and call `shutdownTraces(tracerProvider)` when the process stops. Keep the flush on serverless platforms, where the process can be frozen after the response.
+
+## 5. Run and check
+
+Call the route once with a question that makes the model use a tool, then open the project in Observe. A chat that called a tool looks like this:
+
+| Span | Type in Future AGI | What it carries |
+| --- | --- | --- |
+| `chat ` | agent (more than one model call) or chain | Request model, provider, `tanstack.ai.iterations`, finish reason, `session.id` when you pass a conversation id |
+| `chat #` | llm | Request and response model, provider, `gen_ai.usage.*` tokens (cache and reasoning tokens when the provider sends them), finish reason, `tanstack.ai.iteration`; Future AGI computes cost from model and tokens |
+| `execute_tool ` | tool | Tool name, call id, type, `tanstack.ai.tool.outcome`, `error.type` and ERROR status when the tool throws |
+
+A failed model call (a wrong model name, a provider outage) is an ERROR on the `chat #` span and on the root, with the provider's error code (`400`, `model_not_found`) as `error.type` and status message. A tool that throws is an ERROR on its own span only: TanStack sends the error to the model as the tool result, so the run can still finish. A client disconnect ends every open span as ERROR `cancelled` with `tanstack.ai.completion.reason=cancelled`.
+
+## What is captured
+
+| Data | Default | `captureContent: true` |
+| --- | --- | --- |
+| Span names, timing, parent links, status code | Yes | Yes |
+| Request and response model, `gen_ai.system` (adapter name), `gen_ai.provider.name`, finish reason, sampling parameters you set | Yes | Yes |
+| Tokens per model call (`gen_ai.usage.input_tokens`, `output_tokens`, `total_tokens`, cache read and creation, reasoning) | Yes | Yes |
+| Tool name, call id, type, outcome | Yes | Yes |
+| `tanstack.ai.iteration`, `tanstack.ai.iterations`, `tanstack.ai.completion.reason`, `tanstack.ai.root_usage.*` | Yes | Yes |
+| `session.id` (the `threadId` you pass, with `threadIdAsSession: true`) | Yes | Yes |
+| `error.type`, and an `exception` event with only `exception.type` | Yes | Yes |
+| System prompt, messages and the answer (`gen_ai.input.messages`, `gen_ai.output.messages`, message events) | No | Yes, through `redact` |
+| Tool arguments and results | No | Yes, through `redact` |
+| Error text (span status message, `exception.message`) | No | Yes, through `redact` |
+| Stack traces (`exception.stacktrace`) | No | No |
+| Resource attributes | `project_name`, `project_type`, `project_version_name`, `project_version_id`, `eval_tags`, `metadata` and `service.name`. No host, process or user attributes. | The same |
+| TanStack metrics (`gen_ai.client.token.usage`, operation duration) | Not created: the recipe passes no meter | The same |
+
+## Privacy
+
+**Default: metadata only.** TanStack's `captureContent` option defaults to `false`, and the recipe leaves it there, so no system prompt, message, answer, tool argument or tool result reaches a span. TanStack does record errors whatever `captureContent` is: it calls `span.recordException(error)` and sets the error's message as the span status. The message comes from the provider or from your tool, and the exception event carries a stack trace with local file paths and your user name. The recipe gives `otelMiddleware` a tracer whose spans replace both calls (public OpenTelemetry API only): the span gets `error.type`, which is the provider's error code or the error class name, and the status message and exception event carry only that type. A stack trace is never exported.
+
+**Opt in: `captureContent: true`.** Pass it to `futureAgiOtelMiddleware`. TanStack then exports messages and tool payloads, and the recipe exports the error message too, still without a stack trace. Pass `redact` to rewrite every text first; a redactor that throws yields `[redaction_failed]`, never the raw text:
+
+```js
+const middleware = futureAgiOtelMiddleware(tracer, {
+ captureContent: true,
+ redact: (text) => text.replace(/\b[\w.+-]+@[\w-]+\.[\w.]+\b/g, "[email]"),
+});
+```
+
+**Ids you choose.** The `threadId` you pass as the session is exported verbatim on every span. Use an opaque id (a random UUID per conversation), never an email address or user name. The same goes for TanStack's legacy `conversationId`.
+
+How this was checked: each run put a random marker in the user message and the system prompt, the tool returned it in its result, and in the failure runs the tool threw an error carrying the marker, a home-directory path and the local user name. With the default, the marker, the path, the user name, the host name, an email address in the prompt, `file://` stack frames and the Future AGI and model keys were in no column of any ClickHouse row of the project (spans, rollups, sessions, traces) or in the Postgres project row, for the runs through the OpenAI-compatible endpoint, the live OpenAI runs and the 0.64.0 runs. With `captureContent: true` the marker was stored in span attributes and the tool error's text in the status message, still with no stack trace. Before the recipe's error wrapper, the same tool failure stored the home-directory path and the user name in the span's status message. The example's contract tests repeat these checks offline.
+
+## Apps that already run OpenTelemetry
+
+TanStack starts its chat span under whatever span is active. If your app has its own OpenTelemetry provider and context manager (HTTP server instrumentation, a framework's built-in tracing), that is your request span, which goes to your other backend. Future AGI would then receive a trace whose root has a parent it never sees, and the trace would be missing from the Tracing list (it was, in our test). The recipe therefore starts every chat in a new trace. If your app's own spans also go to Future AGI and you want the chat nested under them, pass `joinActiveTrace: true`.
+
+`registerFutureAgiTracing()` calls `register()` with `setGlobalTracerProvider: false`, so it never replaces your app's global provider or sends your other spans to Future AGI.
+
+## How it behaves
+
+- **Tokens are counted once.** TanStack also writes the sum of every model call's usage onto the chat span. Future AGI sums `gen_ai.usage.*` over every span of a trace for the trace view, sessions, dashboards and cost, so the recipe moves the chat span's copy to `tanstack.ai.root_usage.*` whenever the model-call spans carry usage. If no model call reported usage, the chat span keeps it.
+- **Sessions.** With `threadIdAsSession: true` and a `threadId` on `chat()`, every span carries `session.id` and Future AGI groups the conversation. Without a `threadId`, TanStack generates `thread--` per call, so the recipe sets no session.
+- **Exporter down.** With nothing listening at `FI_BASE_URL`, `chat()` and the route still answer; `flushTraces()` logs `[futureagi] span export failed` and never throws. A collector that accepts but never answers costs the request at most the 2 s flush bound.
+- **Batching.** `register({ batch: true })` has no effect with `@traceai/fi-core` 1.0.0 on OpenTelemetry SDK 2.x, so the recipe uses the default per-span export. With a very slow collector the OTLP exporter's limit of 30 exports in flight can drop spans (about 8 concurrent chats of 4 spans).
+- **Global provider untouched.** See [Apps that already run OpenTelemetry](#apps-that-already-run-opentelemetry).
+
+## Limitations
+
+- **The Tracing list shows no tokens for a TanStack trace.** The list reads tokens from the root span, and the recipe moves the root's sum off it so the trace view, sessions, dashboards and cost count each call once. Open the trace, or look at the LLM spans, for tokens and cost.
+- **Content columns reflect `captureContent`.** The default metadata-only mode emits no messages. With `captureContent: true`, Future AGI 1.56.1 promotes `gen_ai.input.messages` and `gen_ai.output.messages` into the input/output columns and retains the raw attributes. The earlier local run recorded empty columns on an older stack; that result is not the current collector contract.
+- **Do not use `chat({ stream: false })`.** In 0.64.0 to 0.69.0 the non-streaming path stops reading at the first `RUN_ERROR`, so a failed call never reaches TanStack's error hook and leaves no trace at all. Read the stream as in step 4.
+- **Media activities** (`generateImage`, speech, transcription) get a span from `otelMiddleware`, but the recipe sets no Future AGI kind on it. They are outside the verified scope.
+- **Browser and edge** are out of scope: the recipe is for Node.js servers, and `FI_API_KEY` must never reach a client bundle.
+- **Pinned to 0.69.0.** `@tanstack/ai` 1.0.0 and `@tanstack/ai-openai` 1.0.0 were published on 2026-10-22. In 1.0.0, `otelMiddleware` no longer opens a tool span for a client tool that has no `execute` function, `usage-attributes` no longer writes `tanstack.ai.usage.duration_seconds` and `tanstack.ai.usage.units_billed`, and the deprecated `OtelSpanKind` type alias is removed. This recipe is verified on 0.69.0 only; re-run the example's tests before moving the pins.
+
+## Troubleshooting
+
+- **No traces in the project.** Check `FI_API_KEY`, `FI_SECRET_KEY` and `FI_PROJECT_NAME`, and that `FI_BASE_URL` is an origin without a path. The collector drops a batch without `project_name`.
+- **`Cannot find module '@tanstack/ai/middlewares/otel'` or `otelMiddleware is not exported`.** Import it from the `@tanstack/ai/middlewares/otel` subpath; `@tanstack/ai` does not re-export it.
+- **Traces open from a link but are missing from the Tracing list.** Your chat span has a parent from another backend. Use the recipe's default (do not pass `joinActiveTrace: true`) or send that app's spans to Future AGI too.
+- **A failed request leaves no trace.** The route used `stream: false`, or stopped reading the stream without aborting. See step 4.
+- **The trace view shows twice the tokens.** A bare `otelMiddleware` is registered instead of, or next to, `futureAgiOtelMiddleware`, or the SDK is not on the pinned version. Keep one middleware and the `overrides`.
+- **Duplicate spans.** Two middlewares (for example the OpenInference TanStack middleware and this recipe) are registered. Keep one.
+- **Prompts or error text appear on spans.** `captureContent: true` is set. Remove it, or add a `redact`.
+- **The route waits about 2 s and logs `span export still pending`.** The collector is not answering. Spans keep exporting in the background.
+
+## Next Steps
+
+
+
+ Create keys and an Observe project.
+
+
+ Tracing for the Vercel `ai` package with `@traceai/vercel`.
+
+