Skip to main content

​
Mastra

Mastra integration currently uses the MutagenT SDK directly with Mastra’s built-in observer support. A dedicated @mutagent/mastra package is coming soon to simplify setup. For now, you configure MutagenT as an observer directly in your Mastra config, and all agent executions, tool calls, and LLM interactions are automatically traced.

​
Installation

You only need the MutagenT SDK: 
bun add @mutagent/sdk
Peer dependencies: @mastra/core (your existing Mastra installation)

​
Quick Start

1

Set environment variables

Add your MutagenT API key to your .env file:
MUTAGENT_API_KEY=your-mutagent-api-key
2

Initialize tracing

Call initTracing() at application startup, before any Mastra agent runs.
import { initTracing } from '@mutagent/sdk/tracing';

initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });
3

Configure tracing in your Mastra entry point

Initialize tracing before your Mastra configuration. The SDK hooks into Mastra’s internal event system to capture agent lifecycle events.
// mastra.config.ts
import { defineConfig } from '@mastra/core';
import { initTracing } from '@mutagent/sdk/tracing';

initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });

export default defineConfig({
  // Your existing Mastra configuration
  agents: { /* ... */ },
});

​
Full Example

// mastra.config.ts
import { defineConfig } from '@mastra/core';
import { initTracing } from '@mutagent/sdk/tracing';

// Initialize MutagenT tracing
initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });

export default defineConfig({
  agents: {
    'support-agent': {
      name: 'Support Agent',
      model: 'gpt-4o',
      instructions: 'You are a helpful support agent.',
      tools: [searchKnowledgeBase, createTicket],
    },
  },
});

// Usage - traces are captured automatically
import { mastra } from './mastra.config';

const agent = mastra.getAgent('support-agent');
const response = await agent.generate('How do I reset my password?');
// Trace automatically sent to MutagenT

​
What Gets Traced

EventDescription
Agent executionsFull agent run lifecycle with input and output
Tool callsEach tool invocation with arguments and results
LLM callsUnderlying model calls made by the agent
ErrorsAgent and tool failures with error messages

​
CLI Shortcut

Mastra integration is coming soon. In the meantime, you can use the SDK directly for tracing. See the code example above.
Since Mastra uses a built-in observer pattern, MutagenT tracing works across all agents in your Mastra project once configured — no per-agent setup needed.