​
Overview

The createStep function creates a new step within the active session. Steps represent logical units of work in your workflow.

​
Syntax

await lai.createStep(params?: {
  evalScore?: number;
  evalDescription?: string;
  screenshot?: string;      // base64 data URL
  screenshotPath?: string;  // path to image file
}): Promise<{ stepId: string } | undefined>

​
Parameters

​
params
CreateStepParams
Optional object with step configuration:

​
Returns

Returns a Promise that resolves to an object with:
  • stepId - Unique identifier for the step
If no session is active, returns undefined.

​
Examples

​
Basic Step Creation

// Create a step with no parameters
await lai.createStep();

// Or create with evaluation metadata
await lai.createStep({ evalScore: 100, evalDescription: "All checks passed" });

​
With Evaluation

await lai.createStep({
  evalScore: 100,
  evalDescription: "All validations passed"
});

​
Sequential Steps

// Step 1: Load data
await lai.createStep();

const userData = await loadUserData();

await lai.endStep({
  evalScore: 100,
  evalDescription: "Data loaded successfully"
});

// Step 2: Process data
await lai.createStep();

const processed = await processData(userData);

await lai.endStep({
  evalScore: 95,
  evalDescription: "Minor validation warnings"
});

// Step 3: Generate output
await lai.createStep();

​
Error Handling

try {
  await lai.createStep();

  // Risky operations
  await processExternalData();

  await lai.endStep({
    evalScore: 100,
    evalDescription: "Success"
  });

} catch (error) {
  // End step with failure
  await lai.endStep({
    evalScore: 0,
    evalDescription: `Failed: ${error.message}`
  });
  throw error;
}

​
With Provider Integration

await lai.createStep();

// LLM calls within the step are auto-tracked
const OpenAI = (await import('openai')).default;
const openai = new OpenAI();

const response = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [
    { role: "system", content: "You are a data analyst" },
    { role: "user", content: analyzeThis }
  ]
});

// Multiple LLM calls create multiple events within the step
const summary = await openai.chat.completions.create({
  model: "gpt-3.5-turbo",
  messages: [
    { role: "user", content: `Summarize: ${response.choices[0].message.content}` }
  ]
});

await lai.endStep({ evalScore: 100, evalDescription: "Analysis completed" });

​
Best Practices

​
1. Use Context Managers for Self-Contained Workflows

Prefer withLucidic for short, self-sufficient tasks that should end when work completes. See Session Context.

​
2. Always End Steps

// Use try-finally to ensure cleanup
try {
  await lai.createStep();
  await criticalOperation();
} finally {
  await lai.endStep();
}

​
3. One Active Step

Only one step can be active at a time: 
// Wrong - previous step not ended
await lai.createStep();
await lai.createStep(); // Error!

// Correct
await lai.createStep();
await lai.endStep();
await lai.createStep();
await lai.endStep();

​
Notes

  • An active session is required before creating steps
  • Previous step must be ended before creating a new one
  • Steps are automatically ended when the session ends
  • All parameters are optional - you can create a step with no configuration

​
See Also