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}`;
      },
    },
  },
});