npm / braintrust
braintrust
What changed in braintrust 3, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
8 breaking1 deprecations78 new APIs and options3 performance26 behavior and defaults16 tooling72 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initbraintrust 3204 changes
Breaking changes 8
Changes the batch evals API into an API for evals with deferred AI provider calls.
Removes output from the dataset pipeline row type definition.
The @flue/runtime export wrapFlueContext was removed.
The @flue/runtime export wrapFlueSession was removed.
Rejects
__proto__,constructor, andprototypekeys to prevent prototype pollution from untrusted merge sources.Rejects
__proto__,constructor, andprototypekeys to prevent prototype pollution from untrusted merge sources.Adds the canonical Next.js setup utility in place of the webpack loader/plugin.
Built-in tools are now nested under sub-agents.
Deprecations 1
Deprecates the old bundler plugin aliases in favor of the new aliases.
New APIs and options 78
Workflow evals now support batch tasks and scorers.
Eval cancellation now stops scheduling trials, aborts the signal passed to task hooks, and waits for in-flight tasks and scorers to settle before rejecting. Pass hooks.signal to task APIs or check signal.aborted to stop work early.
Logger options now include _createInProjectGroup.
Helper types for pushing pre-processors are now exposed.
Add projectGroupName to create projects inside a project group.
Adds span provenance for Temporal and OpenAI Agents SDK.
Adds instrumentation for OpenAI multimodal APIs.
Adds hooks for exporting spans.
Adds AI SDK instrumentation for typesafe ai jev.
Adds instrumentation for @typesafe-ai/sdk, allowing developers to instrument its usage with Braintrust.
Adds utilities to push and preview custom views.
Adds instrumentation for Google GenAI multimodal embeddings.
Adds instrumentation for the LangGraph SDK.
Adds instrumentation for the OpenAI agents API.
Adds advanced filters to Trace.getSpans(), allowing developers to filter spans with more control.
Prompt templates support input audio content.
Tool IDs are tracked for AI SDK v6.
Adds instrumentation for the OpenAI Batch API.
initDataset() supports datasetId.
loadPrompt accepts an apiKey argument.
Instrumentation now supports Vercel AI SDK image generation.
An experimental batch evals API was added.
Voyage instrumentation was added.
Adds instrumentation for @cloudflare/think.
Adds support for flue v2.
Adds meta.eval.input to vitest-evals.
Adds instrumentation for ollama.
Adds instrumentation for agents.
Adds instrumentation for @cloudflare/ai-chat.
Adds instrumentation for @huggingface/transformers.
Support is added for v1 of the OpenRouter SDK.
Adds LangSmith tracing.
Adds a scorer that exposes helpers to evaluate agents.
Forwards and picks up the
--sample Nflag.Adds an API for distributed tracing across service boundaries.
Adds an API for distributed tracing across service boundaries.
Adds a flag to toggle realtime mode in the span fetcher.
Adds braintrustFlueInstrumentation() to make manual instrumentation slightly cleaner.
Adds support for @anthropic-ai/bedrock-sdk.
Adds support for @aws-sdk/client-bedrock-runtime.
Adds support for manual instrumentation for flue v1.
Adds support for @strands-agents/sdk.
Adds AI SDK v7 support.
Adds instrumentation for the pi-coding-agent package.
Adds project-level classifier builder support for function push.
Adds Google GenAI instrumentation for the interactions API.
Inline eval cases can carry explicit origin metadata.
Installing braintrust exposes a bt command in node_modules/.bin that runs the prebuilt native binary for your platform.
invoke() now accepts overrides.
Exports LocalTrace for use by developers.
Adds an environment variable to control the caching location.
Adds auto-instrumentation for Mastra.
The dataset pipeline argument now includes the span id.
Dataset pipelines are available as an experimental feature.
Adds an entrypoint for CJS/TS patching.
Adds an esbuild bundler plugin alias.
Adds a Rollup bundler plugin alias.
Adds a Vite bundler plugin alias.
Adds a webpack bundler plugin alias.
Adds instrumentation for @flue/runtime.
Adds automatic instrumentation for LangChain.
Adds automatic instrumentation for LangGraph.
Adds automatic instrumentation for the OpenAI Agents SDK.
Adds instrumentation for Firebase genkit.
Captures multi-turn message APIs with a wrapper.
Captures reasoning for Groq reasoning models.
wrapVitest now supports projectId.
Thinking is now captured with Cohere.
Dataset versioning support was added, allowing developers to work with versioned datasets.
Experiment dataset filters are now included in experiment metadata.
Instrumentation was added for groq-sdk.
Adds cohere-ai instrumentation.
Adds per-input trialCount support to Eval().
Captures grounding metadata for Google GenAI.
Adds instrumentation for @huggingface/inference.
Adds reranking instrumentation for AI SDK and Openrouter SDK.
Tracks server tool use metrics for the Anthropic SDK.
Adds x-bt-use-gateway to the allowed CORS headers.
Performance 3
Project lookup is cached.
Streamlines SDK flushing.
Flue instrumentation uses less memory.
Behavior and default changes 26
Made @types/react an optional peer dependency so braintrust no longer installs React 18 types for every consumer, avoiding ReactNode type conflicts in React 19 projects.
Eve compatibility now includes versions 0.62 and 0.70.
Streams ending with response.incomplete or response.failed now log output and token metrics; response.failed also logs the error.
Eve turns are now nested under the caller's propagated trace context.
Span customizers are enhanced.
Zod v4 schemas are supported for eval parameters and function parameters.
Scorer results can be nameless.
The eval command applies auto instrumentation.
Instrumentation uses new eve instrumentation hooks.
The instrumentation name is recorded as part of span provenance.
Captures readable reasoning on the originating LLM span across workflow resumes.
Adds span origin provenance metadata to Braintrust and OpenTelemetry spans.
Eve session IDs are recorded on all spans.
Eve turns are tracked as individual traces.
Strands logs inline document, image, and video bytes as Braintrust attachments.
Parallel tool calls are captured in Eve LLM span output.
Mastra now records
time_to_first_tokenfor streaming.Stops capturing message history in AI SDK tool spans.
When optional dependencies are skipped, a postinstall script downloads the matching binary from the npm registry as a fallback.
Node.js login now searches upwards recursively for .env.braintrust containing BRAINTRUST_API_KEY.
Adds exponential backoff between existing retry attempts.
Git metadata is not collected by default when organization-level git metadata settings are absent.
Allows tracing across multiple projects by removing the parent project ID restriction.
OpenRouter instrumentation now captures reasoning.
The supported patching range now includes google ADK 1.0.0.
Improves task lifecycle handling and lifecycle details in the claude-agent-sdk.
Tooling 16
Adds instrumentation for Google GenAI multimodal APIs.
Adds instrumentation for Groq audio APIs.
Instrumentation is added for @google/generative-ai.
Instrumentation is added for synchronous elevenlabs SDK APIs.
Adds instrumentation for anthropic.beta.sessions.
Auto instrumentation is updated to the current Pi Coding Agent SDK release.
Adds tracing support for HarnessAgent.
First-party eve instrumentation was added.
Adds instrumentation for Workflow Agent.
Adds a reporter for vitest-evals.
Adds instrumentation for Mistral classification and moderation APIs.
Adds instrumentation for @github/copilot-sdk.
Adds instrumentation for @openai/codex-sdk.
Instrumentation was added for @cursor/sdk.
Adds instrumentation for Google GenAI embedContent calls for text.
Adds instrumentation for the Anthropic SDK tool runner.
Fixes and other changes 72
The Vite integration now supports Vite 8 dependency optimization.
Claude token usage statistics are fixed.
Empty numeric environment variables are ignored instead of being read as 0.
Empty numeric environment variables are ignored instead of being read as 0.
Preserves LangChain model attribution.
Fixes reasoning_content handling for OpenAI-compatible responses.
Stops resending span metadata on end rows.
Fixes token metrics when using AI SDK middleware.
Prevents dataset snapshots from silently including deleted rows.
Keeps tool spans current during execution so nested spans attach to the tool span.
Captures provider managed tool calls.
Captures the right provider when using the Vercel AI gateway.
OpenAI batch instrumentation now supports Uint8Array and Buffer JSONL sources.
OpenAI batch instrumentation now supports the /v1/embeddings endpoint.
Prevents collisions when eval trials are upserted.
Fixes a race in OTEL trace context propagation.
Fixes LangChain Anthropic token metrics.
Injects the instrumentation hook on Next.js versions below 15.
Fixes instrumentation of streamFunction.
Instrumentation output preserves all streaming chat choices.
LangChain reasoning tokens are recorded as a metric.
Anthropic thinking tokens are recorded as a metric.
noTraceIO is no longer ignored when wrapTraced wraps plain functions.
The limit is enforced across paginated dataset fetches.
Per-call token and cost metrics are now calculated correctly in the Claude Agent SDK integration.
The scorer now receives id and tags.
Subagent tool spans are now correctly parented in the Claude Agent SDK integration.
Returns any to fix type compatibility.
Fixes token counting in Google ADK.
Fixes output token counting for the generate content API.
Fixes output token counting for the interactions API.
Captures the system prompt in Strands agent model span input.
Fixes eval hanging until its configured timeout resolves.
Preserves HarnessAgent trace context across suspended turns.
Emits canonical LangChain JS total token metrics.
Cleans up span metadata produced by the Claude Agent SDK integration.
Transient failures are retried for internal, read-only BTQL requests used to fetch datasets, objects, spans, and prompt versions.
Unresolved dynamic model fallbacks are no longer reported as model metadata.
Mastra span IDs are used as Braintrust row IDs so logFeedback attaches feedback to the correct row.
Closes parent spans using AI SDK 7
onEndcallbacks.Fixes function invocations by stripping
/v1/proxyfrom the functions endpoint.Properly anchors the preview domain CORS regex.
Synthesizes AI SDK total token metrics from prompt and completion counts.
Keeps model child spans correctly parented for concurrent calls sharing a model instance.
Logs the Anthropic system message first in span input.
Fixes dataset row origin for evals and playgrounds.
Fixes subagent span nesting and input.
Eval summaries compare against the experiment’s explicit base experiment ID.
Fixes span nesting.
Validates inline row origin for evals.
Fixes TTFT in AI SDK v6.
Preserves multi-byte UTF-8 characters split across chunk boundaries in streams.
Fixes instrumentation wrapping for the Cohere v2 subclient.
Fixes Google ADK agent naming in instrumentation.
Prevents duplicate LLM spans when multiple SDK instances are loaded in the same process.
Cancels body consumption immediately for object store uploads.
Prevents OpenAI instrumentation from reading a request body more than once.
Marks callModel parent spans as tasks and avoids double-counting metrics.
File transforms are skipped when the transform id is undefined, avoiding processing them in that case.
The export map for bundler plugins was corrected.
Directory warnings now show the correct eval file extension.
Streamed tool calls are now captured for Hugging Face.
Reasoning capture in Mistral was corrected.
Sets AI SDK top-level api spans to type function.
Ends OpenAI Agents child spans when the trace ends.
Collects logprob and refusals output for OpenAI streaming APIs.
Restores prompt cache metrics for the AI SDK.
Collects logprob and refusals output for OpenAI streaming APIs.
Captures Anthropic server tool use inputs for streaming APIs.
Uses a sync channel for AI SDK CJS streamText and streamObject in v4+.
Uses a sync channel for AI SDK CJS streamText and streamObject in v4+.
Prevents tool spans from being dropped when spawning subagents in the claude-agent-sdk.