Exporter LangSmith

LangSmith est la plateforme de LangChain destinée à la surveillance et à l'évaluation des applications fondées sur des LLM. L'exporter LangSmith envoie vos traces à LangSmith afin de fournir des informations sur les performances des modèles, des fonctions de débogage et des Workflows d'évaluation.

Installation

npm

npm install @mastra/langsmith@latest

pnpm

pnpm add @mastra/langsmith@latest

Yarn

yarn add @mastra/langsmith@latest

Bun

bun add @mastra/langsmith@latest

Configuration

Prérequis

1. Compte LangSmith : inscrivez-vous sur smith.langchain.com
2. Clé d'API : générez une clé d'API dans Settings → API Keys de LangSmith
3. Variables d'environnement : définissez vos identifiants

.env

# Required
LANGSMITH_API_KEY=ls-xxxxxxxxxxxx

# Optional
LANGCHAIN_PROJECT=my-project  # Default project for traces
LANGSMITH_BASE_URL=https://api.smith.langchain.com  # For self-hosted

Configuration automatique

Une fois les variables d’environnement définies, utilisez l’exporter sans configuration :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { LangSmithExporter } from '@mastra/langsmith'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      langsmith: {
        serviceName: 'my-service',
        exporters: [new LangSmithExporter()],
      },
    },
  }),
})

Configuration explicite

Vous pouvez également transmettre les identifiants directement ; ils prévalent sur les variables d’environnement :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { LangSmithExporter } from '@mastra/langsmith'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      langsmith: {
        serviceName: 'my-service',
        exporters: [
          new LangSmithExporter({
            apiKey: process.env.LANGSMITH_API_KEY,
          }),
        ],
      },
    },
  }),
})

Options de configuration

Configuration complète

new LangSmithExporter({
  // Required credentials
  apiKey: process.env.LANGSMITH_API_KEY!,

  // Optional settings
  apiUrl: process.env.LANGSMITH_BASE_URL, // Default: https://api.smith.langchain.com
  projectName: 'my-project', // Project to send traces to (overrides LANGCHAIN_PROJECT env var)
  callerOptions: {
    // HTTP client options
    timeout: 30000, // Request timeout in ms
    maxRetries: 3, // Retry attempts
  },
  logLevel: 'info', // Diagnostic logging: debug | info | warn | error

  // LangSmith-specific options
  hideInputs: false, // Hide input data in UI
  hideOutputs: false, // Hide output data in UI
})

Variables d'environnement

Variable	Description
LANGSMITH_API_KEY	Votre clé d'API LangSmith (requise)
LANGCHAIN_PROJECT	Nom du projet par défaut pour les traces (facultatif, valeur par défaut : « default »)
LANGSMITH_BASE_URL	URL d'API des instances auto-hébergées (facultatif)

L'option de configuration projectName prévaut sur la variable d'environnement LANGCHAIN_PROJECT, ce qui permet d'acheminer les traces par programmation vers différents projets.

Configuration dynamique

Vous pouvez remplacer à l'exécution les paramètres LangSmith de chaque span au moyen de withLangsmithMetadata. Cela permet d'acheminer les traces vers différents projets selon les conditions d'exécution, par exemple le client, l'environnement ou la fonctionnalité.

Utiliser la fonction d'assistance

Utilisez withLangsmithMetadata avec buildTracingOptions pour définir des options propres à LangSmith :

src/agents/support-agent.ts

import { Agent } from '@mastra/core/agent'
import { buildTracingOptions } from '@mastra/observability'
import { withLangsmithMetadata } from '@mastra/langsmith'

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'support-agent',
  instructions: 'You are a helpful support agent.',
  model: 'openai/gpt-5.6-sol',
  defaultOptions: {
    tracingOptions: buildTracingOptions(withLangsmithMetadata({ projectName: 'customer-support' })),
  },
})

Acheminement dynamique des projets

Utilisez requestContext pour acheminer les traces vers différents projets selon les conditions d'exécution.

src/mastra/agents/support-agent.ts

import { Agent } from '@mastra/core/agent'
import { buildTracingOptions } from '@mastra/observability'
import { withLangsmithMetadata } from '@mastra/langsmith'

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'support-agent',
  instructions: 'You are a helpful support agent.',
  model: 'openai/gpt-5.6-sol',
  defaultOptions: ({ requestContext }) => {
    const userTier = requestContext?.get('user-tier') as string
    const userId = requestContext?.get('user-id') as string

    return {
      tracingOptions: buildTracingOptions(
        withLangsmithMetadata({
          projectName: userTier === 'enterprise' ? 'enterprise-traces' : 'standard-traces',
          sessionId: userId,
        }),
      ),
    }
  },
})

Champs disponibles

La fonction d'assistance withLangsmithMetadata accepte les champs suivants :

Champ	Type	Description
projectName	string	Remplace le projet pour cette trace
sessionId	string	Regroupe les traces associées par session
sessionName	string	Nom d'affichage de la session

Tous les champs sont facultatifs. La fonction d'assistance fusionne ces valeurs avec les métadonnées existantes ; vous pouvez donc l'appeler plusieurs fois ou la combiner à d'autres options de tracing.

Voir aussi

• Présentation du tracing
• Documentation de LangSmith