[fix] Add exponential backoff to retry in prompts

[jp-agenta]

PR description

feat(sdk): exponential backoff for LLM prompt retries

What

Replaces the fixed-delay retry in the prompt execution engine with exponential backoff, and tightens the RetryConfig model with proper bounds and optional semantics. Updates all UI copy and published docs to match.

Changes

SDK — types.py

• RetryConfig.max_retries: int = 0 → Optional[int] = None, range [0, 5]
• RetryConfig.delay_ms → base_delay: Optional[int] = None, range [100, 1000] ms

SDK — handlers.py

• _coerce_retry_config takes retry_policy and fills safe defaults when policy is active and fields are None (max_retries=1, base_delay=1000)
• Sleep formula: (base_delay / 1000) * 2^attempt — first sleep equals base_delay, doubles each retry
• Both _should_retry and _run_prompt_llm_config_with_retry pass policy through to coercion

Frontend — agenta-entity-ui

• RetryConfigTab: delayMs → baseDelay, field key "delay_ms" → "base_delay", description updated, hardcoded max=10000 slider override removed
• PlaygroundConfigSection: all references updated

Docs

• 07-fallback-models-and-retry.mdx: JSON example + prose updated
• 01-configuration-management.mdx: reference table + JSON example updated
• 03-custom-workflow.mdx: code example + parameter description updated

Tests

• Schema property assertions and coercion default assertions updated in SDK and API unit tests

---

Summary of changes and implications

Model (sdk/agenta/sdk/utils/types.py)

• RetryConfig.max_retries: int = 0 → Optional[int] = None, capped at 5
• RetryConfig.delay_ms renamed to base_delay: Optional[int] = None, constrained to 100–1000 ms
• None is the canonical "not configured" state for both fields

Retry execution (sdk/agenta/sdk/engines/running/handlers.py)

• _coerce_retry_config now accepts retry_policy and fills safe defaults when the policy is active and a field is None: max_retries → 1, base_delay → 1000
• Sleep formula changed from fixed delay_ms / 1000 to exponential (base_delay / 1000) * 2^attempt (attempt is 0-indexed, so first sleep = base_delay, second = base_delay * 2, etc.)
• Both _should_retry and _run_prompt_llm_config_with_retry pass retry_policy through to coercion so defaults apply consistently

Retry schedule

attempt	sleep at base_delay=100ms	sleep at base_delay=1000ms
0	100ms	1s
1	200ms	2s
2	400ms	4s
3	800ms	8s
4	1600ms	16s

Max retries is capped at 5, giving a worst-case total wait of ~3.1s at 100ms base and ~31s at 1000ms base.

Frontend (agenta-entity-ui)

• RetryConfigTab: prop delayMs → baseDelay, field key "delay_ms" → "base_delay", slider description updated to reflect exponential behavior; removed hardcoded max=10000 override (bounds now come from schema)
• PlaygroundConfigSection: all delay_ms references updated throughout

Docs (docs/docs/)

• prompt-engineering/integrating-prompts/07-fallback-models-and-retry.mdx: JSON example updated, prose updated to describe exponential backoff
• reference/sdk/01-configuration-management.mdx: reference table updated (delay_ms → base_delay with range), JSON example updated
• reference/sdk/03-custom-workflow.mdx: code example and parameter description updated

Tests

• Schema property assertions updated ("delay_ms" → "base_delay") in SDK and API unit tests
• _coerce_retry_config default assertions updated to reflect None defaults

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Apr 30, 2026 1:09pm

[github-actions]

Railway Preview Environment

Status	Destroyed (PR closed)

Updated at 2026-04-30T15:36:49.533Z

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 5 additional findings.