Mastra

Mastra is a TypeScript framework for agents + workflows + RAG, built on the Vercel AI SDK. There is no dedicated patchMastra() adapter yet — but because Mastra calls the Vercel AI SDK for every model invocation, patchVercelAI captures the full trace today. A dedicated adapter that adds workflow-step + memory + RAG attribution is shipping shortly.

Install

npm install @trefur/observe @mastra/core ai @ai-sdk/openai

Setup

import { Mastra } from '@mastra/core';
import { Agent } from '@mastra/core/agent';
import { openai } from '@ai-sdk/openai';
import * as ai from 'ai';
import { TrefurObserve, patchVercelAI } from '@trefur/observe';

// Initialise observe once at startup.
TrefurObserve.init({
  apiKey: process.env.TREFUR_API_KEY!,
  agent: { name: 'mastra-orchestrator', framework: 'mastra' },
});
// Mastra wraps the Vercel AI SDK under the hood. patchVercelAI takes the
// imported 'ai' module namespace plus the observe instance, and captures
// every agent call, tool invocation, and workflow step today. A
// dedicated patchMastra() adapter that adds explicit workflow-step
// attribution is on the roadmap.
patchVercelAI(ai, TrefurObserve.getInstance());

const supportAgent = new Agent({
  name: 'support',
  instructions: 'Answer customer questions about orders.',
  model: openai('gpt-4o'),
});

export const mastra = new Mastra({
  agents: { support: supportAgent },
});

const response = await supportAgent.generate('Where is order #12345?');

What gets traced (today)

  • Agent calls — every agent.generate / agent.stream.
  • Tool calls — Mastra tools are Vercel-AI tools under the hood, so they emit as steps.
  • Workflow steps — each step that calls an LLM or tool is captured (steps that are pure JS are not).
  • RAG queries — when Mastra calls a vector store via the Vercel AI SDK retrieval interface.

What the dedicated adapter will add

  • Explicit per-workflow-step boundaries (including non-LLM steps).
  • Memory read + write spans tagged with thread id.
  • Cross-agent handoffs in multi-agent Mastra workflows rendered as parent-child runs.

Common pitfalls

  • Workflow context. Mastra workflows pass data through context. The context object isn't captured by default. For pure-JS steps that don't call an LLM, emit an explicit telemetry record with the SDK's record() method: TrefurObserve.getInstance().record({ framework: 'custom', agent_name: 'mastra-orchestrator', status: 'completed', started_at: new Date().toISOString(), steps: [{ step_type: 'custom', started_at: new Date().toISOString(), status: 'completed' }] }).
  • Memory + RAG with custom backends. If you wire Mastra to a raw vector store (not via the Vercel AI SDK retrieval interface) you'll miss retrieval steps until the dedicated adapter lands. As a workaround, enable the generic HTTP instrumentor: TrefurObserve.getInstance().observe({ http: true, fetch: true }).

See the JavaScript SDK reference for patchVercelAI details.