LangSmith exporter

LangSmith 是 LangChain 用于监控和评估 LLM 应用的平台。LangSmith exporter 会将 Trace 发送到 LangSmith，帮助你深入了解模型性能、进行调试，并支持评估 Workflow。

安装

npm

npm install @mastra/langsmith@latest

pnpm

pnpm add @mastra/langsmith@latest

Yarn

yarn add @mastra/langsmith@latest

Bun

bun add @mastra/langsmith@latest

配置

前提条件

1. LangSmith 账户：在 smith.langchain.com 注册
2. API key：在 LangSmith Settings → API Keys 中生成
3. 环境变量：设置凭据

.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

零配置设置

设置环境变量后，无需任何配置即可使用 exporter：

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()],
      },
    },
  }),
})

显式配置

你也可以直接传入凭据（优先于环境变量）：

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,
          }),
        ],
      },
    },
  }),
})

配置选项

完整配置

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
})

环境变量

变量	说明
LANGSMITH_API_KEY	LangSmith API key（必需）
LANGCHAIN_PROJECT	Trace 的默认项目名称（可选，默认为 "default"）
LANGSMITH_BASE_URL	自托管实例的 API URL（可选）

projectName 配置选项优先于 LANGCHAIN_PROJECT 环境变量，因此你可以通过程序将 Trace 路由到不同项目。

动态配置

你可以使用 withLangsmithMetadata 在运行时按 span 覆盖 LangSmith 设置。这适合根据运行时条件（例如客户、环境或功能）将 Trace 路由到不同项目。

使用 helper

将 withLangsmithMetadata 与 buildTracingOptions 配合使用，以设置 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' })),
  },
})

动态项目路由

使用 requestContext 根据运行时条件将 Trace 路由到不同项目。

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

可用字段

withLangsmithMetadata helper 接受以下字段：

字段	类型	说明
projectName	string	覆盖此 Trace 的项目
sessionId	string	按 session 对相关 Trace 分组
sessionName	string	session 的显示名称

所有字段均为可选。该 helper 会与已有元数据合并，因此你可以多次调用它，或与其他 tracing 选项结合使用。

相关内容

• Tracing 概览
• LangSmith 文档