Set Hermes Iteration Budgets and Provider Retry Behavior

Complex Hermes work can require many tool and model iterations. The global per-turn backstop is agent.max_turns, which defaults to 500. Hermes does not apply early 70% or 90% pressure warnings; those warnings caused capable agents to abandon long tasks prematurely.

agent:
  max_turns: 500
  api_max_retries: 3

When the budget is actually exhausted, Hermes asks the model to wrap up and permits one grace call for a final response. The CLI then warns that the response may be incomplete.

Separate iteration limits from API retries

agent.max_turns limits the agent loop for one conversation turn. agent.api_max_retries controls retries of transient provider failures before a configured fallback provider is tried.

The default retry value of 3 means four total attempts on that provider. If a healthy fallback should take over immediately, setting retries to 0 avoids repeatedly calling a flaky primary route. If no fallback exists, a low retry setting can turn brief network noise into more visible failures.

Tune from observed behavior

1. Keep the default turn budget for general interactive work.
2. Measure why a long workflow consumes iterations before raising the ceiling.
3. Fix repeated no-progress loops with tool-loop guardrails rather than only adding turns.
4. Confirm the fallback chain before reducing provider retries.
5. Use deterministic scripts for collectors and reports that do not need an agent loop.

A larger budget is not a quality setting. It only allows more iterations; it cannot repair a broken tool, impossible goal, or missing credential.

Operations checklist

• The expected workflow length is understood.
• Provider fallback is actually configured before retry tuning.
• Repeated failures are distinguished from legitimate long progress.
• Unattended runs have explicit delivery and failure reporting.
• Budget exhaustion is treated as potentially incomplete work.

Common pitfalls

• Raising the budget to mask a loop. Repetition should trigger diagnosis or a circuit breaker.
• Setting retries to zero without fallback. A transient primary failure may become final immediately.
• Counting retries as turns. Provider transport retries and agent reasoning iterations are different controls.
• Treating the grace call as completion proof. The final summary can honestly describe incomplete work.

Verification

Inspect the effective configuration, then run a bounded disposable task whose completion is easy to observe. Confirm a normal task finishes far below the cap. For retry changes, use a controlled non-production provider test and verify logs show the expected handoff rather than inferring behavior from the final answer.

Official reference: Hermes configuration.