Quickstart

Set up with your coding agent

If you received a trial invitation from Hue, open Worlds and choose Create world instead of the tracing setup below. Copy the prompt from Create world with your agent into your coding agent. See Trial organizations. Open Claude Code, Codex, Cursor or another coding agent in your application’s repository and send:

Prompt

Set up Hue in this project. Read https://docs.hue.run/guides/agent-setup.md and follow it.

The agent reads your repository and shows you its plan. It asks you to create a Read and write API key in Hue and store it yourself, so the key never goes into the chat. It then installs the Hue skill and SDK, traces your real request path, confirms that a real request arrived with its content, and connects the Hue MCP server so it can read your traces. A Hue account is required. To set up by hand, follow the steps below. They send a real trace from a local text transformation, with no model provider or model credits.

The example is a strict setup diagnostic: it fails if Hue is unavailable. For serving applications, use TypeScript production setup or Python production setup.

You need a Hue project and Node.js 22 or 24 or Python 3.10+. To send to a local OpenTelemetry Collector instead, follow Send through a Collector.

1. Create a project key

In Hue, select your project and open Settings → API keys to create a Read and write service key. Store it as HUE_API_KEY in your server environment or secret manager. Project keys explains the access levels and rotation.

2. Install the SDK

TypeScript

Requires Node.js 22 or 24 (Node.js 26 also runs in CI) or Bun 1.4. Run the command in your application’s directory. For a new example, create a directory and run npm init -y && npm pkg set type=module first so that import statements work in .js and .ts files.

npm install @hue-run/sdk@0.27.0

bun add @hue-run/sdk@0.27.0

The package is ESM; CommonJS applications on Node.js 22.12 or later load it with require("@hue-run/sdk"). Check compatibility before adding it to an existing application.

Dependency	When you need it
AI SDK 6	Use `hueExperimentalTelemetry(hue)` as `experimental_telemetry`.
AI SDK 7	Use the `hueTelemetry` adapter with a compatible `@ai-sdk/otel` peer.
`ajv`	Add JSON Schema scoring with `npm install ajv`.
OpenTelemetry	Applications with existing instrumentation can use the standard exporter.

Python

Requires Python 3.10 or later; tested on 3.10 and 3.14. Install into your project’s existing environment:

pip install hue-run==0.15.0

uv add hue-run==0.15.0

For a new pip example, create and activate a virtual environment first with python3 -m venv .venv and source .venv/bin/activate. For a new uv project, run uv init before uv add; run the examples with uv run python or activate its .venv.

Dependency	When you need it
OpenTelemetry 1.x	The SDK accepts `opentelemetry-api`, `opentelemetry-sdk`, and `opentelemetry-exporter-otlp-proto-http` in the range `>=1.40,<2`. See compatibility for tested combinations.
`hue-run[evals]`	Add JSON Schema scoring with `pip install 'hue-run[evals]'`.

Verify your installation

The documented releases are TypeScript 0.27.0 on npm and Python 0.15.0 on PyPI. Check the installed version with npm ls @hue-run/sdk or python -m pip show hue-run; in a uv project, use uv tree.

3. Configure your environment

In the same terminal, set:

export HUE_API_KEY=your_project_service_key
export HUE_CAPTURE_CONTENT=true

HUE_CAPTURE_CONTENT=true records prompts, responses, and tool inputs and outputs alongside timing and errors; set it to false for metadata-only traces. See content capture.

4. Record a request

Identify the user on every request. Replace user-123 below with your application’s stable user ID so Hue can build their World across traces.

TypeScript / JavaScript
Python

Create first-trace.mjs:

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

const apiKey = process.env.HUE_API_KEY;
const capture = process.env.HUE_CAPTURE_CONTENT ?? "true";
if (!apiKey || !["true", "false"].includes(capture)) {
  throw new Error("Set HUE_API_KEY and HUE_CAPTURE_CONTENT=true (recommended) or false");
}

const hue = createHue({
  apiKey,
  serviceName: "hue-first-trace",
  captureContent: capture === "true", // true records inputs and outputs; false sends metadata only.
});

try {
  await hue.checkConnection(); // Verify the key before sending a trace.
  let traceId;
  // Group the request and its tool call in one trace.
  const output = await hue.withSpan(
    "first-trace",
    async (span) => {
      traceId = span.traceId;
      const result = await hue.tool("uppercase", "Hello Hue", () => "Hello Hue".toUpperCase());
      span.setOutput(result);
      return result;
    },
    { input: "Hello Hue", userId: "user-123", sessionId: "hue-quickstart" },
  );
  await hue.flush(); // Wait for Hue to acknowledge the trace.
  console.log({ output, traceId });
} finally {
  await hue.shutdownSafe({ timeoutMillis: 1000 }); // Do not replace the original diagnostic error.
}

Run node first-trace.mjs.

Create first_trace.py:

import os
from hue_sdk import Hue

api_key = os.environ.get("HUE_API_KEY")
capture = os.environ.get("HUE_CAPTURE_CONTENT", "true")
if not api_key or capture not in ("true", "false"):
    raise ValueError("Set HUE_API_KEY and HUE_CAPTURE_CONTENT=true (recommended) or false")

hue = Hue(
    api_key=api_key,
    service_name="hue-first-trace",
    capture_content=capture == "true",  # True records inputs and outputs; False sends metadata only.
)

try:
    hue.validate_project()  # Verify the key before sending a trace.
    # Group the request and its tool call in one trace.
    with hue.context(user_id="user-123", session_id="hue-quickstart"):
        with hue.span("first-trace") as span:
            span.set_input("Hello Hue")
            with hue.tool("uppercase") as tool:
                tool.set_input("Hello Hue")
                output = "Hello Hue".upper()
                tool.set_output(output)
            span.set_output(output)
            trace_id = span.trace_id
    # Wait for Hue to acknowledge the trace before exiting.
    if not hue.force_flush():
        raise RuntimeError("Hue export failed; inspect hue.export_status")
    print({"output": output, "traceId": trace_id})
finally:
    hue.shutdown_safe(timeout_millis=1000)  # Preserve any original diagnostic error.

Run python first_trace.py in the activated environment.

The program checks the key before sending data, prints HELLO HUE and a trace ID after a successful flush, then shuts down the SDK. A rejected export causes the program to fail.

5. Inspect the trace

In the same Hue project, open Traces and match the printed trace ID. You should see:

A root span named first-trace and a tool child named execute_tool uppercase.
Session hue-quickstart and the recorded timing.
Input Hello Hue and output HELLO HUE. With HUE_CAPTURE_CONTENT=false, the trace shows no input or output.

Export acknowledgement confirms receiver acceptance. Inspecting the stored trace verifies the complete setup.

Project keys

Use a project service key for SDK requests and OpenTelemetry exports. Pass it to the SDK constructor. Hue constructors do not automatically load environment files. For direct HTTP requests, authentication uses Authorization: Bearer <project-service-key>. The key determines the destination project. Resource attributes, observed user IDs and session IDs cannot select a different project.

Access levels

A key either reads the project or reads and writes it. New keys default to Read and write. Your organization’s access also limits each key. Trial organizations have Worlds access; a Read and write key does not unlock tracing or evaluations.

Preset	Use it for	Access
Read	A coding agent on the Hue MCP server	Reads project traces and recorded content, attention states, trace checks, evaluations, reviewed cases, intents, managed and local runs, artifacts, members, and keys, which covers production recipes. It cannot send telemetry or change project data.
Read and write	An application sending telemetry, trusted MCP client, CI job, evaluation worker, or source-capture process	Everything Read reaches, plus MCP writes, tracing, source capture, and evaluation, artifact, simulation, environment, and managed-run APIs. Append `?read_only=true` to the MCP URL to hide writes. Billing stays in Settings.

Use Read and write for application telemetry and processes that change project data. Use separate keys for development and production so you can revoke either independently. On a development machine, one Read and write key can serve as both the application’s HUE_API_KEY and the MCP client’s HUE_MCP_KEY; hue login stores it under both names. Create separate keys when you want to revoke either use alone. The MCP access levels list the tools each preset reaches. Owner- and admin-only MCP tools act as the member who created the key, who must still be a verified owner or admin; a sign-in connection uses the role of the member who approved it. Owners and admins create and revoke keys; any member can instead sign in with Hue to connect an MCP client. Treat every key as a server credential and keep it out of browser bundles, logs, source control and shared prompts. Use the in-product trial prompt only with a coding agent you trust.

Legacy presets

Keys created with earlier presets keep their access. Tracing only keys appear as Tracing only (legacy); they can send telemetry, check the project connection, and verify known-trace receipts, but cannot browse project data or use evaluation APIs. Coding agent (read-only) and Coding agent (read + evaluations) keys now appear as Read and Read and write. Tracing and evaluations and Source capture only keys appear as Tracing and evaluations (legacy) and Source capture (legacy); they keep working for their original APIs but cannot read project data through the MCP server, and new keys use Read and write instead. Creating a new restricted key does not narrow an older credential.

Verify and rotate

Call hue.checkConnection() in TypeScript or hue.validate_project() in Python. These send a project lookup without a trace and return the project identity. Confirm it matches the project you intend to use before exporting data. When replacing a key, configure the replacement in the server’s secret store, verify the connection, then revoke the old key in project settings. Never include either credential in a support report. A successful connection check validates project access; the first-trace check separately verifies instrumentation and delivery.

Connection settings

Both SDKs default to https://app.hue.run. Omit baseUrl in TypeScript and base_url in Python for Hue Cloud. You do not need to choose or discover a different endpoint for a normal Hue Cloud integration. For local development or another configured Hue deployment, pass a different origin through baseUrl in TypeScript or base_url in Python. If your application uses HUE_BASE_URL, read it explicitly and pass it to the constructor. SDKs do not load environment files automatically. Supply an origin without credentials, an API path, query parameters or a fragment. HTTPS is required except for loopback HTTP. SDKs append their own paths; a standard OTLP exporter instead needs the full signal endpoint.

Next steps

Generate a World to test your agent against simulated app data without production traces.
Structure your own requests with Traces and spans, using the TypeScript or Python SDK or your existing OpenTelemetry setup.
Connect your coding agent to the Hue MCP server by signing in with Hue or with a Read or Read and write key.
Turn a trace into a case and evaluate your agent: Create a case.

If the trace does not appear, follow troubleshooting.

Get started

Worlds

MCP

Simulations

Traces

Evals

Traces to cases

Classifiers

Reference

Quickstart

Set up with your coding agent

1. Create a project key

2. Install the SDK

TypeScript

Python

Verify your installation

3. Configure your environment

4. Record a request

5. Inspect the trace

Project keys

Access levels

Legacy presets

Verify and rotate

Connection settings

Next steps

​Set up with your coding agent

​1. Create a project key

​2. Install the SDK

​TypeScript

​Python

​Verify your installation

​3. Configure your environment

​4. Record a request

​5. Inspect the trace

​Project keys

​Access levels

​Legacy presets

​Verify and rotate

​Connection settings

​Next steps

Set up with your coding agent

1. Create a project key

2. Install the SDK

TypeScript

Python

Verify your installation

3. Configure your environment

4. Record a request

5. Inspect the trace

Project keys

Access levels

Legacy presets

Verify and rotate

Connection settings

Next steps