Skip to main content
Flue is an open-source TypeScript agent harness framework. Braintrust traces Flue agent operations, including LLM turns, tool calls, delegated tasks, and context compaction.

​
Setup

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.
1

Install packages

2

Set environment variables

.env

​
Instrument Flue

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.
1

Create the Braintrust instrumentation module

Create a source-root module that initializes Braintrust and instruments Flue:
src/braintrust.ts
2

Load the instrumentation

For a deployed app, import the module once at the top of src/app.ts, before the application handles agent activity:
src/app.ts
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:
src/agents/support.ts
3

Run your app

Run your Flue app normally. Agent activity appears in the Braintrust project configured by BRAINTRUST_PROJECT_NAME.

​
What Braintrust traces

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.
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() before initLogger().

​
Resources