> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Mastra

If you are a coding agent, prefer the Braintrust [`bt` CLI](/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, such as ad-hoc lookups and exploration from your IDE.

[Mastra](https://mastra.ai/) 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:

<CodeGroup>
  ```bash Typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  # pnpm
  pnpm add @mastra/core @mastra/braintrust @mastra/observability braintrust
  # npm
  npm install @mastra/core @mastra/braintrust @mastra/observability braintrust
  ```
</CodeGroup>

## 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.

<Steps>
  <Step title="Build your Mastra app">
    ```javascript title="mastra-app.js" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    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);
    ```
  </Step>

  <Step title="Run with the import hook">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    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, then run the compiled file with the import hook.

    <Note>
      If you're using a bundler, see [Trace LLM calls](/instrument/trace-llm-calls#auto-instrumentation) for plugin and loader setup.
    </Note>
  </Step>
</Steps>

### Manual instrumentation

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

```typescript title="trace-mastra.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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`](https://www.npmjs.com/package/@mastra/braintrust) package, which accepts a Braintrust logger directly:

```typescript title="trace-mastra-exporter.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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();
```

<Note>
  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.
</Note>

### 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:

```typescript title="eval-mastra.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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,
    }),
  ],
});
```

## Resources

* [Mastra documentation](https://mastra.ai/)
* [Mastra observability guide](https://mastra.ai/en/docs/observability/ai-tracing)
* [Braintrust Eval guide](/evaluate/run-evaluations)