Skip to main content
Mastra is an agentic framework that simplifies building complex AI applications with multi-agent workflows, tool integrations, and memory management.

​
Launch Phoenix

  1. Sign up for an Arize Phoenix account at https://app.phoenix.arize.com/login
  2. Grab your API key from the Keys option on the left bar.
  3. In your code, configure environment variables for your endpoint and API key:
# .env, or shell environment

# Add Phoenix API Key for tracing
PHOENIX_API_KEY="ADD YOUR PHOENIX API KEY"
# And Collector Endpoint for Phoenix Cloud
PHOENIX_COLLECTOR_ENDPOINT="ADD YOUR PHOENIX HOSTNAME"

​
Install

npm install @mastra/arize

​
Configure Environment

Create a .env file that points Mastra to your Phoenix instance: 
PHOENIX_ENDPOINT=http://localhost:6006/v1/traces
PHOENIX_API_KEY=your-api-key # Optional for local Phoenix
PHOENIX_PROJECT_NAME=mastra-service # Optional, defaults to "mastra-service"

​
Setup

Initialize the Arize exporter inside your Mastra project: 
import { Mastra } from "@mastra/core";
import { ArizeExporter } from "@mastra/arize";

export const mastra = new Mastra({
  // ... other config (agents, workflows, etc.)
  observability: {
    configs: {
      arize: {
        serviceName: process.env.PHOENIX_PROJECT_NAME || "mastra-service",
        exporters: [
          new ArizeExporter({
            endpoint: process.env.PHOENIX_ENDPOINT!,
            apiKey: process.env.PHOENIX_API_KEY,
            projectName: process.env.PHOENIX_PROJECT_NAME,
          }),
        ],
      },
    },
  },
});

​
Create Agents and Tools

From here you can use Mastra as normal. Create agents with tools and run them: 
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { Mastra } from "@mastra/core";
import { ArizeExporter } from "@mastra/arize";
import { z } from "zod";

// Create a simple weather tool
const weatherTool = {
  name: "weatherTool",
  description: "Get current weather for a location",
  parameters: z.object({
    location: z.string().describe("The city and country"),
  }),
  execute: async ({ location }) => {
    // Simulate weather API call
    return {
      location,
      temperature: "22°C",
      condition: "Sunny",
      humidity: "60%",
    };
  },
};

// Create an agent
const weatherAgent = new Agent({
  name: "Weather Assistant",
  instructions: "You help users get weather information. Use the weather tool to get current conditions.",
  model: openai("gpt-4o-mini"),
  tools: { weatherTool },
});

// Register the agent with Mastra instance
const mastra = new Mastra({
  agents: { weatherAgent },
  observability: {
    configs: {
      arize: {
        serviceName: process.env.PHOENIX_PROJECT_NAME || "mastra-service",
        exporters: [
          new ArizeExporter({
            endpoint: process.env.PHOENIX_ENDPOINT!,
            apiKey: process.env.PHOENIX_API_KEY,
            projectName: process.env.PHOENIX_PROJECT_NAME,
          }),
        ],
      },
    },
  },
});

​
Running Your Application

To test your application with Phoenix tracing: 
# Start the Mastra dev server
mastra dev

## or, build and run the production server with instrumentation enabled
# npm run build
# node --import=./.mastra/output/instrumentation.mjs .mastra/output/index.mjs
This will:
  1. Initialize the tracing SDK with your observability configuration
  2. Start the Mastra playground at http://localhost:4111
  3. Enable trace export to Phoenix at http://localhost:6006
Interact with your agents:
  • Via Playground: Navigate to http://localhost:4111/playground to chat with agents
  • Via API: Make requests to the generated API endpoints
  • Programmatically: Create test scripts that run within the Mastra dev environment

​
Observe

Now that you have tracing setup, all agent runs, tool calls, and model interactions will be streamed to your running Phoenix for observability and evaluation.
Mastra traces in Phoenix

​
Resources