Documentation•Reference

Observability partners: bring Langfuse or Braintrust

HazelJS does not ship a Mastra-style Studio (prompt playgrounds, experiment dashboards, model-graded scorer suites). Agent OS owns governance and local day-2 ops. For LLM Studio UX and experiment scoring, bring your own Langfuse or Braintrust over OpenTelemetry.

One-liner: HazelJS operates governed agents; Langfuse/Braintrust observe and score them.

Ownership split

LayerHazelJS ownsPartners own
Local runtime debug@hazeljs/​inspector timelines / __hazel—
CI quality gates@hazeljs/​eval + @hazeljs/​testing goldens—
Trace export@hazeljs/​observability OTLP—
Studio UX, prompt playgrounds, experiment dashboards—Langfuse / Braintrust

Inspector is for Agent OS timelines and Gatekeeper/HITL day-2 ops — not a substitute for a partner Studio.

Export traces with @hazeljs/​observability

Use vendor-neutral OTLP. Pass auth via otlpHeaders. Hazel does not depend on @langfuse/​* or @braintrust/​*.

import { OpenTelemetryProvider } from '@hazeljs/​observability';

const provider = new OpenTelemetryProvider({
  serviceName: 'support-agent',
  otlpEndpoint: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT!,
  otlpHeaders: {
    /​/​ set from env — see Langfuse /​ Braintrust sections below
    Authorization: process.env.OTEL_AUTH_HEADER!,
  },
});

await provider.start();

Wire the same provider into AgentRuntime / AgentModule so agent.execute, agent.tool.execute, and agent.llm spans export automatically. See Observability package.

Langfuse (OTLP)

Langfuse accepts OTLP over HTTP (JSON or protobuf; not gRPC).

  1. Create project API keys in Langfuse Cloud (or self-host).
  2. Build Basic auth: base64(publicKey:secretKey).
  3. Point Hazel at the traces endpoint and headers:
const auth = Buffer.from(
  `${process.env.LANGFUSE_PUBLIC_KEY}:${process.env.LANGFUSE_SECRET_KEY}`
).toString('base64');

const provider = new OpenTelemetryProvider({
  serviceName: 'support-agent',
  /​/​ EU default — use us.cloud.langfuse.com (or jp /​ hipaa) for other regions
  otlpEndpoint: 'https://cloud.langfuse.com/​api/​public/​otel/​v1/​traces',
  otlpHeaders: {
    Authorization: `Basic ${auth}`,
    'x-langfuse-ingestion-version': '4',
  },
});

await provider.start();
RegionTraces URL
EUhttps://cloud.langfuse.com/​api/​public/​otel/​v1/​traces
UShttps://us.cloud.langfuse.com/​api/​public/​otel/​v1/​traces
Self-hosthttps://<host>/​api/​public/​otel/​v1/​traces

Upstream: Langfuse OpenTelemetry.

Braintrust (OTLP)

const provider = new OpenTelemetryProvider({
  serviceName: 'support-agent',
  otlpEndpoint: 'https://api.braintrust.dev/​otel/​v1/​traces',
  otlpHeaders: {
    Authorization: `Bearer ${process.env.BRAINTRUST_API_KEY}`,
    'x-bt-parent': `project_name:${process.env.BRAINTRUST_PROJECT}`,
  },
});

await provider.start();

EU / BYOC: substitute the data-plane host from Braintrust docs. Upstream: Braintrust OpenTelemetry.

Alternate: vendor span processors (BYO)

If your team already uses Langfuse or Braintrust SDKs, attach their processors yourself. Hazel does not wrap them:

/​/​ Example shape only — install and configure per vendor docs
import { NodeSDK } from '@opentelemetry/​sdk-node';
/​/​ import { LangfuseSpanProcessor } from '@langfuse/​otel';
/​/​ import { BraintrustSpanProcessor } from '@braintrust/​otel';

const sdk = new NodeSDK({
  serviceName: 'support-agent',
  spanProcessors: [
    /​/​ new LangfuseSpanProcessor({ ... }),
    /​/​ and/​or new BraintrustSpanProcessor({ parent: 'project_name:...' }),
  ],
});
sdk.start();

Prefer one export path per environment to avoid duplicate spans.

CI eval vs partner experiments

NeedUse
Fail CI when RAG/agent quality regresses@hazeljs/​eval runGoldenDataset + reportEvalForCi
Agent-centric suites (expectTools, latency)@hazeljs/​testing describeAgent
Prompt playgrounds, human review, model judges at scaleLangfuse / Braintrust experiments

CI goldens and partner Studios are complementary: gate deploys in CI; explore and score runs in the partner UI.