Trace Mastra agents

Installation

npm install @mastra/core @mastra/langsmith @mastra/observability @mastra/libsql

Setup

1. Set your LangSmith API key and the selected environment’s tracer_session_name:
   export LANGSMITH_API_KEY=<your_langsmith_api_key>
   export LANGCHAIN_PROJECT=<your_project_name> # optional
   
   Set LANGCHAIN_PROJECT explicitly to the selected environment’s tracer_session_name.
2. If you plan to use OpenAI models, also ensure you have an OpenAI API key available at runtime:
   export OPENAI_API_KEY=<your_openai_api_key>
   
3. In your project directory, create the following project structure and files:
   src/
       mastra.ts
       agent.ts
       index.ts
   

Configure Mastra with the LangSmith exporter

import { Mastra } from "@mastra/core";
import { LibSQLStore } from "@mastra/libsql";
import { LangSmithExporter } from "@mastra/langsmith";

import { echoAgent } from "./agent";

export const mastra = new Mastra({
  agents: { echoAgent },

  storage: new LibSQLStore({
    url: "file:./mastra.db",
  }),

  observability: {
    configs: {
      langsmith: {
        serviceName: "mastra-langsmith-demo",
        exporters: [
          new LangSmithExporter({
            apiKey: process.env.LANGSMITH_API_KEY,
          }),
        ],
      },
    },
  },

  // Disable deprecated telemetry system
  telemetry: {
    enabled: false,
  },
});

• Storage is required for tracing (even when exporting traces externally).
• The LangSmith exporter reads credentials from environment variables.
• The deprecated telemetry system is disabled to avoid warnings.
• No separate instrumentation file is required when running Mastra outside of the Mastra server. For more details, refer to the Mastra docs.

Define an agent

import { Agent } from "@mastra/core/agent";

export const echoAgent = new Agent({
  name: "echoAgent",
  instructions: "You are a helpful assistant.",
  model: "openai/gpt-6-luna",
});

Run the agent

1. Add the following to an index.ts file:
   import { mastra } from "./mastra";
   
   async function main() {
   const agent = mastra.getAgent("echoAgent");
   const result = await agent.generate("Say hello and explain what Mastra is.");
   console.log(result.text);
   }
   
   main();
   
2. Run your agent:
   npx ts-node src/index.ts
   

View traces in LangSmith

1. Open the LangSmith UI.
2. Select the agent and environment configured through LANGCHAIN_PROJECT.
3. Locate the trace corresponding to echoAgent.generate.

• Model inputs and outputs
• Agent execution steps
• Timing and error information