Workflow Agent Node — Per-Output Retry Configuration#

Overview#

Workflow Agent Nodes (agent_v2) support per-output retry configuration: after the Agent backend returns a result, each declared output is individually type-checked, and any failures can trigger a full node re-run before the configured failure strategy fires. The maximum retry count per output is 10.

This is distinct from model-level rate-limit retries or workflow-level concurrency controls — it operates at the post-execution output-validation layer.

Configuration Model#

Each declared output (DeclaredOutputConfig) carries a failure_strategy containing a DeclaredOutputRetryConfig:

The le=10 upper bound is enforced by Pydantic at schema load time 1.

Each output also has an on_failure terminal strategy — applied after all retries are exhausted — with three options defined by OutputErrorStrategy:

• STOP → fail the node
• DEFAULT_VALUE → substitute a pre-configured default value
• FAIL_BRANCH → route through the node's fail branch outbound edge

OutputFailureOrchestrator#

OutputFailureOrchestrator is the stateless decision engine in api/core/workflow/nodes/agent_v2/output_failure_orchestrator.py. Its single decide() method receives:

• failures: a list of FailedOutput objects (each wrapping the declared config, failure kind, and reason)
• current_attempt: zero-indexed attempt number owned by the caller

It returns an OutputFailureOutcome with one of four decisions:

Retry budget logic: The effective budget is the maximum max_retries across all currently-failed outputs 2. If current_attempt < retry_budget, the orchestrator returns RETRY and increments next_attempt. This means retry continues until every failed output's budget is spent 3.

Multi-output precedence: When multiple outputs fail with different terminal strategies, the highest-precedence strategy wins: FAIL_BRANCH > STOP > DEFAULT_VALUE 4.

Retry Loop in the Node Runner#

The caller — agent_node._run — owns the attempt counter and the retry loop:

1. Run the Agent backend (attempt 0).
2. Call PerOutputTypeChecker.check() on all declared outputs.
3. Convert TYPE_CHECK_FAILED results to FailedOutput objects and call orchestrator.decide() 5.
4. On RETRY: update attempt = outcome.next_attempt, issue a new backend run with a distinct idempotency key, and repeat from step 2.
5. On USE_DEFAULT, FAIL_NODE, or TAKE_FAIL_BRANCH: apply terminal handling and exit.

Node inputs are captured only on the first attempt (attempt == 0) so retries don't pollute the inputs payload 6.

Failure Kinds#

OutputFailureKind has two values:

• TYPE_CHECK — produced by PerOutputTypeChecker: missing required outputs, type mismatches, invalid file references 7
• OUTPUT_CHECK — reserved for model-based file content checks (DeclaredOutputCheckConfig), enabled only for FILE-type outputs 8

Currently, the retry path is triggered by TYPE_CHECK failures. OUTPUT_CHECK infrastructure exists in the config model but is handled by a separate FileOutputCheckExecutor path.

Key Source Files#