​
Overview

The updateStep function updates properties of a specific step by its ID. This is typically used to mark steps as finished or update their evaluation scores.

​
Syntax

await lai.updateStep({
  stepId: string;
  state?: string;
  action?: string;
  goal?: string;
  evalScore?: number;
  evalDescription?: string;
}): Promise<void>

​
Parameters

​
stepId
string
required
ID of the step to update.
​
evalScore
number
Evaluation score (0-100).
​
evalDescription
string
Description of the evaluation.

​
Returns

Returns a Promise that resolves to void.

​
Examples

​
Basic Update

// Keep reference to step
const step = await lai.createStep({
  state: "Processing",
  action: "Analyze data"
});

// Update later
await lai.updateStep({
  stepId: step.stepId,
  evalScore: 75,
  evalDescription: "Partially complete"
});

// Finish the step (use endStep)
await lai.endStep({
  stepId: step.stepId,
  evalScore: 100,
  evalDescription: "Analysis completed successfully"
});

​
Progress Tracking

const step = await lai.createStep();

const totalChunks = 100;

for (let i = 0; i < totalChunks; i++) {
  await processChunk(i);
  
  // Update progress
  const progress = Math.round(((i + 1) / totalChunks) * 100);
  await lai.updateStep({
    stepId: step.stepId,
    evalScore: progress,
    evalDescription: `Processed ${i + 1}/${totalChunks} chunks`
  });
}

// Mark as complete
await lai.endStep({
  stepId: step.stepId,
  evalScore: 100,
  evalDescription: "All chunks processed"
});

​
Multiple Steps Management

// Create multiple steps
const steps = await Promise.all([
  lai.createStep(),
  lai.createStep(),
  lai.createStep()
]);

// Process in parallel
await Promise.all(steps.map(async (step, index) => {
  try {
    await processStepTask(index);
    
    // Update on success
    await lai.endStep({
      stepId: step.stepId,
      evalScore: 100,
      evalDescription: `Step ${index + 1} completed`
    });
  } catch (error) {
    // Update on failure
    await lai.endStep({
      stepId: step.stepId,
      evalScore: 0,
      evalDescription: `Step ${index + 1} failed: ${error.message}`
    });
  }
}));

​
Difference from endStep

FeatureupdateStependStep
Requires step ID✅ Yes❌ Optional
Can update non-active steps✅ Yes❌ No
Can update finished steps❌ No✅ No
Updates current active step reference❌ No✅ Yes
Can update state/action/goal❌ No✅ Yes

​
When to Use Each

Use updateStep when:
  • You need to update a specific step by ID
  • Managing multiple steps simultaneously
  • Updating progress incrementally
  • Working with non-active steps
Use endStep when:
  • Ending the current active step
  • Following sequential step flow
  • Need to update state/action/goal

​
Common Patterns

​
1. Retry with Score Tracking

async function retryableOperation() {
  const step = await lai.createStep({
    state: "Retryable operation",
    action: "Process with retries"
  });
  
  for (let attempt = 1; attempt <= 3; attempt++) {
    try {
      await riskyOperation();
      
      await lai.endStep({
        stepId: step.stepId,
        evalScore: 100,
        evalDescription: `Succeeded on attempt ${attempt}`
      });
      return;
      
    } catch (error) {
      const score = Math.max(0, 100 - (attempt * 30));
      await lai.updateStep({
        stepId: step.stepId,
        evalScore: score,
        evalDescription: `Attempt ${attempt} failed: ${error.message}`
      });
      if (attempt === 3) {
        await lai.endStep({ stepId: step.stepId });
      }
      
      if (attempt < 3) await delay(1000 * attempt);
    }
  }
}

​
2. Background Processing

// Start long-running task
const step = await lai.createStep({
  state: "Background job",
  action: "Process async"
});

// Return step ID for status updates
const jobId = startBackgroundJob(async (progress) => {
  await lai.updateStep({
    stepId: step.stepId,
    evalScore: progress,
    evalDescription: `Processing: ${progress}% complete`
  });
});

// Later, mark as complete
await lai.endStep({
  stepId: step.stepId,
  evalScore: 100,
  evalDescription: "Background job finished"
});

​
Best Practices

​
1. Keep Step References

// Store step IDs for later updates
const stepMap = new Map();

stepMap.set('validation', await lai.createStep({ state: "Validating" }));
stepMap.set('processing', await lai.createStep({ state: "Processing" }));

// Update specific steps
await lai.updateStep(stepMap.get('validation').stepId, true, 100);

​
2. Consistent Scoring

// Define scoring criteria
const scoreStep = (success: boolean, warnings: number) => {
  if (!success) return 0;
  if (warnings === 0) return 100;
  if (warnings <= 2) return 90;
  if (warnings <= 5) return 75;
  return 50;
};

await lai.endStep({
  stepId,
  evalScore: scoreStep(result.success, result.warnings),
  evalDescription: `Completed with ${result.warnings} warnings`
});

​
Notes

  • Step must exist and belong to the active session
  • Can update finished steps (unlike endStep)
  • All parameters except stepId are optional
  • Updates don’t affect the active step pointer

​
See Also