Flue (tracing) | Respan Docs

Flue is a TypeScript agent harness framework for autonomous agents and AI workflows. Use @respan/instrumentation-flue to subscribe to Flue runtime events and emit canonical Respan spans.

Set up Respan

Create an account at platform.respan.ai and grab an API key.

Run npx @respan/cli setup to set up with your coding agent.

Example projects

TypeScript examples

Setup

Install packages

$ npm install @flue/runtime @respan/respan @respan/tracing @respan/instrumentation-flue

Set environment variables

$ export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

Initialize Respan before Flue handles activity

1 import * as FlueRuntime from "@flue/runtime";
2 import { Respan } from "@respan/respan";
3 import { FlueInstrumentor } from "@respan/instrumentation-flue";
4 
5 const respan = new Respan({
6   apiKey: process.env.RESPAN_API_KEY,
7   baseURL: process.env.RESPAN_BASE_URL,
8   appName: "flue-tracing",
9   instrumentations: [
10     new FlueInstrumentor({
11       runtimeModule: FlueRuntime,
12       workflowName: "Flue App.workflow",
13     }),
14   ],
15 });
16 
17 await respan.initialize();

Run Flue activity inside a Respan workflow

1 await respan.propagateAttributes(
2   {
3     trace_group_identifier: "Flue App.workflow",
4     metadata: {
5       service: "agent-runtime",
6       framework: "flue",
7     },
8   },
9   async () => {
10     await respan.withWorkflow({ name: "Flue App" }, async () => {
11       // Run your Flue agent, workflow, or runtime activity here.
12     });
13   }
14 );
15 
16 await respan.flush();

View your trace

Open the Traces page to see Flue workflow runs, agent sessions, model turns, tool executions, tasks, shell operations, compaction events, and structured logs.

Captured data

Data	Description
Workflow runs	Flue run lifecycle events, inputs, outputs, duration, and errors.
Direct agents	Agent lifecycle events for direct Flue agent sessions.
Model turns	Model request, response, usage, provider, API type, and reasoning metadata.
Tools	Tool names, arguments, outputs, durations, and errors.
Tasks	Delegated task prompts, agents, results, durations, and failures.
Shell operations	Shell command operations and command failure details.
Compaction	Context compaction metadata including before/after message counts.
Structured logs	Flue application logs emitted through the runtime context.

Attributes

Use Respan attributes to group Flue runs by user, trace group, or deployment.

1 await respan.propagateAttributes(
2   {
3     customer_identifier: "user_123",
4     thread_identifier: "flue-session-abc",
5     trace_group_identifier: "Support Agent.workflow",
6     metadata: {
7       environment: "production",
8       channel: "support",
9     },
10   },
11   async () => {
12     await respan.withWorkflow({ name: "Support Agent" }, runFlueAgent);
13   }
14 );

Attribute	Type	Description
`customer_identifier`	`string`	Identifies the end user in Respan analytics.
`thread_identifier`	`string`	Groups related Flue activity into a session.
`trace_group_identifier`	`string`	Groups related spans into a named trace group.
`metadata`	`object`	Custom key-value pairs attached to spans.

Notes

@respan/instrumentation-flue listens to Flue’s runtime observe() event stream.
Pass runtimeModule when your app imports @flue/runtime directly. This ensures the instrumentor observes the same runtime module instance your application uses.
The TypeScript examples are deterministic and emit representative Flue workflow, agent, model-turn, tool, task, compaction, log, and recovery events without calling an external LLM provider.