> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# LangSmith exporter

[LangSmith](https://smith.langchain.com/) 是 LangChain 用於監察及評估 LLM 應用程式的平台。LangSmith exporter 會將你的 Trace 傳送至 LangSmith，讓你深入了解模型效能、進行除錯，以及執行評估 Workflow。

## 安裝

**npm**:

```bash
npm install @mastra/langsmith@latest
```

**pnpm**:

```bash
pnpm add @mastra/langsmith@latest
```

**Yarn**:

```bash
yarn add @mastra/langsmith@latest
```

**Bun**:

```bash
bun add @mastra/langsmith@latest
```

## 配置

### 前置要求

1. **LangSmith 帳戶**：在 [smith.langchain.com](https://smith.langchain.com) 註冊
2. **API 金鑰**：在 LangSmith Settings → API Keys 產生 API 金鑰
3. **環境變數**：設定你的憑證

```bash
# 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，無需提供任何配置：

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

### 明確配置

你亦可直接傳入憑證（優先於環境變數）：

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

## 配置選項

### 完整配置

```typescript
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 金鑰（必填）         |
| `LANGCHAIN_PROJECT`  | Trace 的預設項目名稱（選填，預設為 "default"） |
| `LANGSMITH_BASE_URL` | 自行託管實例的 API URL（選填）             |

`projectName` 配置選項的優先級高於 `LANGCHAIN_PROJECT` 環境變數，讓你能以程式方式將 Trace 路由至不同項目。

## 動態配置

你可以使用 `withLangsmithMetadata`，在執行階段為每個 span 覆寫 LangSmith 設定。這適合用於根據執行階段條件（例如客戶、環境或功能），將 Trace 路由至不同項目。

### 使用 helper

配合 `buildTracingOptions` 使用 `withLangsmithMetadata`，以設定 LangSmith 專用選項：

```typescript
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 路由至不同項目。

```typescript
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 選項配合使用。

## 相關內容

- [Trace 概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)
- [LangSmith 文件](https://docs.smith.langchain.com/)