AI Retry

The ai-retry block runs a protected process chain and, when it fails, lets an LLM inspect the error and the message, revise the message, and re-run the chain, up to maxAttempts times.

A complete example

Here the protected chain is an ai-mapping whose schema validation gives ai-retry something concrete to recover from:

service:
  name: ai-retry

env:
  - name: ANTHROPIC_API_KEY
    required: true

connectors:
  - name: claude
    type: llm-anthropic
    settings:
      apiKey: ${ANTHROPIC_API_KEY}

flows:
  - name: charge
    process:
      - type: ai-retry
        name: resilient-charge
        connector: claude
        maxAttempts: 3
        prompt: >
          A step failed building the charge request. Inspect vars.error and the
          message body, correct the body (for example, fix a malformed amount or
          a missing currency), and produce a revised message to retry.
        process:
          # ai-mapping validates against outputSchema and errors on a bad shape,
          # giving ai-retry something to recover from.
          - type: ai-mapping
            name: build-charge
            settings:
              connector: claude
              prompt: "Build a Stripe charge request from the order."
              outputSchema: |
                {
                  "type": "object",
                  "required": ["amount", "currency"],
                  "properties": {
                    "amount":   { "type": "integer" },
                    "currency": { "type": "string" }
                  }
                }
        error:
          - type: set-payload
            settings:
              value: '{"status": "degraded", "reason": vars.error.message}'

The ai-retry sample in the visual editor

ai-retry is a composite: connector, prompt, maxAttempts, the protected process, and the error chain sit at the top level of the block.

How the loop works

The protected process chain runs. On success the block is a pass-through and no model call is made.
On failure, the error is stored in vars.error and the model is shown the error, the current message body, and the current variables.
The model calls a revise_message tool with a corrected body and, optionally, variables to set or override, since a failing step often reads vars.<name>.
The revision is applied to the message and the chain re-runs. Another failure feeds the new error back to the model, up to maxAttempts (default 3).

If every attempt fails, the block falls through to its error chain with vars.error set. With no error chain, the last error propagates to the surrounding recovery path. The prompt is your domain guidance to the repair model: what the step expects, what corruption to look for, what a valid message looks like.

When to use it

ai-retry suits failures that are data-shaped: a malformed field, a missing value, an output that failed schema validation. The canonical pairing is ai-retry around ai-mapping, whose validation failures come with a precise error message the model can act on.

When not to use it

Avoid it for	Because
Failures no message revision can fix: an expired API key, a network outage, a downstream 500	The model burns attempts changing a body that was never the problem. Use plain error handling and backoff.
Non-idempotent chains	Every attempt re-runs the entire protected chain from the top, so a step that sends an email, writes a record, or charges a card runs again. Keep side-effectful steps outside the chain, after it succeeds.
Mechanically fixable errors	If you can name the fix ("default the currency to USD"), do it with a transform. A model call is the expensive way to apply a rule you already know.
Hot, latency-sensitive paths	Each attempt costs at least one model call on top of re-running the chain.

On success ai-retry adds zero cost and zero latency; the model is only consulted when the chain fails.

Full field tables: AI Blocks reference.

A complete example

How the loop works

When to use it

When not to use it

On this page