withWorkflow() | Respan Docs

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

stringRequired

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()