IterativeLoopStageExecutor

NexusLabs.Needlr.AgentFramework.Workflows ¶

NexusLabs.Needlr.AgentFramework.Workflows.Sequential ¶

IterativeLoopStageExecutor Class¶

Executes a pipeline stage by running an NexusLabs.Needlr.AgentFramework.Iterative.IIterativeAgentLoop with dynamically constructed options and context.

public sealed class IterativeLoopStageExecutor : NexusLabs.Needlr.AgentFramework.Workflows.Sequential.IStageExecutor

Inheritance System.Object 🡒 IterativeLoopStageExecutor

Implements IStageExecutor

Example¶

// Basic usage
var executor = new IterativeLoopStageExecutor(
    iterativeLoop,
    ctx => new IterativeLoopOptions
    {
        Instructions = "Write an article.",
        Tools = tools,
        PromptFactory = iterCtx => BuildPrompt(iterCtx.Workspace),
        MaxIterations = 15,
        LoopName = ctx.StageName,
    });

// With onLoopCompleted to capture termination metadata
var executor = new IterativeLoopStageExecutor(
    iterativeLoop,
    ctx => buildOptions(ctx),
    onLoopCompleted: (loopResult, ctx) =>
    {
        accessor.LastDiagnostics = loopResult.Diagnostics;
        accessor.LastTerminationReason = loopResult.Termination.ToString();
    });

// With shouldTreatAsSuccess for acceptable non-success terminations
var executor = new IterativeLoopStageExecutor(
    iterativeLoop,
    ctx => buildOptions(ctx),
    shouldTreatAsSuccess: r =>
        r.Termination is TerminationReason.MaxIterationsReached
                      or TerminationReason.MaxToolCallsReached);

// Composing with decorators
var timedExecutor = new TimeoutExecutor(
    new IterativeLoopStageExecutor(loop, optionsFactory),
    TimeSpan.FromMinutes(10));

Remarks¶

This executor bridges the workspace-driven iterative loop pattern into the IStageExecutor contract used by SequentialPipelineRunner. Unlike AgentStageExecutor (which wraps a single-pass AIAgent.RunAsync call), this executor runs a multi-iteration loop where each iteration builds a fresh prompt from workspace state, maintaining O(n) token cost.

All termination paths use result-based signaling — the executor never throws exceptions for loop-level failures. This means exception-driven decorators like ContinueOnFailureExecutor and FallbackExecutor do not intercept loop termination results. For advisory behavior, set failureDisposition to ContinueAdvisory. For timeout enforcement, TimeoutExecutor still works because the loop observes the linked System.Threading.CancellationToken and terminates cooperatively.

The onLoopCompleted callback fires immediately after the loop returns, before result mapping. Use it to capture loop-specific metadata (termination reason, per-iteration diagnostics, tool call counts) that is not surfaced on StageExecutionResult. This is the only point where the raw NexusLabs.Needlr.AgentFramework.Iterative.IterativeLoopResult is accessible.

Constructors¶

IterativeLoopStageExecutor(IIterativeAgentLoop, Func<StageExecutionContext,IterativeLoopOptions>, Func<StageExecutionContext,IterativeContext>, Action<IterativeLoopResult,StageExecutionContext>, Func<IterativeLoopResult,bool>, FailureDisposition) Constructor¶

Initializes a new IterativeLoopStageExecutor.

public IterativeLoopStageExecutor(NexusLabs.Needlr.AgentFramework.Iterative.IIterativeAgentLoop loop, System.Func<NexusLabs.Needlr.AgentFramework.Workflows.Sequential.StageExecutionContext,NexusLabs.Needlr.AgentFramework.Iterative.IterativeLoopOptions> optionsFactory, System.Func<NexusLabs.Needlr.AgentFramework.Workflows.Sequential.StageExecutionContext,NexusLabs.Needlr.AgentFramework.Iterative.IterativeContext>? contextFactory=null, System.Action<NexusLabs.Needlr.AgentFramework.Iterative.IterativeLoopResult,NexusLabs.Needlr.AgentFramework.Workflows.Sequential.StageExecutionContext>? onLoopCompleted=null, System.Func<NexusLabs.Needlr.AgentFramework.Iterative.IterativeLoopResult,bool>? shouldTreatAsSuccess=null, NexusLabs.Needlr.AgentFramework.Workflows.Sequential.FailureDisposition failureDisposition=NexusLabs.Needlr.AgentFramework.Workflows.Sequential.FailureDisposition.AbortPipeline);

Parameters¶

loop NexusLabs.Needlr.AgentFramework.Iterative.IIterativeAgentLoop

The iterative agent loop to execute.

optionsFactory System.Func<StageExecutionContext ,NexusLabs.Needlr.AgentFramework.Iterative.IterativeLoopOptions >

Factory that produces the NexusLabs.Needlr.AgentFramework.Iterative.IterativeLoopOptions from the current stage context. Called once per execution — callers configure instructions, tools, prompt factory, iteration limits, and all other loop settings here.

contextFactory System.Func<StageExecutionContext ,NexusLabs.Needlr.AgentFramework.Iterative.IterativeContext >

Optional factory that produces the NexusLabs.Needlr.AgentFramework.Iterative.IterativeContext from the current stage context. When null (the default), the executor creates an NexusLabs.Needlr.AgentFramework.Iterative.IterativeContext using Workspace. Provide a factory to pre-populate NexusLabs.Needlr.AgentFramework.Iterative.IterativeContext.State or use a different workspace.

onLoopCompleted System.Action<NexusLabs.Needlr.AgentFramework.Iterative.IterativeLoopResult ,StageExecutionContext >

Optional callback invoked immediately after the loop completes, before result mapping. Receives the raw NexusLabs.Needlr.AgentFramework.Iterative.IterativeLoopResult and the StageExecutionContext. Use this to capture loop-specific metadata (termination reason, per-iteration diagnostics) that is not surfaced on StageExecutionResult. Called on both success and failure paths. Not called if the loop throws an exception.

shouldTreatAsSuccess System.Func<NexusLabs.Needlr.AgentFramework.Iterative.IterativeLoopResult ,System.Boolean >

Optional predicate evaluated when the loop result has NexusLabs.Needlr.AgentFramework.Iterative.IterativeLoopResult.Succeeded = false. When the predicate returns true, the executor treats the result as a success. Use this for termination reasons like NexusLabs.Needlr.AgentFramework.Iterative.TerminationReason.MaxIterationsReached that are acceptable in the caller's domain. Not called when the loop already succeeded.

failureDisposition FailureDisposition

The FailureDisposition applied to failed results. Defaults to AbortPipeline. Set to ContinueAdvisory for stages whose failure should not halt the pipeline.

Methods¶

IterativeLoopStageExecutor.ExecuteAsync(StageExecutionContext, CancellationToken) Method¶

Executes the stage logic and returns a result indicating success or failure.

public System.Threading.Tasks.Task<NexusLabs.Needlr.AgentFramework.Workflows.Sequential.StageExecutionResult> ExecuteAsync(NexusLabs.Needlr.AgentFramework.Workflows.Sequential.StageExecutionContext context, System.Threading.CancellationToken cancellationToken);