> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 追踪 Mastra 应用

[Mastra](https://mastra.ai/docs) 是一个用于构建 AI 驱动的应用程序和代理的 TypeScript 框架。使用 Mastra 的 [LangSmith 导出器](https://mastra.ai/docs/observability/ai-tracing/exporters/langsmith)，您可以将来自 Mastra 代理和工作流的追踪数据发送到 LangSmith，用于调试、评估和可观测性。

本指南将向您展示如何使用 Mastra 的 AI 追踪系统将 Mastra 与 LangSmith 集成。

## 安装

安装 Mastra 和 LangSmith 导出器：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
npm install @mastra/core @mastra/langsmith @mastra/observability @mastra/libsql
```

## 设置

1. 设置您的 LangSmith API 密钥和（可选的）LangSmith 项目名称：

   ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
   export LANGSMITH_API_KEY=<your_langsmith_api_key>
   export LANGCHAIN_PROJECT=<your_project_name> # 可选
   ```

   <Tip>
     如果未设置 [`LANGCHAIN_PROJECT`](/langsmith/log-traces-to-project)，追踪数据将被发送到默认项目。
   </Tip>

2. 如果您计划使用 OpenAI 模型，请确保在运行时也有可用的 OpenAI API 密钥：

   ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
   export OPENAI_API_KEY=<your_openai_api_key>
   ```

3. 在您的项目目录中，创建以下项目结构和文件：

   ```
   src/
       mastra.ts
       agent.ts
       index.ts
   ```

## 使用 LangSmith 导出器配置 Mastra

Mastra 追踪直接在 `Mastra` 构造函数上进行配置。将以下内容添加到 `mastra.ts` 文件中：

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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,
          }),
        ],
      },
    },
  },

  // 禁用已弃用的遥测系统
  telemetry: {
    enabled: false,
  },
});
```

* [追踪需要存储](https://mastra.ai/docs/observability/ai-tracing/overview#basic-config)（即使将追踪数据导出到外部）。
* LangSmith 导出器从环境变量读取凭据。
* [已弃用的遥测系统](https://mastra.ai/docs/observability/overview#otel-tracing-deprecated) 已被禁用以避免警告。
* 在 Mastra 服务器之外运行 Mastra 时，不需要单独的检测文件。
  更多详情，请参阅 [Mastra 文档](https://mastra.ai/docs/observability/ai-tracing/overview)。

### 定义代理

为兼容性起见，请使用[基于字符串的模型标识符](https://mastra.ai/models#basic-usage)。将以下代码添加到 `agent.ts` 文件中：

```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { Agent } from "@mastra/core/agent";

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

Mastra 将使用您配置的 API 密钥自动路由模型调用，并捕获每次调用的追踪数据。

### 运行代理

1. 将以下内容添加到 `index.ts` 文件中：

   ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
   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. 运行您的应用程序：

   ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
   npx ts-node src/index.ts
   ```

## 在 LangSmith 中查看追踪数据

运行代理后：

1. 打开 [LangSmith UI](https://smith.langchain.com)。
2. 选择您的项目。例如，`LANGCHAIN_PROJECT` 的值。
3. 找到与 `echoAgent.generate` 对应的追踪数据。

您将能够检查：

* 模型输入和输出
* 代理执行步骤
* 计时和错误信息

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/trace-with-mastra.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>