For a complete example, check out our Mastra integration example on GitHub.
Mastra is a framework for building AI agents with built-in support for multiple LLM providers. This guide shows you how to integrate Gentrace with Mastra to trace and monitor your AI agents.

​
Prerequisites

​
Installation

npm install @mastra/core gentrace @ai-sdk/openai

​
Configuration

Initialize both Gentrace and Mastra in your application: 
import { init, interaction } from 'gentrace';
import { Mastra } from '@mastra/core';
import { createOpenAI } from '@ai-sdk/openai';

async function main() {
  // Initialize Gentrace
  init({
    apiKey: process.env.GENTRACE_API_KEY,
  });

  // Create OpenAI provider
  const openai = createOpenAI({
    apiKey: process.env.OPENAI_API_KEY,
  });

  // Initialize Mastra with Gentrace telemetry
  const mastra = new Mastra({
    openai,
    telemetry: {
      gentrace: {
        apiKey: process.env.GENTRACE_API_KEY,
      },
    },
  });
}

// Run the main function
main().catch(console.error);

​
Usage

Here’s a complete example showing how to create and use a Mastra agent with Gentrace tracing:
agents/email-assistant.ts
import { Agent } from '@mastra/core';

// Create an agent
const emailAssistant = new Agent({
  name: 'EmailAssistant',
  model: 'gpt-4o-mini',
  instructions:
    'You are a helpful email assistant. Help users write professional emails.',
  provider: 'OPENAI',
});

// Use the agent within a Gentrace interaction
async function generateEmail(subject: string, context: string) {
  return await interaction(
    'generate-email',
    async () => {
      const response = await emailAssistant.text({
        messages: [
          {
            role: 'user',
            content: `Write a professional email about: ${subject}\nContext: ${context}`,
          },
        ],
      });

      return response.text;
    },
    {
      pipelineId: process.env.GENTRACE_PIPELINE_ID!,
      metadata: {
        subject,
        agentName: 'EmailAssistant',
      },
    },
  );
}

​
Environment Variables

Create a .env file with your API keys:
.env
GENTRACE_API_KEY=your-gentrace-api-key
GENTRACE_PIPELINE_ID=your-pipeline-id
OPENAI_API_KEY=your-openai-api-key

​
Advanced Features

​
Using Multiple Agents

Mastra supports creating multiple agents with different configurations: 
const technicalAgent = new Agent({
  name: 'TechnicalWriter',
  model: 'gpt-4o',
  instructions: 'You are a technical documentation expert.',
  provider: 'OPENAI',
});

const creativeAgent = new Agent({
  name: 'CreativeWriter',
  model: 'gpt-4o-mini',
  instructions: 'You are a creative content writer.',
  provider: 'OPENAI',
});

​
Agent Tools and Functions

Mastra agents can use tools and functions, which are automatically traced by Gentrace: 
const researchAgent = new Agent({
  name: 'ResearchAssistant',
  model: 'gpt-4o',
  instructions: 'You help with research tasks.',
  provider: 'OPENAI',
  tools: {
    searchWeb: {
      description: 'Search the web for information',
      input: z.object({
        query: z.string(),
      }),
      execute: async ({ query }) => {
        // Your search implementation
        return `Search results for: ${query}`;
      },
    },
  },
});