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

# Mastra

> Build AI agents with Mastra and Adaline.

# Mastra

Use the Adaline Mastra integration when you want Mastra agent execution data to flow into Adaline. The package supports two integration styles:

* `AdalineMastraCallbackHandler` for Mastra execution hooks
* `AdalineMastraExporter` for Mastra observability exporter flows

## Prerequisites

Before you start, make sure you have:

* An [Adaline account](https://app.adaline.ai/sign-up?utm_source=adaline.ai).
* A **workspace API key** — create one under **Settings → API keys**.
* Your **project ID** — copy it from **Monitor → Copy Project ID**.

See [Integrate your AI Agent](/docs/get-started/integrate-your-ai-agent) for a full walkthrough.

Set both as environment variables before running the examples on this page:

```bash theme={null}
export ADALINE_API_KEY="your-api-key"
export ADALINE_PROJECT_ID="your-project-id"
```

## Install

```bash theme={null}
npm install @adaline/client @adaline/mastra @mastra/core @mastra/observability @ai-sdk/openai
```

## Initialize Adaline

Create an Adaline client, then initialize a monitor for the target project.

```typescript theme={null}
import { Adaline } from "@adaline/client";

const adaline = new Adaline({ apiKey: process.env.ADALINE_API_KEY! });
const monitor = adaline.initMonitor({ projectId: process.env.ADALINE_PROJECT_ID! });
```

<Note>
  For production guidance — buffering, batching, retries, serverless flushing, and graceful shutdown — see [Instrument with the Adaline SDK](/docs/instrument/with-adaline-sdks).
</Note>

## Choose an integration path

Use whichever path matches how your Mastra app is instrumented:

* attach `AdalineMastraCallbackHandler` if you are adding execution hooks directly to agent runs
* configure `AdalineMastraExporter` if you are wiring into Mastra observability exporters

## Attach the Mastra callback handler

The callback handler exposes Mastra execution hooks through `getExecutionHooks()`. Those hooks can be passed into agent execution calls.

```typescript theme={null}
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { AdalineMastraCallbackHandler } from "@adaline/mastra";

const handler = new AdalineMastraCallbackHandler({
  monitor,
  name: "support-agent",
  referenceId: "support-agent-run",
});

const agent = new Agent({
  name: "support-agent",
  instructions: "Reply in one sentence.",
  model: openai("gpt-4o-mini"),
});

const result = await agent.generate("Say hello.", {
  maxTokens: 20,
  ...handler.getExecutionHooks(),
});

await monitor.flush();
```

## Configure the Mastra exporter

If your Mastra application is already using the observability exporter flow, you can attach the Adaline exporter there instead.

```typescript theme={null}
import { AdalineMastraExporter } from "@adaline/mastra";

const exporter = new AdalineMastraExporter({
  monitor,
});

// Attach `exporter` to your Mastra observability configuration.
```

## Use an existing parent trace or span

Both the callback handler and exporter accept an existing Adaline parent context, so Mastra work can be attached under a trace or span you created earlier.

```typescript theme={null}
const parentTrace = monitor.logTrace({
  name: "mastra-run",
  referenceId: "mastra-run-1",
});

const handler = new AdalineMastraCallbackHandler({
  monitor,
  name: "support-agent",
  parentTrace,
});
```

Pass either `parentTrace` or `parentSpan`, but not both.

## What the Mastra integration captures

The Mastra integration is designed to capture Mastra execution structure such as:

* root agent executions
* step completions
* iteration completions
* tool calls and tool results
* delegation start and completion events

This page focuses on the integration surface. The exact span tree depends on which Mastra hooks and observability events your application emits.

## Next steps

<CardGroup cols={2}>
  <Card title="Instrument with the Adaline SDK" icon="code" href="/docs/instrument/with-adaline-sdks">
    Monitor lifecycle, buffering and batching, retries, serverless flushing, and graceful shutdown.
  </Card>

  <Card title="SDK reference" icon="braces" href="/docs/reference/sdk/v2/overview">
    Full class and type reference for the TypeScript and Python SDKs.
  </Card>

  <Card title="All integrations" icon="layout-grid" href="/docs/integrations/introduction">
    Browse every framework and AI-provider integration Adaline supports.
  </Card>

  <Card title="View your logs" icon="line-chart" href="https://app.adaline.ai">
    Open Adaline to see traces and spans land in your project.
  </Card>
</CardGroup>