# Mastra

LangWatch traces agents built with Mastra, the TypeScript agent framework.

> Page: https://langwatch.ai/docs/integration/typescript/integrations/mastra
> Source: https://github.com/langwatch/langwatch/blob/main/docs/integration/typescript/integrations/mastra.mdx
> Index of all pages: https://langwatch.ai/docs/llms.txt

> **Tip:** **Quick setup?** Instead of following these steps manually, [copy a prompt](https://langwatch.ai/docs/skills/directory) into your coding agent and it will set this up for you automatically.

LangWatch integrates with Mastra through OpenTelemetry to capture traces from your Mastra agents automatically.

## Installation

**npm**

```bash npm
npm i langwatch @mastra/core @ai-sdk/openai @mastra/observability @mastra/otel-exporter @mastra/libsql
```

**pnpm**

```bash pnpm
pnpm add langwatch @mastra/core @ai-sdk/openai @mastra/observability @mastra/otel-exporter @mastra/libsql
```

**yarn**

```bash yarn
yarn add langwatch @mastra/core @ai-sdk/openai @mastra/observability @mastra/otel-exporter @mastra/libsql
```

**bun**

```bash bun
bun add langwatch @mastra/core @ai-sdk/openai @mastra/observability @mastra/otel-exporter @mastra/libsql
```

## Usage

Configure your Mastra instance with OpenTelemetry exporter pointing to LangWatch:

```typescript
import { Agent } from "@mastra/core/agent";
import { Mastra } from "@mastra/core";
import { openai } from "@ai-sdk/openai";
import { Observability } from "@mastra/observability";
import { OtelExporter } from "@mastra/otel-exporter";
import { LibSQLStore } from "@mastra/libsql";

export const mastra = new Mastra({
  agents: {
    assistant: new Agent({
      name: "assistant",
      instructions: "You are a helpful assistant.",
      model: openai("gpt-6-luna"),
    }),
  },
  storage: new LibSQLStore({ id: "mastra-storage", url: "file:./mastra.db" }),
  observability: new Observability({
    configs: {
      langwatch: {
        serviceName: "<project_name>",
        exporters: [
          new OtelExporter({
            provider: {
              custom: {
                endpoint: "https://app.langwatch.ai/api/otel/v1/traces",
                headers: { Authorization: `Bearer ${process.env.LANGWATCH_API_KEY}` },
              },
            },
          }),
        ],
      },
    },
  }),
});
```

Mastra automatically sends traces to LangWatch through the OpenTelemetry exporter. All agent interactions, tool calls, and workflow executions will be captured.

## Check it worked

Run the example. The SDK flushes pending spans when the process exits. Then open your project in LangWatch: a new trace appears in the traces list within a few seconds. Open it to see the Mastra agent run and its model calls.

If no trace appears, check that `LANGWATCH_API_KEY` is set in the environment the process runs in.

## Related

- [Capturing RAG](https://langwatch.ai/docs/integration/typescript/tutorials/capturing-rag) - Learn how to capture RAG data from retrievers and tools
- [Capturing Metadata and Attributes](https://langwatch.ai/docs/integration/typescript/tutorials/capturing-metadata) - Add custom metadata and attributes to your traces and spans
- [Capturing Evaluations & Guardrails](https://langwatch.ai/docs/integration/python/tutorials/capturing-evaluations-guardrails) - Log evaluations and implement guardrails in your Mastra applications

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.
