追踪 Mastra 应用

Mastra 是一个用于构建 AI 应用和 agent 的 TypeScript 框架。借助 Mastra 的 LangSmith exporter，你可以把 Mastra agent 和工作流的追踪发送到 LangSmith，用于调试、评估和可观测性。

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

安装

安装 Mastra 和 LangSmith exporter：

npm install @mastra/core @mastra/langsmith @mastra/observability @mastra/libsql

设置

1. 设置你的 LangSmith API key 以及（可选的）LangSmith 项目名称：

   export LANGSMITH_API_KEY=<your_langsmith_api_key>
   export LANGCHAIN_PROJECT=<your_project_name> # optional

TIP

如果未设置 LANGCHAIN_PROJECT，追踪将发送到默认项目。

2. 如果你计划使用 OpenAI 模型，还要确保运行时可以使用 OpenAI API key：

   export OPENAI_API_KEY=<your_openai_api_key>

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

   src/
       mastra.ts
       agent.ts
       index.ts

为 Mastra 配置 LangSmith exporter

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

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

  // Disable deprecated telemetry system
  telemetry: {
    enabled: false,
  },
});

• 追踪需要 Storage（即使将追踪导出到外部也需要）。
• LangSmith exporter 从环境变量读取凭据。
• 已弃用的 telemetry 系统 会被禁用，以避免警告。
• 在 Mastra server 之外运行 Mastra 时，无需单独的 instrumentation 文件。 更多细节请参阅 Mastra 文档。

定义 agent

为保持兼容性，请使用基于字符串的模型标识符。将以下代码添加到 agent.ts 文件：

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 key 自动路由模型调用，并捕获每次调用的追踪。

运行 agent

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

   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. 运行你的应用：

   npx ts-node src/index.ts

在 LangSmith 中查看追踪

运行 agent 后：

1. 打开 LangSmith UI。
2. 选择你的项目。例如 LANGCHAIN_PROJECT 的值。
3. 找到与 echoAgent.generate 对应的追踪。

你将能够检查：

• 模型输入和输出
• agent 执行步骤
• 计时和错误信息

---