> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Flue

> Trace Flue agent workflows in Braintrust to debug LLM turns, tool calls, delegated tasks, and context compaction

If you are a coding agent, prefer the Braintrust [`bt` CLI](/docs/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, such as ad-hoc lookups and exploration from your IDE.

[Flue](https://flueframework.com/) is an open-source TypeScript agent harness framework. Braintrust traces Flue agent operations, including LLM turns, tool calls, delegated tasks, and context compaction.

<View title="TypeScript" icon="https://img.logo.dev/typescriptlang.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  <h2 id="setup-typescript">
    Setup
  </h2>

  Install Braintrust alongside the Flue runtime and CLI, then set your API key and optional project name. Install `@flue/runtime` and `@flue/cli` together so their versions stay aligned. Flue v2 instrumentation requires Braintrust v3.27.0 or later.

  <Steps>
    <Step title="Install packages">
      <CodeGroup>
        ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        pnpm add braintrust @flue/runtime @flue/cli
        ```

        ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        npm install braintrust @flue/runtime @flue/cli
        ```
      </CodeGroup>
    </Step>

    <Step title="Set environment variables">
      ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      BRAINTRUST_API_KEY=<your-braintrust-api-key>
      BRAINTRUST_PROJECT_NAME=<your-braintrust-project-name>
      ```
    </Step>
  </Steps>

  <h2 id="instrument-typescript">
    Instrument Flue
  </h2>

  Initialize Braintrust at module scope, then pass `braintrustFlueInstrumentation()` to Flue's `instrument(...)` API. The instrumentation observes runtime events and wraps agent, model, tool, and task execution to preserve the trace hierarchy.

  <Steps>
    <Step title="Create the Braintrust instrumentation module">
      Create a source-root module that initializes Braintrust and instruments Flue:

      ```ts title="src/braintrust.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      import { instrument } from "@flue/runtime";
      import { braintrustFlueInstrumentation, initLogger } from "braintrust";

      initLogger({
        projectName: process.env.BRAINTRUST_PROJECT_NAME ?? "my-flue-app",
        apiKey: process.env.BRAINTRUST_API_KEY,
      });

      instrument(braintrustFlueInstrumentation());
      ```
    </Step>

    <Step title="Load the instrumentation">
      For a deployed app, import the module once at the top of `src/app.ts`, before the application handles agent activity:

      ```ts title="src/app.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      import "./braintrust.ts";

      // Your existing Flue application routes follow.
      ```

      The `flue run` command loads the selected agent module without loading `src/app.ts`. To trace these runs, import the same module from the agent file:

      ```ts title="src/agents/support.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      "use agent";

      import "../braintrust.ts";

      // Your existing agent definition follows.
      ```
    </Step>

    <Step title="Run your app">
      Run your Flue app normally. Agent activity appears in the Braintrust project configured by `BRAINTRUST_PROJECT_NAME`.
    </Step>
  </Steps>

  <h2 id="what-traced-typescript">
    What Braintrust traces
  </h2>

  Braintrust captures:

  * Operation spans (`flue.prompt`, `flue.skill`, and `flue.compact`) with the operation input and result.
  * LLM turn spans (`flue.turn`) with messages as input, the model and request parameters as metadata, and the response as output.
  * Tool call spans (`tool:<name>`), with the tool arguments as input and the tool result as output.
  * Delegated task spans (`task:<agent>`), with the task prompt as input and its result as output.
  * Context compaction spans (`compaction:<reason>`), with message counts before and after compaction.
  * Token metrics, including prompt, completion, total, cached, and cache-creation values, plus estimated cost when Flue provides it.
  * Flue correlation metadata, including agent, conversation, instance, operation, submission, task, tool call, and turn identifiers when available.
  * Errors captured on every span.

  <Warning>
    Flue traces can include model messages, system instructions, reasoning, tool definitions and values, task content, and errors. Review your data retention and access requirements before enabling tracing in production. To redact sensitive data before Braintrust logs it, configure [`setMaskingFunction()`](/docs/instrument/advanced-tracing#mask-sensitive-data) before `initLogger()`.
  </Warning>

  <h2 id="resources-typescript">
    Resources
  </h2>

  * [Flue's Braintrust integration guide](https://flueframework.com/docs/ecosystem/tooling/braintrust/).
  * [Flue's observability guide](https://flueframework.com/docs/guide/observability/).
  * [@flue/runtime on npm](https://www.npmjs.com/package/@flue/runtime).
</View>