TypeScript SDK

import { createHue, HueExportError } from "@hue-run/sdk";

async function main() {
  const apiKey = process.env.HUE_API_KEY;
  if (!apiKey) throw new Error("Set HUE_API_KEY in your server environment.");

  const hue = createHue({
    apiKey,
    serviceName: "uppercase-demo",
    captureContent: true, // Record inputs and outputs alongside timing and metadata.
    onExportIssue: (issue) => {
      console.error("Hue export issue", issue.kind, issue.signal, issue.count);
    },
  });

  try {
    await hue.checkConnection(); // Verify which project the key belongs to.
    // The tool call becomes a child of this request span.
    await hue.withSpan(
      "demo.run",
      async (run) => {
        const result = await hue.tool("uppercase", "hello", () => "hello".toUpperCase());
        run.setOutput(result);
        console.log("Trace ID:", run.traceId);
      },
      { sessionId: "demo-session", input: "hello" },
    );
    const report = await hue.flush(); // Confirm delivery before the process exits.
    console.log("Acknowledged spans:", report.acceptedSpans);
  } finally {
    await hue.shutdownSafe({ timeoutMillis: 1000 });
  }
}

try {
  await main();
} catch (error) {
  if (error instanceof HueExportError) {
    console.error("Hue did not acknowledge all telemetry", error.report);
  } else {
    console.error("The example failed. Check your connection and server configuration.");
  }
  process.exitCode = 1;
}

node trace.ts

const response = await hue.model(
  "gpt-5-mini",
  async (span) => {
    span.setInput(
      messages.map((message) => ({
        role: message.role,
        parts: [{ type: "text", content: message.content }],
      })),
    );
    const response = await openai.chat.completions.create({ model: "gpt-5-mini", messages });
    span.setOutput(
      response.choices.map((choice) => ({
        role: choice.message.role,
        parts: [{ type: "text", content: choice.message.content ?? "" }],
        finish_reason: choice.finish_reason,
      })),
    );
    span.setUsage({
      inputTokens: response.usage?.prompt_tokens,
      outputTokens: response.usage?.completion_tokens,
    });
    return response;
  },
  { provider: "openai" },
);

bun add @ai-sdk/otel@^1.0.0

import { streamText } from "ai";
import { hueExperimentalTelemetry } from "@hue-run/sdk";

export function handleChat(message: string, sessionId: string, userId: string) {
  let textStream!: AsyncIterable<string>;
  const done = hue.withSpan(
    "support.chat",
    async (request) => {
      const result = streamText({
        model,
        tools,
        prompt: message,
        experimental_telemetry: hueExperimentalTelemetry(hue),
      });
      textStream = result.textStream;
      await result.consumeStream(); // Ends after the stream, tools and the AI SDK's own spans.
      const text = await result.text;
      request.setOutput(text);
      return text;
    },
    { input: message, sessionId, userId },
  );
  return { textStream, done };
}

await hue.flush();
const confirmation = await hue.verifyTrace(requestTraceId, {
  expectedSpanIds: [requestSpanId],
  requiredFields: ["model"],
  timeoutMillis: 10_000,
});
if (!confirmation.verified) {
  throw new Error("Expected trace evidence did not arrive before the deadline.");
}
console.log(confirmation.receipt?.traceUrl);

import { createHueSafe, type JsonValue } from "@hue-run/sdk";

export const hue = createHueSafe({
  apiKey: process.env.HUE_API_KEY ?? "",
  serviceName: "customer-agent",
  captureContent: process.env.HUE_CAPTURE_CONTENT !== "false", // Content is on unless explicitly disabled.
  enabled: process.env.HUE_TRACING_ENABLED !== "false",
  maxQueueBytes: 8 * 1024 * 1024,
});

// Call your existing agent exactly once. Preserve its result and exceptions.
export async function handleRequest(input: JsonValue) {
  return hue.withSpan("agent.request", async (span) => {
    const result = await existingAgent(input);
    span.setOutput(result);
    return result;
  }, { input });
}

// At process shutdown, after stopping new requests:
export async function shutdownTracing() {
  return hue.shutdownSafe({ timeoutMillis: 1000 });
}
// Register shutdownTracing in your shutdown hook; observe its result without throwing.