Module agentforge4j.runtime
Package com.agentforge4j.runtime

Class WorkflowRuntimeBuilder

java.lang.Object
com.agentforge4j.runtime.WorkflowRuntimeBuilder
public final class WorkflowRuntimeBuilder extends Object
Fluent builder that wires a DefaultWorkflowRuntime with the canonical executor graph, behaviour handlers, loop strategies, and command handlers.

Required collaborators are the WorkflowRepository, WorkflowStateRepository, WorkflowEventLog, and a pre-built AgentInvoker. FileSink, ShellCommandRunner, Clock, LoopEvaluator, and RunContextManager default when omitted.

Public construction path for WorkflowRuntime; DefaultWorkflowRuntime constructors stay package-private because they accept non-exported execution types.

  • Constructor Details

    • WorkflowRuntimeBuilder

      public WorkflowRuntimeBuilder()

  • Method Details

    • workflowRepository

      public WorkflowRuntimeBuilder workflowRepository(WorkflowRepository value)
      Configures the workflow definition source.
      Parameters:
      value - repository instance
      Returns:
      this builder

    • workflowStateRepository

      public WorkflowRuntimeBuilder workflowStateRepository(WorkflowStateRepository value)
      Configures persistence for WorkflowState between drives.
      Parameters:
      value - repository instance
      Returns:
      this builder

    • workflowEventLog

      public WorkflowRuntimeBuilder workflowEventLog(WorkflowEventLog value)
      Configures the append-only event log receiving WorkflowEvent instances.
      Parameters:
      value - event log instance
      Returns:
      this builder

    • clock

      public WorkflowRuntimeBuilder clock(Clock value)
      Configures the clock used for timestamps on state updates and events. Defaults to Clock.systemUTC() when omitted.
      Parameters:
      value - clock instance
      Returns:
      this builder

    • fileSink

      public WorkflowRuntimeBuilder fileSink(FileSink value)
      Configures where CreateFileCommand content is written.
      Parameters:
      value - file sink instance
      Returns:
      this builder

    • shellCommandRunner

      public WorkflowRuntimeBuilder shellCommandRunner(ShellCommandRunner value)
      Configures execution of RunCommandCommand shell strings.
      Parameters:
      value - shell runner instance
      Returns:
      this builder

    • loopEvaluator

      public WorkflowRuntimeBuilder loopEvaluator(LoopEvaluator value)
      Configures the evaluator loop strategy dependency. Defaults to DefaultLoopEvaluator when omitted.
      Parameters:
      value - loop evaluator instance
      Returns:
      this builder

    • maxNestingDepth

      public WorkflowRuntimeBuilder maxNestingDepth(int value)
      Configures the maximum nested workflow depth passed to ExecutionContext.
      Parameters:
      value - maximum nesting depth (at least 1)
      Returns:
      this builder

    • runContextManager

      public WorkflowRuntimeBuilder runContextManager(RunContextManager value)
      Configures correlation scope hooks for each drive. Defaults to RunContextManager.NO_OP when omitted.
      Parameters:
      value - run context manager instance
      Returns:
      this builder

    • agentInvoker

      public WorkflowRuntimeBuilder agentInvoker(AgentInvoker value)
      Configures the AgentInvoker used for agent and SPAR steps (for example from framework integration or constructed explicitly by the embedding application).
      Parameters:
      value - invoker instance
      Returns:
      this builder

    • eventRecorder

      public WorkflowRuntimeBuilder eventRecorder(EventRecorder value)
      Configures the shared EventRecorder used by command handlers, loop strategies, and step executors. When omitted, build() constructs one from workflowEventLog(WorkflowEventLog) and clock(Clock).
      Parameters:
      value - event recorder instance
      Returns:
      this builder

    • toolExecutionService

      public WorkflowRuntimeBuilder toolExecutionService(ToolExecutionService value)
      Configures the optional tool-execution chokepoint. When set, a ToolInvocationCommandHandler is registered so TOOL_INVOCATION commands are dispatched, and tool-approval resume becomes available; when omitted, tool invocation is unavailable and behaviour is unchanged.
      Parameters:
      value - tool execution service instance
      Returns:
      this builder

    • pendingToolInvocationStore

      public WorkflowRuntimeBuilder pendingToolInvocationStore(PendingToolInvocationStore value)
      Configures the store used to resume approval-pending tool invocations. Required alongside toolExecutionService(ToolExecutionService) for continueAfterToolApproval to function.
      Parameters:
      value - pending tool invocation store instance
      Returns:
      this builder

    • requirementResolver

      public WorkflowRuntimeBuilder requirementResolver(RequirementResolver value)
      Configures the resolver used to satisfy declared requirements at the run-start checkpoint and at deferred first use. Defaults to DefaultRequirementResolver (default- or-empty) when omitted, so a pure-core runtime still enforces the fail-fast guarantee.
      Parameters:
      value - requirement resolver instance
      Returns:
      this builder

    • runExecutionInterceptor

      public WorkflowRuntimeBuilder runExecutionInterceptor(RunExecutionInterceptor value)
      Configures the control interceptor fired before main execution and before each LLM call. Defaults to RunExecutionInterceptor.NO_OP.
      Parameters:
      value - run-execution interceptor instance
      Returns:
      this builder

    • generatedArtifactStore

      public WorkflowRuntimeBuilder generatedArtifactStore(GeneratedArtifactStore value)
      Configures the run-scoped store that captures emitted CREATE_FILE bytes for in-process artifact validation. Defaults to a retaining InMemoryGeneratedArtifactStore when omitted.
      Parameters:
      value - generated-artifact store instance
      Returns:
      this builder

    • artifactValidators

      public WorkflowRuntimeBuilder artifactValidators(List<ArtifactValidator> value)
      Configures the ArtifactValidators a VALIDATE step may select by validatorId. Defaults to none; an embedding assembly (for example bootstrap) supplies the defaults.
      Parameters:
      value - validators registered by id (no duplicate ids)
      Returns:
      this builder

    • contextAggregators

      public WorkflowRuntimeBuilder contextAggregators(List<ContextAggregator> value)
      Configures the ContextAggregators an AGGREGATE step may select by aggregatorId. Defaults to none; an embedding assembly (for example bootstrap) supplies the defaults.
      Parameters:
      value - aggregators registered by id (no duplicate ids)
      Returns:
      this builder

    • build

      public WorkflowRuntime build()
      Validates required dependencies, wires executors and handlers, and returns a runnable WorkflowRuntime.

      Also rejects, before returning, every registered WorkflowDefinition in workflowRepository's current snapshot that contains a COLLECTION step: that step type has no registered BehaviourHandler in this release (see WorkflowValidator.validateNoCollectionSteps(java.util.Map<java.lang.String, com.agentforge4j.core.workflow.WorkflowDefinition>)), so a run that reached one would otherwise fail deep inside execution instead of at build time. The JSON-loader path also runs this same check (defense-in-depth); this call covers definitions assembled programmatically, which never pass through the loader's validation suite.

      Returns:
      configured runtime instance
      Throws:
      IllegalArgumentException - if a required dependency is missing or invalid, or if a registered workflow contains a COLLECTION step