Workflow Builder Modules

This page documents the stable public workflow-building facades.

Stable public exports for building and running workflows.

class design_research_agents.workflow.CompiledExecution(*, workflow, input, request_id, dependencies, delegate_name, finalize=<function _identity_result>, execution_mode='sequential', failure_policy='skip_dependents', tracer=None, trace_input=<factory>, workflow_request_id=None)[source]

Bound compiled delegate execution that can be run repeatedly.

delegate_name: Delegate name used for top-level trace metadata.

dependencies: Bound dependency payload mapping.

execution_mode: Workflow execution mode used by run().

failure_policy: Workflow failure policy used by run().

finalize: Finalizer that maps the raw workflow result into the delegate result.

input: Bound workflow input payload.

request_id: Top-level request identifier for delegate tracing.

run()[source]: Execute the compiled workflow and finalize the result.

trace_input: Input payload attached to the top-level trace scope.

tracer: Optional tracer used for top-level compile-run traces.

workflow: Workflow graph compiled for this execution.

workflow_request_id: Optional nested workflow request id override.

class design_research_agents.workflow.DelegateBatchCall(*, call_id, delegate, prompt, execution_mode='sequential', failure_policy='skip_dependents')[source]

One delegate call specification executed by DelegateBatchStep.

call_id: Unique call identifier within the batch.

delegate: Delegate object invoked for this call.

execution_mode: Execution mode propagated when the delegate is workflow-like.

failure_policy: Failure policy propagated when the delegate is workflow-like.

prompt: Prompt passed to the delegate for this call.

class design_research_agents.workflow.DelegateBatchStep(*, step_id, calls_builder, dependencies=(), fail_fast=True, artifacts_builder=None)[source]

Workflow step that executes multiple delegate invocations in sequence.

artifacts_builder: Optional callback that extracts user-facing artifact manifests from step context.

calls_builder: Callback that builds batch delegate call specs from runtime context.

dependencies: Step ids that must complete before this step can run.

fail_fast: Whether to stop executing additional calls after first failure.

step_id: Unique step identifier used for dependency wiring and result lookup.

class design_research_agents.workflow.DelegateStep(*, step_id, delegate, dependencies=(), prompt=None, prompt_builder=None, artifacts_builder=None)[source]

Workflow step that invokes one direct delegate.

artifacts_builder: Optional callback that extracts user-facing artifact manifests from step context.

delegate: Direct delegate object (agent, pattern, or workflow-like runner).

dependencies: Step ids that must complete before this step can run.

prompt: Static prompt passed to the delegate when prompt_builder is absent.

prompt_builder: Optional callback that derives a prompt string from runtime step context.

step_id: Unique step identifier used for dependency wiring and result lookup.

class design_research_agents.workflow.ExecutionResult(*, success, output=<factory>, tool_results=<factory>, model_response=None, step_results=<factory>, execution_order=<factory>, metadata=<factory>)[source]

Structured output produced by one execution entrypoint.

This shape intentionally covers both agent-like executions and workflow-like executions so callers can consume one result contract everywhere.

property error

Return terminal error payload when present.

Returns:: Error payload from output mapping, or None.

execution_order: Step ids in the order they were executed for workflow-style runs.

property final_output

Return workflow/agent final_output payload when present.

Returns:: Final output value from output payload, or None.

metadata: Additional diagnostics, runtime counters, and trace metadata.

model_response: Final model response associated with the run, when available.

output: Primary payload produced by the entrypoint.

output_dict(key)[source]

Return one output value normalized to a dictionary.

Parameters:: key – Output key to read.
Returns:: Dictionary value when the output value is mapping-like, else {}.

output_list(key)[source]

Return one output value normalized to a list.

Parameters:: key – Output key to read.
Returns:: List value when the output value is a list/tuple, else [].

output_value(key, default=None)[source]

Return one output value by key with optional default.

Parameters:

key – Output key to read.
default – Value returned when key is absent.

Returns:

Output value for key when present, else default.

step_results: Per-step results keyed by step id for workflow-style runs.

success: True when the overall run completed without terminal failure.

summary()[source]

Return one compact summary payload for user-facing output.

Returns:: Compact summary payload with canonical execution fields.

property terminated_reason

Return normalized termination reason when present.

Returns:: Termination reason string, or None.

to_dict()[source]

Return a JSON-serializable dictionary representation of the result.

Returns:: Dictionary representation of the result payload.

to_json(*, ensure_ascii=True, indent=2, sort_keys=True)[source]

Return JSON string for deterministic pretty-printing.

Parameters:

ensure_ascii – Forwarded to json.dumps.
indent – Forwarded to json.dumps.
sort_keys – Forwarded to json.dumps.

Returns:

JSON representation of this result.

tool_results: Tool invocation results captured during execution, in call order.

class design_research_agents.workflow.LogicStep(*, step_id, handler, dependencies=(), route_map=None, artifacts_builder=None)[source]

Workflow step that executes deterministic local logic.

artifacts_builder: Optional callback that extracts user-facing artifact manifests from step context.

dependencies: Step ids that must complete before this step can run.

handler: Deterministic local function that computes this step output.

route_map: Optional route key to downstream-target mapping for conditional activation.

step_id: Unique step identifier used for dependency wiring and result lookup.

class design_research_agents.workflow.LoopStep(*, step_id, steps, dependencies=(), max_iterations=1, initial_state=None, continue_predicate=None, state_reducer=None, execution_mode='sequential', failure_policy='skip_dependents', artifacts_builder=None)[source]

Workflow step that executes an iterative nested workflow body.

artifacts_builder: Optional callback that extracts user-facing artifact manifests from step context.

continue_predicate: Predicate deciding whether to execute the next iteration.

dependencies: Step ids that must complete before loop iteration begins.

execution_mode: Execution mode used for nested loop-body workflow runs.

failure_policy: Failure handling policy applied within each loop iteration run.

initial_state: Initial loop state mapping provided to iteration context.

max_iterations: Hard cap on the number of loop iterations.

state_reducer: Reducer that computes next loop state from prior state and iteration result.

step_id: Unique step identifier used for dependency wiring and result lookup.

steps: Static loop body steps executed for each iteration.

class design_research_agents.workflow.MemoryReadStep(*, step_id, query_builder, dependencies=(), namespace='default', top_k=5, min_score=None, artifacts_builder=None)[source]

Workflow step that reads relevant records from the memory store.

artifacts_builder: Optional callback that extracts user-facing artifact manifests from step context.

dependencies: Step ids that must complete before this step can run.

min_score: Optional minimum score threshold for returned records.

namespace: Namespace partition to read from.

query_builder: Callback that builds query text or query payload from step context.

step_id: Unique step identifier used for dependency wiring and result lookup.

top_k: Maximum number of records to return.

class design_research_agents.workflow.MemoryWriteStep(*, step_id, records_builder, dependencies=(), namespace='default', artifacts_builder=None)[source]

Workflow step that writes records into the memory store.

artifacts_builder: Optional callback that extracts user-facing artifact manifests from step context.

dependencies: Step ids that must complete before this step can run.

namespace: Namespace partition to write into.

records_builder: Callback that builds record payloads from step context.

step_id: Unique step identifier used for dependency wiring and result lookup.

class design_research_agents.workflow.ModelStep(*, step_id, llm_client, request_builder, dependencies=(), response_parser=None, artifacts_builder=None)[source]

Workflow step that executes one model request through an LLM client.

artifacts_builder: Optional callback that extracts user-facing artifact manifests from step context.

dependencies: Step ids that must complete before this step can run.

llm_client: LLM client used to execute the request built for this step.

request_builder: Callback that builds the LLMRequest payload from runtime context.

response_parser: Optional callback that parses model response into structured output.

step_id: Unique step identifier used for dependency wiring and result lookup.

class design_research_agents.workflow.ToolStep(*, step_id, tool_name, dependencies=(), input_data=None, input_builder=None, artifacts_builder=None)[source]

Workflow step that invokes one runtime tool.

artifacts_builder: Optional callback that extracts user-facing artifact manifests from step context.

dependencies: Step ids that must complete before this step can run.

input_builder: Optional callback that derives input payload from runtime step context.

input_data: Static input payload used when input_builder is not provided.

step_id: Unique step identifier used for dependency wiring and result lookup.

tool_name: Registered tool name to invoke through the tool runtime.

class design_research_agents.workflow.Workflow(*, tool_runtime=None, memory_store=None, steps, input_schema=None, output_schema=None, prompt_context_key='prompt', base_context=None, default_execution_mode='sequential', default_failure_policy='skip_dependents', default_request_id_prefix=None, default_dependencies=None, tracer=None)[source]

Configured workflow for user-defined step graphs and run defaults.

Store runtime dependencies, step graph, and input handling mode.

Parameters:

tool_runtime – Tool runtime used by ToolStep executions.
memory_store – Optional memory store used by memory step executions.
steps – Static workflow step graph to execute for each run.
input_schema – Optional schema used to infer input mode and validate mapped input. When omitted, workflow expects prompt-string input.
output_schema – Optional schema enforced against output.final_output when the run succeeds.
prompt_context_key – Context key used to store normalized prompt input.
base_context – Base context merged into every run context.
default_execution_mode – Default runtime step scheduling mode.
default_failure_policy – Default dependency failure handling policy.
default_request_id_prefix – Optional prefix used to derive request ids.
default_dependencies – Default dependency objects injected into each run.
tracer – Optional tracer used for workflow runtime events.

Raises:

ValueError – If constructor inputs are inconsistent.

run(input=None, *, execution_mode=None, failure_policy=None, request_id=None, dependencies=None)[source]

Execute one workflow run with input mode inferred from input_schema.

Parameters:

input – Prompt string when input_schema is omitted; otherwise schema mapping.
execution_mode – Optional per-run execution mode override.
failure_policy – Optional per-run failure policy override.
request_id – Optional explicit request id for tracing/correlation.
dependencies – Optional per-run dependency overrides.

Returns:

Aggregated workflow execution result.

class design_research_agents.workflow.WorkflowArtifact(*, path, mime, title=None, summary=None, audience=None, producer_step_id=None, sources=(), metadata=<factory>)[source]

User-facing workflow artifact manifest entry.

audience: Optional target audience label (for example user).

metadata: Supplemental artifact metadata.

mime: MIME type for artifact consumers.

path: Filesystem path to the artifact.

producer_step_id: Step id that produced the artifact when known.

sources: Provenance entries describing source steps/fields.

summary: Optional artifact summary for user-facing rendering.

title: Optional short artifact title for UIs.

to_dict()[source]

Return a JSON-serializable dictionary representation.

Returns:: Dictionary representation of this artifact entry.

class design_research_agents.workflow.WorkflowArtifactSource(*, step_id, field=None, note=None)[source]

Provenance entry describing one artifact source edge.

field: Optional output field or source label within the step payload.

note: Optional human-readable provenance note.

step_id: Step id that contributed to this artifact.

design_research_agents.workflow.list_of(item_schema)[source]: Return an array schema whose items are constrained by item_schema.

design_research_agents.workflow.scalar(type_name)[source]: Return a scalar-schema mapping for one JSON-schema-like type name.

design_research_agents.workflow.typed_dict(*, required=None, optional=None, additional_properties=False)[source]: Return an object schema from required/optional field schema mappings.

Reusable configurable workflow facade for user-supplied step graphs.

class design_research_agents.workflow.workflow.Workflow(*, tool_runtime=None, memory_store=None, steps, input_schema=None, output_schema=None, prompt_context_key='prompt', base_context=None, default_execution_mode='sequential', default_failure_policy='skip_dependents', default_request_id_prefix=None, default_dependencies=None, tracer=None)[source]

Configured workflow for user-defined step graphs and run defaults.

Store runtime dependencies, step graph, and input handling mode.

Parameters:

tool_runtime – Tool runtime used by ToolStep executions.
memory_store – Optional memory store used by memory step executions.
steps – Static workflow step graph to execute for each run.
input_schema – Optional schema used to infer input mode and validate mapped input. When omitted, workflow expects prompt-string input.
output_schema – Optional schema enforced against output.final_output when the run succeeds.
prompt_context_key – Context key used to store normalized prompt input.
base_context – Base context merged into every run context.
default_execution_mode – Default runtime step scheduling mode.
default_failure_policy – Default dependency failure handling policy.
default_request_id_prefix – Optional prefix used to derive request ids.
default_dependencies – Default dependency objects injected into each run.
tracer – Optional tracer used for workflow runtime events.

Raises:

ValueError – If constructor inputs are inconsistent.

run(input=None, *, execution_mode=None, failure_policy=None, request_id=None, dependencies=None)[source]

Execute one workflow run with input mode inferred from input_schema.

Parameters:

input – Prompt string when input_schema is omitted; otherwise schema mapping.
execution_mode – Optional per-run execution mode override.
failure_policy – Optional per-run failure policy override.
request_id – Optional explicit request id for tracing/correlation.
dependencies – Optional per-run dependency overrides.

Returns:

Aggregated workflow execution result.