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 中產生 API Key
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	自行代管 instance 的 API URL（選用）

projectName 設定選項優先於 LANGCHAIN_PROJECT 環境變數，讓你能以程式方式將 Trace 導向不同專案。

動態設定

你可以使用 withLangsmithMetadata，在 runtime 依個別 span 覆寫 LangSmith 設定。若要根據 runtime 條件（例如客戶、環境或功能）將 Trace 導向不同專案，這項功能非常實用。

使用 helper

搭配 buildTracingOptions 使用 withLangsmithMetadata，設定 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，根據 runtime 條件將 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 會與任何現有的 metadata 合併，因此你可以多次呼叫，也可以與其他 Tracing 選項搭配使用。

相關內容

• Tracing 總覽
• LangSmith 文件