Gentrace Documentation

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

Node.js 20+
A Gentrace account and API key
A Mastra project

Installation

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

yarn add @mastra/core gentrace @ai-sdk/openai

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

Getting started

Error analysis

Tracing

Evaluation

Integrations

Administration

Reference

SDK Entities

Mastra

Prerequisites

Installation

Configuration

Usage

Environment Variables

Advanced Features

Using Multiple Agents

Agent Tools and Functions

​Prerequisites

​Installation

​Configuration

​Usage

​Environment Variables

​Advanced Features

​Using Multiple Agents

​Agent Tools and Functions

​Related Resources

Prerequisites

Installation

Configuration

Usage

Environment Variables

Advanced Features

Using Multiple Agents

Agent Tools and Functions

Related Resources