How should errors propagate through an agent workflow?

Errors in an agent workflow should propagate as clear, structured failure information from the node where they occur to the part of the workflow responsible for recovery, escalation, or reporting. A failed node must not silently look like a successful one.

Example: API test-generation workflow

An agent extracts requirements, generates API tests, executes them, and prepares a report. During execution, its test runner cannot reach the staging service.

The execution node records an error such as:

• source: test_execution
• category: dependency_unavailable
• retryable: true
• attempt: 1
• message: Staging endpoint could not be reached

The orchestrator can now make an informed decision:

1. Retry the operation if the error is transient and a retry is safe.
2. Stop or escalate if attempts are exhausted or the dependency remains unavailable.
3. Report partial progress without claiming the tests passed.

If the failure were instead a missing authorization grant, retrying the same request would generally be inappropriate. The workflow should request an approved credential or escalate.

How do errors move between nodes?

• Detection: A node or tool identifies a failure.
• Classification: Convert the failure into a consistent error category with context.
• State update or exception: Record the error in workflow state, or allow an exception to reach the workflow runtime for its configured failure handling.
• Routing: Choose an allowed recovery node, terminal failure, or human-review path.
• Reporting: Expose the outcome clearly, preserving what succeeded and what did not.

An error record can contain run_id, node, error_type, retryable, attempts, timestamp, and sanitized details. Keep secrets, raw credentials, and sensitive payloads out of error messages and logs.

Local recovery vs. workflow failure

Local recovery makes sense when a node can handle a known problem safely—for example, correcting a malformed generated test after a validator identifies the exact issue.

Workflow-level failure is appropriate when the error prevents downstream steps from meeting their requirements—for example, a missing mandatory API specification. In that case, dependent nodes should not continue with incomplete or fabricated inputs.

For parallel branches, decide in advance whether a failed branch is mandatory (the join fails or waits for recovery) or optional (the join may proceed with an explicitly marked partial result).

Practical implementation tips

• Use a small, documented set of error categories rather than relying on free-form text.
• Keep the original failure context and record each recovery attempt.
• Bound retries with backoff, deadlines, and attempt limits.
• Check for completed external side effects before retrying a timed-out operation.
• Make terminal states explicit: succeeded, failed, cancelled, or needs_review.
• Include trace or correlation identifiers so failures can be followed across graph nodes and Celery workers.

In LangGraph, nodes can return structured error-state updates for conditional routing; unhandled exceptions can also interrupt execution according to the graph runtime and invocation setup. In Celery, failed tasks need an explicit orchestration policy rather than assuming their results will arrive normally.

In short

Propagate errors with enough context to choose a safe next action, but never hide failures or allow dependent nodes to treat them as successes.