A correction nudge is a short corrective instruction the runtime injects back into the conversation when a sub-agent's routing intent does not make sense. Rather than failing the run, it asks the agent to try again.
All nudges are soft and bounded. They never hard-fail a run; once the retry budget is spent, the runtime falls back to a reasonable default and moves on.
The four triggers
The entry-agent rule. If the graph's entry sub-agent ends its very first turn with a plain answer instead of routing anywhere, it is nudged to actually route — or ask one clarifying question — rather than having a fabricated direct answer accepted. This fires only on that sub-agent's first-ever routing decision. A normal synthesis answer after a successful handoff is never nudged.
Ambiguous routing. A turn asking for more than one route at once — two transfers, or a transfer mixed with delegations — is nudged to pick one. Bounded by a small retry budget, then a deterministic fallback. If it still cannot be resolved, the run ends with ambiguous_handoff.
Oscillation (A→B→A). A sub-agent immediately handing control back to whoever just handed off to it is nudged against the bounce-back. Notably, it is allowed through after a couple of nudges, so graphs that genuinely need back-and-forth still work.
Repeat delegation. Delegating to a target already consulted earlier in the same conversation is nudged to avoid the redundant ask.
Recognising one in a trace
Two signatures:
- A conversation turn containing a
[SYSTEM]block you did not write and the user did not send. This is the runtime's own instruction. - A
route_errorimmediately followed by the same sub-agent taking another turn — nudge-and-retry, not failure.
Two misreadings to avoid
Treating a [SYSTEM] block as user input, or as a prompt-injection attempt to defend against. It is the runtime's internal correction mechanism.
And assuming an oscillation nudge means the graph is broken. A small amount of legitimate back-and-forth is expected and permitted. Persistent nudging is the signal worth acting on — it usually means two sub-agents have overlapping responsibilities and neither clearly owns the request.