@saguiitay/eventhouse-ai-observability 0.1.2 → 0.2.0

package/docs/vercel-adapter.md

@@ -0,0 +1,201 @@
+# Vercel AI SDK adapter
+
+`observeVercelAI` supplies a per-call `telemetry` configuration for
+Vercel AI SDK **7.0.165**, using its native **`@ai-sdk/otel@1.0.165`** integration.
+Supported APIs are `generateText` and
+`streamText`, including multiple model steps and local tool execution.
+The SDK is an optional peer; importing the observability package or its
+`/vercel` entry point does not load `ai` at runtime.
+
+Install a compatible SDK in the application:
+
+```sh
+pnpm add ai@7.0.165 @ai-sdk/otel@1.0.165 zod@4.6.7
+```
+
+SDK 7 moved tracer injection from `experimental_telemetry.tracer` into the
+`OpenTelemetry` integration constructor. This adapter uses the replacement
+API; no global provider registration is required. SDK 6's telemetry settings
+are not supported by this version of the adapter.
+
+## Per-call setup
+
+```ts
+import { generateText, streamText } from "ai";
+import { OpenTelemetry } from "@ai-sdk/otel";
+import { observeVercelAI } from "@saguiitay/eventhouse-ai-observability/vercel";
+
+// `model` is an existing AI SDK language model supplied by your application.
+const observer = observeVercelAI({
+  connectionString: process.env.FABRIC_EVENTSTREAM_CONNECTION_STRING!,
+  serviceName: "my-ai-app",
+  integration: (tracer) => new OpenTelemetry({ tracer }),
+});
+
+try {
+  const generated = await generateText({
+    model,
+    prompt: "Summarize the report",
+    telemetry: observer.telemetry,
+  });
+
+  const streamed = streamText({
+    model,
+    prompt: generated.text,
+    telemetry: observer.telemetry,
+  });
+  // Consume the stream before flushing or shutting down.
+  await streamed.consumeStream();
+  await observer.flush();
+  console.log(observer.getDiagnostics());
+} finally {
+  await observer.shutdown();
+}
+```
+
+Pass `observer.telemetry` on **every SDK call**. The required `integration`
+factory receives the adapter's private tracer and constructs the SDK's native
+`OpenTelemetry` integration. The library does not import either `ai` or
+`@ai-sdk/otel` at runtime.
+
+This is not a global provider
+registration or a wrapper around `generateText`/`streamText`. Calls without this
+configuration are not observed by this adapter. Do not combine it with another
+adapter that instruments the same provider request, or token totals may be
+counted twice.
+
+The normal engine transport, sampling, queue limits, resource attributes,
+redaction and diagnostics options are accepted when the observer creates its
+own engine. Fabric Eventstream configuration works the same way as at the root
+entry point.
+
+## Native spans and analytics
+
+The SDK's native integration creates root, step, model and tool spans.
+A tracer bridge routes them
+through the engine's private provider and local asynchronous context. It does
+not register a global OTel tracer provider or context manager. Application
+parents, explicit native parents and unsampled parent contexts are preserved.
+
+The bridge retains `gen_ai.operation.name` (`invoke_agent`, `agent_step`, `chat`,
+`execute_tool`),
+provider/model and tool attributes. `vercel.span.type` distinguishes `turn`,
+`step`, `model_request` and `tool`. Span names are fixed to those operation
+names rather than carrying arbitrary function identifiers or content.
+Model usage remains `gen_ai.usage.input_tokens` and
+`gen_ai.usage.output_tokens`; native root aggregate usage is discarded. Each
+provider operation contributes usage once, even in a multistep tool loop.
+SDK model switching retains each request's own model identity. The public
+`executeLanguageModelCall` and `executeTool` integration hooks are bound to the
+engine's local context, so telemetry created inside provider calls or nested
+tool work inherits the native model/tool parent without a global context
+manager.
+
+Some error-only streams omit a native model-call completion event. The bridge
+ends that existing model span with `observability.incomplete: true` when its
+step finishes, retains the failure classification, and leaves unknown usage
+unset. It does not copy tokens from the parent.
+
+The SDK's outer text span covers the complete SDK call, not a separate adapter
+execution. Retries retain the native SDK operation structure. Embeddings,
+speech, transcription, legacy object-generation APIs and durable workflows
+are outside this adapter's supported contract.
+
+## Privacy
+
+Inputs and outputs are not recorded by default. The returned configuration has
+both `recordInputs: false` and `recordOutputs: false`, even if the engine permits
+content capture.
+
+SDK 7 filters content before telemetry integrations receive events, but native
+integration options and enrichment callbacks can still add request headers,
+arbitrary metadata, provider metadata or exception details.
+The tracer bridge uses an attribute allowlist before
+the engine receives mutations. It drops those fields, span/link attributes
+outside the allowlist, custom span names, native events and status messages.
+Failures keep an error status and a fixed `provider_error` classification; raw
+errors still reach the application's normal SDK error handling unchanged.
+This filtering also applies to settings supplied by spreading the returned
+configuration.
+
+To record text or tool content, opt in on both the engine and the relevant
+direction:
+
+```ts
+const observer = observeVercelAI({
+  exporter,
+  captureContent: true,
+  recordInputs: true,
+  recordOutputs: true,
+  integration: (tracer) => new OpenTelemetry({ tracer }),
+});
+```
+
+Captured content is mapped to `gen_ai.input.messages`,
+`gen_ai.output.messages`, and standard tool content attributes. Strings are
+bounded to 4,096 characters and sanitized by the engine's secret redactor and
+your optional `redact` callback. Provider metadata, headers and raw errors stay
+excluded even with capture enabled. Secret redaction is not a general PII
+detector: use your own redactor for application-specific sensitive content.
+Model identifiers and tool names/IDs are retained as bounded operational
+metadata; do not place user content or secrets in those identifiers.
+
+The adapter cannot control other telemetry integrations, exporters or
+application callbacks. Configure their privacy separately. Native error
+objects are replaced with a fixed classification before this integration sees
+them, including errors used as metric dimensions. The native integration may
+also emit operational latency metrics to an application's existing global
+meter provider; those metrics are not exported or counted by this tracing
+engine.
+
+## Shared engines and shutdown
+
+```ts
+import { createObservability } from "@saguiitay/eventhouse-ai-observability";
+
+const engine = createObservability({ exporter });
+const observer = observeVercelAI({
+  engine,
+  integration: (tracer) => new OpenTelemetry({ tracer }),
+});
+try {
+  await generateText({
+    model,
+    prompt: "Hello",
+    telemetry: observer.telemetry,
+  });
+} finally {
+  await observer.shutdown(); // Ends this adapter's live spans and flushes.
+  await engine.shutdown(); // The application closes its shared engine once.
+}
+```
+
+An externally supplied engine remains application-owned by default. The
+integration instance belongs to this attachment; return a fresh
+`OpenTelemetry` instance from each factory rather than sharing one between
+observers.
+`shutdownEngine: true` explicitly transfers its shutdown ownership to the
+adapter. For engines created by `observeVercelAI`, shutdown ownership is always
+the adapter's; `shutdownEngine: false` requires an external engine.
+
+`flush()` exports ended spans without ending ongoing generation.
+`shutdown()` is idempotent, disables this configuration and ends outstanding
+adapter spans with `observability.incomplete: true`. It never cancels a model
+request, closes a provider client, or consumes an unfinished stream. Wait for
+your application work before shutdown if complete spans are required.
+
+## Verification and references
+
+`tests/vercel.test.ts` runs the real SDK with `MockLanguageModelV3` from the
+SDK's public `ai/test` entry point and the real native `OpenTelemetry`
+integration. No provider credentials or external
+inference calls are used.
+The verified versions are `ai@7.0.165`, `@ai-sdk/otel@1.0.165` and
+`zod@4.6.7`.
+
+The [official telemetry guide](https://ai-sdk.dev/docs/ai-sdk-core/telemetry)
+documents per-call integrations and custom tracer injection. The adapter also
+checks the official
+[native integration](https://github.com/vercel/ai/blob/ai%407.0.165/packages/otel/src/open-telemetry.ts),
+[native span/error recording](https://github.com/vercel/ai/blob/ai%407.0.165/packages/otel/src/record-span.ts),
+and [supplemental attribute options](https://github.com/vercel/ai/blob/ai%407.0.165/packages/otel/src/supplemental-attributes.ts).

package/examples/README.md

@@ -1,23 +1,45 @@
-# Copilot examples
+# SDK examples
+
+Every adapter has a runnable sample:
+
+| Adapter   | Sample command                                                         | SDK authentication                              |
+| --------- | ---------------------------------------------------------------------- | ----------------------------------------------- |
+| Copilot   | `pnpm example:basic`, `pnpm example:tools`, `pnpm example:multi-agent` | Authenticated Copilot CLI                       |
+| OpenAI    | `pnpm example:openai`                                                  | `OPENAI_API_KEY`                                |
+| Vercel AI | `pnpm example:vercel`                                                  | `OPENAI_API_KEY` for the direct OpenAI provider |
+
+Examples keep telemetry metadata-only, default to a local console exporter,
+and flush/shut down telemetry before exiting. Console telemetry means no spans
+were exported remotely; real SDK model calls still use the network and consume
+quota or incur charges.
+
+Fabric is the package's built-in transport. For OTLP, the checkout helper
+explicitly constructs OpenTelemetry's official exporter from a development
+dependency and passes it through `exporter`. The library itself does not read
+OTLP endpoint variables or include that exporter as a runtime dependency.
+
+## Copilot SDK
 
 These are real Copilot SDK 1.0.31 applications, not simulated event emitters.
 Use Node.js 22.15+ (validated with 24.22.3), the root package dependencies, and an
 authenticated Copilot CLI. Model calls consume your Copilot quota.
 
 The **basic** example consumes published
-`@saguiitay/eventhouse-ai-observability@0.1.2` once that release is published.
+`@saguiitay/eventhouse-ai-observability@0.2.0` once that release is published.
 Version 0.1.0 was successfully installed and used against a live
 Fabric deployment on 2026-11-12. The example has its own
 dependency manifest and disables the root TypeScript source aliases, so it
 cannot silently use the checkout's runtime. The tools and multi-agent examples
 continue to use the locally built package.
 
-Install the basic example's dependency once. To use npmjs through the approved
-Microsoft mirror, override the example's existing GitHub scope mapping:
+Install the basic example's dependency once. To use npmjs or your organization's
+approved mirror, override the example's existing GitHub scope mapping without
+committing organization-specific registry configuration:
 
 ```powershell
 Push-Location .\examples\copilot-basic
-npm install --package-lock=false --@saguiitay:registry=https://packagefeedproxy.microsoft.io/npm/
+$registry = Read-Host "Your approved npm registry URL"
+npm install --package-lock=false "--@saguiitay:registry=$registry"
 Pop-Location
 ```
 
@@ -25,7 +47,7 @@ Mirror availability can lag publication. Alternatively, after the pinned version
 has also been published to GitHub Packages, use the existing scope mapping.
 GitHub Packages requires a classic
 personal access token with `read:packages`, even for public
-packages. All other dependencies use the Microsoft proxy, not npmjs.org:
+packages. Other dependencies continue to use your configured, approved registry:
 
 ```powershell
 Push-Location .\examples\copilot-basic
@@ -93,3 +115,50 @@ timeout, throttling, and size problems without printing endpoints or keys.
 
 If a model cannot delegate with the runtime's `task` tool, choose another
 available model with `COPILOT_MODEL`; do not widen the permission policy.
+
+## OpenAI and Vercel AI SDKs
+
+Both examples use the locally built package and the root development
+dependencies. From the checkout:
+
+```powershell
+pnpm install --frozen-lockfile
+pnpm build
+foreach ($example in 'openai-basic', 'vercel-basic') {
+    if (-not (Test-Path "examples\$example\.env")) {
+        Copy-Item "examples\$example\env.example" "examples\$example\.env"
+    }
+}
+pnpm example:openai
+pnpm example:vercel
+```
+
+Set `OPENAI_API_KEY` securely in each example's ignored `.env` or the process
+environment. `OPENAI_MODEL` defaults to `gpt-4.1-mini`; choose a model available
+to your account. No key is supplied by the templates. A root `.env` is not loaded.
+
+The OpenAI sample performs a nonstreaming Responses call and a streaming Chat
+Completions call. It consumes the stream and requests the provider's usage
+chunk; it does not estimate tokens. The original SDK client remains unchanged.
+
+The Vercel sample uses `@ai-sdk/openai` directly, not the AI Gateway. It
+demonstrates generation with a bounded, side-effect-free arithmetic tool and
+a separate streaming call. Model-driven tool selection is not guaranteed;
+the tool loop is limited to two steps. Native telemetry is passed on every
+call through `@ai-sdk/otel` with a private tracer.
+
+The OpenAI sample makes two paid model calls. Vercel makes up to three,
+depending on tool selection. Each call caps output at 256 tokens.
+Samples print the model's response for
+demonstration; this application output is separate from metadata-only
+telemetry. They do not print API keys or raw errors.
+
+For remote telemetry, optionally configure
+`FABRIC_EVENTSTREAM_CONNECTION_STRING` and, if needed,
+`FABRIC_EVENTSTREAM_ENTITY_NAME`, or an OTLP endpoint such as
+`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`. Export failures/drops cause the sample to
+fail after telemetry cleanup. Producer acknowledgements do not establish
+Eventhouse ingestion.
+
+See [OpenAI adapter](../docs/openai-adapter.md) and
+[Vercel adapter](../docs/vercel-adapter.md) for supported APIs and lifecycle.

package/examples/copilot-basic/package.json

@@ -3,6 +3,6 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@saguiitay/eventhouse-ai-observability": "0.1.2"
+    "@saguiitay/eventhouse-ai-observability": "0.2.0"
   }
 }

package/examples/openai-basic/env.example

@@ -0,0 +1,8 @@
+# Copy to .env and supply your own OpenAI API key. Both calls incur API usage.
+OPENAI_API_KEY=
+OPENAI_MODEL=gpt-4.1-mini
+# Telemetry is metadata-only and goes to the console by default.
+# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
+# FABRIC_EVENTSTREAM_CONNECTION_STRING=<Custom endpoint SOURCE producer string>
+# FABRIC_EVENTSTREAM_ENTITY_NAME=<only if EntityPath is absent>
+# Keep all service credentials in the process environment or an untracked .env.

package/examples/openai-basic/index.ts

@@ -0,0 +1,46 @@
+import OpenAI from "openai";
+import { observeOpenAI } from "@saguiitay/eventhouse-ai-observability/openai";
+import { runTelemetryExample } from "../telemetry.js";
+
+if (!process.env.OPENAI_API_KEY?.trim())
+  throw new Error("OPENAI_API_KEY is required to run the OpenAI example.");
+
+try {
+  const client = new OpenAI();
+  const model = process.env.OPENAI_MODEL ?? "gpt-4.1-mini";
+
+  await runTelemetryExample(
+    "openai-basic",
+    (options) => observeOpenAI(client, options),
+    async (observer) => {
+      const response = await observer.client.responses.create({
+        model,
+        max_output_tokens: 256,
+        input:
+          "Explain in one sentence why application observability is useful.",
+      });
+      console.log("Responses:", response.output_text);
+
+      const stream = await observer.client.chat.completions.create({
+        model,
+        max_completion_tokens: 256,
+        messages: [
+          {
+            role: "user",
+            content: "Explain in one sentence what a distributed trace shows.",
+          },
+        ],
+        stream: true,
+        stream_options: { include_usage: true },
+      });
+      let text = "";
+      for await (const chunk of stream)
+        text += chunk.choices[0]?.delta.content ?? "";
+      console.log("Chat Completions:", text);
+    },
+  );
+} catch {
+  throw new Error(
+    "OpenAI example failed; check provider configuration and telemetry diagnostics.",
+  );
+}

package/examples/shared.ts

@@ -4,51 +4,14 @@ import {
   type PermissionHandler,
   type SessionConfig,
 } from "@github/copilot-sdk";
-import type {
-  EventhouseObservabilityOptions,
-  Diagnostics,
-  SpanExporter,
-} from "@saguiitay/eventhouse-ai-observability";
+import type { Diagnostics } from "@saguiitay/eventhouse-ai-observability";
 import type { observeCopilot } from "@saguiitay/eventhouse-ai-observability/copilot";
+import { reportTelemetry, telemetryOptions } from "./telemetry.js";
 
 export const denyPermissions: PermissionHandler = () => ({
   kind: "denied-no-approval-rule-and-could-not-request-from-user",
 });
 
-const localExporter: SpanExporter = {
-  export(spans, callback) {
-    for (const span of spans) {
-      console.log(
-        JSON.stringify({
-          name: span.name,
-          traceId: span.spanContext().traceId,
-          spanId: span.spanContext().spanId,
-          parentSpanId: span.parentSpanContext?.spanId,
-          durationMs: span.duration[0] * 1000 + span.duration[1] / 1e6,
-          attributes: span.attributes,
-        }),
-      );
-    }
-    callback({ code: 0 });
-  },
-  async shutdown() {},
-};
-
-function telemetryOptions(serviceName: string) {
-  const mode = process.env.FABRIC_EVENTSTREAM_CONNECTION_STRING
-    ? "eventstream"
-    : process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||
-        process.env.OTEL_EXPORTER_OTLP_ENDPOINT
-      ? "otlp"
-      : "console";
-  const options: EventhouseObservabilityOptions = {
-    serviceName,
-    captureContent: false,
-    ...(mode === "console" ? { exporter: localExporter } : { transport: mode }),
-  };
-  return { mode, options };
-}
-
 export function exampleIterations(
   raw = process.env.COPILOT_EXAMPLE_ITERATIONS,
 ): number {
@@ -61,28 +24,6 @@ export function exampleIterations(
   return count;
 }
 
-function reportTelemetry(
-  mode: string,
-  diagnostics: Readonly<Diagnostics>,
-): void {
-  console.info(
-    `[telemetry] ${mode}: generated=${diagnostics.eventsGenerated}, exported=${diagnostics.eventsExported}, dropped=${diagnostics.eventsDropped}, failures=${diagnostics.exportFailures}`,
-  );
-  if (diagnostics.lastError) {
-    const { category, message } = diagnostics.lastError;
-    console.warn(`[telemetry] ${category}: ${message}`);
-  }
-  if (mode === "eventstream") {
-    console.info(
-      "[telemetry] Exported means producer acknowledgement, not Eventhouse ingestion. Check Eventstream incoming messages and Eventhouse rows.",
-    );
-  } else if (mode === "console") {
-    console.info(
-      "[telemetry] Console only; no data was sent to Fabric or OTLP.",
-    );
-  }
-}
-
 export async function runExample(
   name: string,
   configuration: SessionConfig,
@@ -97,7 +38,7 @@ export async function runExample(
   let session: CopilotSession | undefined;
   let observer: ReturnType<typeof observeCopilot> | undefined;
   let diagnostics: Readonly<Diagnostics> | undefined;
-  const { mode, options } = telemetryOptions(name);
+  const { mode, options } = await telemetryOptions(name);
   console.info(`[telemetry] transport=${mode}`);
   try {
     await client.start();

package/examples/telemetry.ts

@@ -0,0 +1,124 @@
+import type {
+  Diagnostics,
+  EventhouseObservabilityOptions,
+  SpanExporter,
+} from "@saguiitay/eventhouse-ai-observability";
+
+const localExporter: SpanExporter = {
+  export(spans, callback) {
+    for (const span of spans) {
+      console.log(
+        JSON.stringify({
+          name: span.name,
+          traceId: span.spanContext().traceId,
+          spanId: span.spanContext().spanId,
+          parentSpanId: span.parentSpanContext?.spanId,
+          durationMs: span.duration[0] * 1000 + span.duration[1] / 1e6,
+          attributes: span.attributes,
+        }),
+      );
+    }
+    callback({ code: 0 });
+  },
+  async shutdown() {},
+};
+
+export async function telemetryOptions(serviceName: string) {
+  const mode = process.env.FABRIC_EVENTSTREAM_CONNECTION_STRING
+    ? "eventstream"
+    : process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||
+        process.env.OTEL_EXPORTER_OTLP_ENDPOINT
+      ? "otlp"
+      : "console";
+  let exporter: SpanExporter | undefined;
+  if (mode === "console") exporter = localExporter;
+  if (mode === "otlp") {
+    const base = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+    const endpoint =
+      process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ??
+      `${base?.replace(/\/$/, "")}/v1/traces`;
+    try {
+      const url = new URL(endpoint);
+      if (
+        !["http:", "https:"].includes(url.protocol) ||
+        url.username ||
+        url.password
+      )
+        throw new Error();
+    } catch {
+      throw new Error("Invalid example OTLP endpoint configuration.");
+    }
+    const { OTLPTraceExporter } =
+      await import("@opentelemetry/exporter-trace-otlp-http");
+    exporter = new OTLPTraceExporter({ url: endpoint });
+  }
+  const options: EventhouseObservabilityOptions = {
+    serviceName,
+    captureContent: false,
+    ...(exporter ? { exporter } : {}),
+  };
+  return { mode, options };
+}
+
+export function reportTelemetry(
+  mode: string,
+  diagnostics: Readonly<Diagnostics>,
+): void {
+  console.info(
+    `[telemetry] ${mode}: generated=${diagnostics.eventsGenerated}, exported=${diagnostics.eventsExported}, dropped=${diagnostics.eventsDropped}, failures=${diagnostics.exportFailures}`,
+  );
+  if (diagnostics.lastError) {
+    const { category, message } = diagnostics.lastError;
+    console.warn(`[telemetry] ${category}: ${message}`);
+  }
+  if (mode === "eventstream") {
+    console.info(
+      "[telemetry] Exported means producer acknowledgement, not Eventhouse ingestion. Check Eventstream incoming messages and Eventhouse rows.",
+    );
+  } else if (mode === "console") {
+    console.info(
+      "[telemetry] Console only; no data was sent to Fabric or OTLP.",
+    );
+  }
+}
+
+interface ExampleObserver {
+  flush(): Promise<void>;
+  shutdown(): Promise<void>;
+  getDiagnostics(): Readonly<Diagnostics>;
+}
+
+export async function runTelemetryExample<O extends ExampleObserver>(
+  name: string,
+  observe: (options: EventhouseObservabilityOptions) => O,
+  run: (observer: O) => Promise<void>,
+): Promise<void> {
+  const { mode, options } = await telemetryOptions(name);
+  let observer: O | undefined;
+  let diagnostics: Readonly<Diagnostics> | undefined;
+  console.info(`[telemetry] transport=${mode}`);
+  try {
+    observer = observe(options);
+    await run(observer);
+  } finally {
+    try {
+      await observer?.flush();
+    } finally {
+      try {
+        await observer?.shutdown();
+      } finally {
+        if (observer) {
+          diagnostics = observer.getDiagnostics();
+          reportTelemetry(mode, diagnostics);
+        }
+      }
+    }
+  }
+  if (
+    diagnostics &&
+    (diagnostics.exportFailures > 0 || diagnostics.eventsDropped > 0)
+  )
+    throw new Error(
+      "Telemetry export failed or dropped spans; see the telemetry summary above.",
+    );
+}

package/examples/vercel-basic/env.example

@@ -0,0 +1,8 @@
+# Set OPENAI_API_KEY in your environment. Real calls consume OpenAI quota.
+OPENAI_API_KEY=
+OPENAI_MODEL=gpt-4.1-mini
+# Uncomment ONE transport, or leave both unset for console-only telemetry.
+# Content capture is disabled; credentials are never telemetry content.
+# FABRIC_EVENTSTREAM_CONNECTION_STRING=<Custom endpoint SOURCE producer string>
+# FABRIC_EVENTSTREAM_ENTITY_NAME=<only if EntityPath is absent>
+# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces

package/examples/vercel-basic/index.ts

@@ -0,0 +1,60 @@
+import { createOpenAI } from "@ai-sdk/openai";
+import { OpenTelemetry } from "@ai-sdk/otel";
+import { generateText, stepCountIs, streamText, tool } from "ai";
+import { z } from "zod";
+import { observeVercelAI } from "@saguiitay/eventhouse-ai-observability/vercel";
+import { runTelemetryExample } from "../telemetry.js";
+
+const apiKey = process.env.OPENAI_API_KEY?.trim();
+if (!apiKey) throw new Error("Set OPENAI_API_KEY before running this example");
+
+const square = tool({
+  description:
+    "Square a finite number using pure local arithmetic, without external access.",
+  inputSchema: z.object({ value: z.number().finite().min(-1e6).max(1e6) }),
+  execute: async ({ value }) => {
+    if (!Number.isFinite(value) || Math.abs(value) > 1e6)
+      throw new Error("Number outside demo range");
+    return value * value;
+  },
+});
+
+try {
+  const openai = createOpenAI({ apiKey });
+  const model = openai(process.env.OPENAI_MODEL?.trim() || "gpt-4.1-mini");
+  await runTelemetryExample(
+    "vercel-basic",
+    (options) =>
+      observeVercelAI({
+        ...options,
+        integration: (tracer) => new OpenTelemetry({ tracer }),
+      }),
+    async (observer) => {
+      const generated = await generateText({
+        model,
+        maxOutputTokens: 256,
+        prompt: "Use the square tool to square 12, then report the result.",
+        tools: { square },
+        stopWhen: stepCountIs(2),
+        telemetry: observer.telemetry,
+      });
+      console.log("Generated:", generated.text);
+
+      const streamed = streamText({
+        model,
+        maxOutputTokens: 256,
+        prompt: "Explain in one short sentence what squaring a number means.",
+        telemetry: observer.telemetry,
+        // Prevent the SDK's default error logger from exposing provider details.
+        onError: () => {},
+      });
+      for await (const chunk of streamed.textStream)
+        console.log("Stream chunk:", chunk);
+      console.log("Streamed:", await streamed.text);
+    },
+  );
+} catch {
+  throw new Error(
+    "Vercel example failed; check provider configuration and telemetry diagnostics.",
+  );
+}