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
| Layer | HazelJS owns | Partners 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).
- Create project API keys in Langfuse Cloud (or self-host).
- Build Basic auth:
base64(publicKey:secretKey). - 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();
| Region | Traces URL |
|---|---|
| EU | https://cloud.langfuse.com/api/public/otel/v1/traces |
| US | https://us.cloud.langfuse.com/api/public/otel/v1/traces |
| Self-host | https://<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
| Need | Use |
|---|---|
| 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 scale | Langfuse / Braintrust experiments |
CI goldens and partner Studios are complementary: gate deploys in CI; explore and score runs in the partner UI.