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.
• 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 for a full walkthrough.

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

export ADALINE_API_KEY="your-api-key"
export ADALINE_PROJECT_ID="your-project-id"

Install

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.

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! });

For production guidance — buffering, batching, retries, serverless flushing, and graceful shutdown — see Instrument with the Adaline SDK.

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.

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.

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.

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

Instrument with the Adaline SDK

Monitor lifecycle, buffering and batching, retries, serverless flushing, and graceful shutdown.

SDK reference

Full class and type reference for the TypeScript and Python SDKs.

All integrations

Browse every framework and AI-provider integration Adaline supports.

View your logs

Open Adaline to see traces and spans land in your project.