Workflow Runtime and Steps

Workflow is the public orchestration facade for typed step execution. WorkflowRuntime remains the internal engine that powers Workflow and prebuilt pattern implementations.

design_research_agents.workflow is the public module for constructing new workflow implementations. Prebuilt implementations live in design_research_agents.patterns.

Workflow-module step exports

All workflow step primitives are available from the workflow module:

from design_research_agents.workflow import (
    DelegateStep,
    DelegateBatchStep,
    LogicStep,
    LoopStep,
    MemoryReadStep,
    MemoryWriteStep,
    ModelStep,
    ToolStep,
    Workflow,
)

Step types

  • LogicStep: deterministic local handlers. Key fields: step_id, handler, dependencies, route_map. Use it for pure orchestration logic, branching, and deterministic transforms.

  • ToolStep: tool runtime invocations. Key fields: step_id, tool_name, input_builder, dependencies. Use it for explicit tool boundary calls through Toolbox.

  • DelegateStep: delegated agent/workflow execution. Key fields: step_id, delegate, prompt_builder, dependencies. Use it when nested agents/patterns should own their own prompting or tool usage.

  • LoopStep: iterative nested workflow body with loop state callbacks. Key fields: step_id, steps, max_iterations, initial_state, continue_predicate, state_reducer, execution_mode, failure_policy. Use it when iterative orchestration is first-class and state must evolve per iteration.

  • MemoryReadStep: retrieval step against a configured memory store. Key fields: step_id, query_builder, namespace, top_k, min_score. Use it to inject retrieved context into downstream agent/tool steps.

  • MemoryWriteStep: persistence step for normalized memory records. Key fields: step_id, records_builder, namespace. Use it to store intermediate/final artifacts for later retrieval.

Loop primitive

  • LoopStep executes a fixed nested step sequence for up to max_iterations.

  • continue_predicate can stop early based on iteration index and loop state.

  • state_reducer updates loop state from each iteration ExecutionResult.

  • Loop step outputs include explicit termination reason and serialized per-iteration results.

Execution semantics

  • execution_mode=\"sequential\" for strict order

  • execution_mode=\"dag\" for dependency-aware scheduling

  • Supports dependency injection through dependency_results

  • Supports route-based branch skipping via LogicStep.route_map

  • Supports configurable failure policies

Reusable facade

Workflow is the high-level constructor-first facade for user-defined graphs:

  • Workflow(input_schema=None) (default) for string prompt input.

  • Workflow(input_schema={...}) for mapping input with schema validation.

  • Workflow(output_schema={...}) to validate canonical output.final_output.

  • DelegateStep delegates are provided directly on each step object.

Input mode contracts

  • input_schema=None accepts non-empty string input only. It rejects non-string values and blank/whitespace-only prompts. Prompt input is provided to step context under prompt.

  • input_schema={...} accepts mapping input only. It validates payloads against input_schema. Schema input is provided to step context under inputs.

  • output_schema={...} validates output.final_output when workflow execution succeeds. Use scalar(...), typed_dict(...), and list_of(...) from design_research_agents.workflow for concise schema composition.

  • Both modes support constructor-level run defaults and per-run overrides. They return ExecutionResult with consistent workflow metadata.

  • Prebuilt implementations in design_research_agents.patterns are authored with these same primitives.

Examples

  • examples/workflow/workflow_runtime.py

  • examples/workflow/workflow_runtime_loop_step.py

  • examples/workflow/workflow_schema_mode.py

  • examples/workflow/workflow_prompt_mode.py