Braintrust

快速开始

使用 Braintrust 蓝图为现有 Flue 项目添加跟踪功能。在终端或你选择的编码智能体中运行以下命令：

flue add tooling braintrust

概述

Braintrust 蓝图会在源代码根目录创建 braintrust.ts，并从 app.ts 中导入一次。生成的模块在 API 密钥可用时初始化 Braintrust，然后将 Braintrust 的 Flue 观察器连接到运行时事件流：

import { observe } from '@flue/runtime';
import { braintrustFlueObserver, initLogger } from 'braintrust';

if (process.env.BRAINTRUST_API_KEY) {
  initLogger({
    projectName: process.env.BRAINTRUST_PROJECT_NAME ?? 'Flue',
    apiKey: process.env.BRAINTRUST_API_KEY,
  });

  observe((event, ctx) => {
    const compatible = compatibleEvent(event);
    if (compatible) braintrustFlueObserver(compatible, ctx);
  });
}

省略的 compatibleEvent(...) 辅助函数会为蓝图安装的 Braintrust 版本转换当前的 Flue 工具和恢复事件。相同的模块在 Node.js 和 Cloudflare 上运行；与 Sentry 不同，Braintrust 不需要单独的 Cloudflare 包或 Durable Object 包装器。

配置完成后，智能体操作会显示为带有嵌套跨度的跟踪，包括模型轮次、工具、委托任务和压缩。

配置

永远不要提交 API 密钥；在 Cloudflare 上，将其存储为 Worker 密钥，而不是 Wrangler vars 值。当密钥不存在时，集成不会初始化或订阅，应用继续运行而不进行跟踪导出。

蓝图会安装 Braintrust 3.17 并通过 observe(...) 注册其公共 Flue 观察器。相同的源代码通过 Braintrust 的 workerd 导出在 Node.js 和 Cloudflare 上构建；不需要单独的 Cloudflare 包或 Durable Object 包装器。

Braintrust 还提供了一个 Node 导入钩子，用于仅 Node 的自动检测。生成的手动观察器是可能针对任一运行时的项目的可移植路径。

有关 Braintrust 与 OpenTelemetry 和 Sentry 的比较，请参阅可观测性。

Braintrust 跟踪内容

• 提示、技能或压缩操作成为 flue.<kind> 任务跨度。
• 模型轮次成为带有输入、输出、错误和使用指标的 llm:<model> 跨度。
• 工具调用成为嵌套的 tool:<name> 跨度。
• 委托任务成为嵌套的任务跨度。
• 上下文压缩成为嵌套的压缩跨度。

模型跨度包括令牌使用量和可用时的估计成本。跟踪保留智能体实例、会话、操作和可选的 submissionId 关联。有关 Flue 的身份和观察器模型，请参阅可观测性。

Braintrust 3.17 期望终端工具事件使用之前的 tool_call 名称，因此生成的桥接会为安装的版本转换工具事件。在升级 Braintrust 之前，请重新检查该转换。

保护敏感内容

Braintrust 跟踪是包含内容的。其观察器可以导出模型消息和输出、推理、系统提示、工具定义和值、任务提示和结果、错误以及关联元数据。

在生产环境中启用之前，请审查保留、访问、隐私和合规要求。当内容需要编辑时，在初始化之前使用 Braintrust 的 setMaskingFunction(...)，并针对代表性提示、推理、工具数据、错误、密钥和个人信息测试特定于应用的屏蔽器。

Cloudflare 交付

在 Cloudflare 上，每个生成的智能体 Durable Object 导出自己的活动。Braintrust 异步刷新，但 Flue 观察器无法将最终上传附加到 Durable Object 执行生命周期。因此，交付是尽力而为的，当工作完成后隔离立即变为空闲时，可能会丢失最终跨度。

在启用 Cloudflare 导出之前确认该权衡，并在部署的 Worker 中验证交付。Node 使用 Braintrust 的进程退出刷新回退。

验证

针对非生产 Braintrust 项目运行一个带有模型轮次和工具调用的智能体。确认跟踪层次结构、关闭的工具跨度、使用数据和 Flue 关联。在 Cloudflare 上，另外验证在部署的隔离生命周期下的最终跨度交付。