feat(core): support multi-step doWhile/doUntil loops

[omeraplak]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://voltagent.dev/docs/community/contributing/#commit-convention

Bugs / Features

• Related issue(s) linked
• Tests for the changes have been added
• Docs have been added / updated
• Changesets have been added https://voltagent.dev/docs/community/contributing/#creating-a-changeset

What is the current behavior?

andDoWhile and andDoUntil only accept a single step. For multi-step loop bodies, users have to place all logic in one andThen(...).execute block.

What is the new behavior?

andDoWhile and andDoUntil now accept either:

• step (existing behavior, backward compatible)
• steps (new) for sequential multi-step loop bodies

Each iteration runs the configured steps in order and pipes each output into the next step.

Also updated loop step serialization to include subSteps when a loop has multiple steps.

fixes (issue)

N/A

Notes for reviewers

• No breaking runtime API change for existing step usage.
• Added runtime tests in and-loop.spec.ts and type tests in core.spec-d.ts.
• Docs updated at website/docs/workflows/steps/and-loop.md.
• Changeset included at .changeset/giant-coins-twirl.md.

Validation run:

• pnpm --filter @voltagent/core exec vitest run src/workflow/steps/and-loop.spec.ts src/workflow/core.spec-d.ts --typecheck

---

Summary by cubic

Enable multi-step loop bodies for andDoWhile/andDoUntil. Each iteration can run multiple steps in order and pass outputs between them; single-step usage stays the same.

• New Features
  • Accepts steps array in addition to step (backward compatible); condition uses the last step’s output; throws if steps is empty.
  • Executes steps sequentially per iteration, piping each step’s result into the next.
  • Adds subSteps to loop serialization and improves tracing for nested loop steps; docs and tests updated.

^{Written for commit b55cd0a. Summary will update on new commits.}

Summary by CodeRabbit

Release Notes

• New Features

  • andDoWhile and andDoUntil now support multiple steps per loop iteration. Provide either a single step or an array of steps; within each iteration, step outputs automatically chain into the next step.

• Documentation

  • Updated documentation for andDoWhile and andDoUntil with examples of multi-step loop configurations.

[changeset-bot]

🦋 Changeset detected

Latest commit: b55cd0a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@voltagent/core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

📝 Walkthrough

Walkthrough

The pull request adds multi-step loop support for andDoWhile and andDoUntil. Loop steps can now be either a single step or an array of steps that execute sequentially during each iteration, with outputs feeding into subsequent steps. Serialization, type checking, and loop execution logic have been updated accordingly.

Changes

Cohort / File(s)	Summary
Type Definitions packages/core/src/workflow/steps/types.ts, packages/core/src/workflow/steps/index.ts	Introduced discriminated union types (WorkflowStepLoopSingleStepConfig and WorkflowStepLoopMultiStepConfig) to support either single or multiple steps; added WorkflowStepLoopSteps public type and extended WorkflowStepLoop interface with optional steps array.
Core Serialization packages/core/src/workflow/core.ts	Updated loop step serialization to conditionally set nestedStep for single steps or subSteps/subStepsCount for multiple steps based on serializedSteps count.
Loop Implementation packages/core/src/workflow/steps/and-loop.ts	Refactored createLoopStep with helper utilities (splitLoopConfig, getLoopSteps); added validation for at least one step, per-step tracing with loop metadata (loop_iteration, loop_step_index), and inner loop to execute multiple steps sequentially per iteration.
Type Tests packages/core/src/workflow/core.spec-d.ts	Added test suite for andDoWhile in non-chaining API to verify condition data type inference and context typing consistency.
Runtime Tests packages/core/src/workflow/steps/and-loop.spec.ts	Added tests for chained multi-step loop iterations and empty steps array error handling.
Documentation & Changelog .changeset/giant-coins-twirl.md, website/docs/workflows/steps/and-loop.md	Updated documentation and changelog to document multi-step loop support with optional step/steps parameters.

Sequence Diagram

sequenceDiagram
    participant Executor as Loop Executor
    participant Condition as Condition Check
    participant Step1 as Step 1
    participant Step2 as Step N
    participant Tracing as Tracing/Metrics
    
    rect rgba(100, 150, 200, 0.5)
        Executor->>Condition: Evaluate condition with input
        Condition-->>Executor: Continue? (boolean)
    end
    
    rect rgba(100, 150, 200, 0.5)
        loop For each step in steps array
            Executor->>Tracing: Record step index & loop iteration
            Executor->>Step1: Execute with current data
            Step1-->>Step2: Output data
            Step2->>Step2: Transform data
            Step2-->>Executor: Return modified data
        end
    end
    
    rect rgba(100, 150, 200, 0.5)
        Executor->>Condition: Re-evaluate with new data
        Condition-->>Executor: Continue/Stop?
    end
    
    alt Condition met
        Executor->>Executor: Next iteration
    else Condition not met
        Executor->>Executor: Exit loop
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• feat: add workflow control steps (branch, foreach, loop, map, sleep) #929: Multi-step per-iteration support extends the loop step implementation introduced in this PR with new type discriminations, helper utilities, and multi-step execution logic.

Poem

🐰 Loops now dance with many feet,
Each step feeds the next with beat,
From single stride to chained ballet,
Data flows through every play,
Our loops grow wings—hooray, hooray! ✨

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(core): support multi-step doWhile/doUntil loops' clearly and concisely summarizes the main change: enabling multi-step loop support for doWhile/doUntil. It aligns with the primary objective of the PR and follows conventional commit format.
Description check	✅ Passed	The PR description comprehensively addresses all template sections: checklist items are marked, current/new behavior clearly explained, related files documented, and validation details provided. Minor note: no related issue linked, but this is acknowledged and marked as N/A.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/workflow-multi-step-loops

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

packages/core/src/workflow/steps/and-loop.ts (1)

59-63: Silent no-op on missing resolved step.

If resolvedSteps[stepIndex] is undefined, the function returns without updating currentData. Since the for loop at Line 121 is bounded by resolvedSteps.length, this branch is unreachable in practice. Consider throwing instead for defense-in-depth — a silent no-op here could mask bugs if future refactoring changes the loop bounds.

Suggested change

       const runResolvedStep = async (stepIndex: number) => {
         const resolvedStep = resolvedSteps[stepIndex];
         if (!resolvedStep) {
-          return;
+          throw new Error(`Loop step at index ${stepIndex} not found`);
         }

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cloudflare-workers-and-pages]

Deploying voltagent with    Cloudflare Pages

Latest commit:	b55cd0a
Status:	✅  Deploy successful!
Preview URL:	https://37be1d62.voltagent.pages.dev
Branch Preview URL:	https://feat-workflow-multi-step-loo.voltagent.pages.dev

View logs

[cubic-dev-ai]

No issues found across 8 files