Skip to main content

​
Overview

Use withWorkflow(options, fn) to mark an end-to-end run. All nested tasks, agents, and tools are captured under this workflow.

​
Signature

withWorkflow<T>(
  options: {
    name: string;
    version?: number;
    associationProperties?: Record<string, any>;
  },
  fn: () => Promise<T>
): Promise<T>

​
Basic Usage

import { RespanTelemetry } from '@respan/tracing';

const respanAi = new RespanTelemetry({
    apiKey: process.env.RESPAN_API_KEY,
    appName: 'my-app'
});

await respanAi.initialize();

const result = await respanAi.withWorkflow(
    { 
        name: 'data_pipeline',
        version: 1
    },
    async () => {
        // Your workflow logic here
        const data = await fetchData();
        const processed = await processData(data);
        return processed;
    }
);

​
With Association Properties

await respanAi.withWorkflow(
    { 
        name: 'user_request',
        version: 1,
        associationProperties: {
            'user_id': 'user-123',
            'session_id': 'session-abc',
            'environment': 'production'
        }
    },
    async () => {
        // Your workflow logic
        return await handleUserRequest();
    }
);

​
Nested Tasks

await respanAi.withWorkflow(
    { name: 'complete_pipeline' },
    async () => {
        const extracted = await respanAi.withTask(
            { name: 'extract' },
            async () => {
                return { records: [1, 2, 3] };
            }
        );
        
        const transformed = await respanAi.withTask(
            { name: 'transform' },
            async () => {
                return extracted.records.map(x => x * 2);
            }
        );
        
        return transformed;
    }
);

​
Parameters

​
name
string
required
Workflow display name for identification in the Respan dashboard
​
version
number
Version number for tracking workflow iterations
​
associationProperties
Record<string, any>
Custom metadata to associate with the workflow (user ID, session ID, etc.)

​
Return Value

Returns a Promise that resolves to the return value of the provided function.

​
Best Practices

  • Use descriptive workflow names for easy navigation in the dashboard
  • Keep workflows coarse-grained; use tasks for internal steps
  • Add association properties for filtering and grouping in analytics
  • Always call initialize() before using withWorkflow()