Mastra

Mastra is a TypeScript framework for building AI agents. Braintrust integrates with Mastra’s observability system to automatically trace agent executions, LLM calls, and tool usage.

Setup

Install Mastra with the Braintrust exporter:

# pnpm
pnpm add @mastra/core @mastra/braintrust @mastra/observability braintrust
# npm
npm install @mastra/core @mastra/braintrust @mastra/observability braintrust

Trace with Mastra

Braintrust traces Mastra agent runs, workflows, steps, tool calls, and LLM calls. Enable tracing without code changes through auto-instrumentation, or configure a Braintrust exporter manually.

Auto-instrumentation

To trace Mastra without modifying your application code, run your app with Braintrust’s import hook. The hook adds a Braintrust exporter to Mastra’s observability automatically, so you don’t configure one yourself. Requires @mastra/core v1.20.0 or later and the @mastra/observability package.

Build your Mastra app

mastra-app.js

import { initLogger } from "braintrust";
import { Mastra } from "@mastra/core";
import { Agent } from "@mastra/core/agent";

initLogger({
  projectName: "mastra-demo", // Replace with your project name
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const mastra = new Mastra({
  agents: {
    assistant: new Agent({
      name: "Assistant",
      instructions: "You only respond in haikus.",
      model: "openai/gpt-5-mini",
    }),
  },
});

const response = await mastra
  .getAgent("assistant")
  .generate("Tell me about recursion in programming.");
console.log(response.text);

Run with the import hook

node --import braintrust/hook.mjs mastra-app.js

The auto-instrumentation example uses plain JavaScript so node --import can run the file directly. The Braintrust APIs work the same in TypeScript projects. Compile your TypeScript to JavaScript and run the compiled file with the import hook, or run TypeScript directly with a TypeScript loader.

If you’re using a bundler, see Trace LLM calls for plugin and loader setup.

Manual instrumentation

To configure tracing explicitly, add a Braintrust exporter to Mastra’s Observability settings yourself. Use the BraintrustObservabilityExporter built into the braintrust SDK:

trace-mastra.ts

import { Agent } from "@mastra/core/agent";
import { Mastra } from "@mastra/core/mastra";
import { Observability } from "@mastra/observability";
import { BraintrustObservabilityExporter, initLogger } from "braintrust";

initLogger({ projectName: "mastra-demo" });

const mastra = new Mastra({
  agents: {
    assistant: new Agent({
      name: "Assistant",
      instructions: "You only respond in haikus.",
      model: "openai/gpt-5-mini",
    }),
  },
  observability: new Observability({
    configs: {
      braintrust: {
        serviceName: "mastra-demo",
        exporters: [new BraintrustObservabilityExporter()],
      },
    },
  }),
});

Alternatively, use the BraintrustExporter from the Mastra-maintained @mastra/braintrust package, which accepts a Braintrust logger directly:

trace-mastra-exporter.ts

import { Agent } from "@mastra/core/agent";
import { Mastra } from "@mastra/core/mastra";
import { Observability } from "@mastra/observability";
import { BraintrustExporter } from "@mastra/braintrust";
import { initLogger } from "braintrust";

const logger = initLogger({ projectName: "mastra-demo" });

const exporter = new BraintrustExporter({
  braintrustLogger: logger,
});

const mastra = new Mastra({
  agents: {
    assistant: new Agent({
      name: "Assistant",
      instructions: "You only respond in haikus.",
      model: "openai/gpt-4o-mini",
    }),
  },
  observability: new Observability({
    configs: {
      braintrust: {
        serviceName: "demo",
        exporters: [exporter],
      },
    },
  }),
});

async function main() {
  const agent = mastra.getAgent("assistant");
  const response = await agent.generate("Tell me about recursion in programming.");
  console.log(response.text);
}

main();

The BraintrustExporter constructor can accept a braintrust.Span, braintrust.Experiment, or braintrust.Logger as the braintrustLogger option. This enables automatic nesting of Mastra traces within Braintrust contexts like evals or traced functions.

What Braintrust traces

Braintrust captures:

Agent run spans (agent run: <name>) and workflow run spans (workflow run: <name>) as task spans, with inputs and outputs.
LLM spans (llm: <model>) for model generations, with the messages as input and the response as output.
Workflow step spans (workflow step: <id>) and tool call spans for the steps and tools an agent or workflow runs.
Token usage metrics (prompt, completion, total, plus cached, cache-creation, and reasoning tokens when reported) on LLM spans.
Span metadata, including entity_id, entity_name, and entity_type, plus the model and provider on LLM spans.
Errors captured on every span.

Evaluate with Mastra

Use Mastra agents as the task in a Braintrust Eval to build and evaluate agentic workflows:

eval-mastra.ts

import { Agent } from "@mastra/core/agent";
import { Mastra } from "@mastra/core/mastra";
import { Observability } from "@mastra/observability";
import { BraintrustExporter } from "@mastra/braintrust";
import { Eval, initLogger } from "braintrust";

const logger = initLogger({ projectName: "mastra-demo" });

const exporter = new BraintrustExporter({
  braintrustLogger: logger,
});

const mastra = new Mastra({
  agents: {
    assistant: new Agent({
      name: "Assistant",
      instructions: "You only respond in haikus.",
      model: "openai/gpt-4o-mini",
    }),
  },
  observability: new Observability({
    configs: {
      braintrust: {
        serviceName: "demo",
        exporters: [exporter],
      },
    },
  }),
});

Eval('mastra-demo', {
  data: () => [
    { input: 'What is the capital of France?', expected: 'Paris' },
    { input: 'What is 2+2?', expected: '4' },
  ],
  task: async (input: string) => {
    const agent = mastra.getAgent('assistant');
    return (await agent.generate(input)).text;
  },
  scores: [
    (args: { output: string; expected: string }) => ({
      name: 'contains_answer',
      score: String(args.output).toLowerCase().includes(String(args.expected).toLowerCase()) ? 1 : 0,
    }),
  ],
});

AI providers

SDKs

Developer tools

Runtime environments

Setup

Trace with Mastra

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Evaluate with Mastra

Resources

​Setup

​Trace with Mastra

​Auto-instrumentation

​Manual instrumentation

​What Braintrust traces

​Evaluate with Mastra

​Resources

Setup

Trace with Mastra

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Evaluate with Mastra

Resources