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

# Mastra

> Built-in observer for Mastra AI agent framework

# 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:

<CodeGroup>
  ```bash bun theme={null}
  bun add @mutagent/sdk
  ```

  ```bash npm theme={null}
  npm install @mutagent/sdk
  ```

  ```bash yarn theme={null}
  yarn add @mutagent/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @mutagent/sdk
  ```
</CodeGroup>

**Peer dependencies:** `@mastra/core` (your existing Mastra installation)

## Quick Start

<Steps>
  <Step title="Set environment variables">
    Add your MutagenT API key to your `.env` file:

    ```env theme={null}
    MUTAGENT_API_KEY=your-mutagent-api-key
    ```
  </Step>

  <Step title="Initialize tracing">
    Call `initTracing()` at application startup, before any Mastra agent runs.

    ```typescript theme={null}
    import { initTracing } from '@mutagent/sdk/tracing';

    initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });
    ```
  </Step>

  <Step title="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.

    ```typescript theme={null}
    // 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: { /* ... */ },
    });
    ```
  </Step>
</Steps>

## Full Example

```typescript theme={null}
// 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],
    },
  },
});
```

```typescript theme={null}
// 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

| Event            | Description                                     |
| ---------------- | ----------------------------------------------- |
| Agent executions | Full agent run lifecycle with input and output  |
| Tool calls       | Each tool invocation with arguments and results |
| LLM calls        | Underlying model calls made by the agent        |
| Errors           | Agent and tool failures with error messages     |

## CLI Shortcut

<Note>
  Mastra integration is coming soon. In the meantime, you can use the SDK directly for tracing. See the code example above.
</Note>

<Tip>
  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.
</Tip>