NVIDIANVIDIA-Certified Professional: Agentic AI2026-102.4 Implement error handling (retry logic, graceful failure recovery).
Route failures to the right owner
Completed by the knowledge check
Learning objective
Classify failures and decide whether to return them to the LLM as observations or raise them to the caller.
Core idea
A failed tool call can contain useful information for the next reasoning step, or it can signal that execution must stop. Choose the recipient by asking who can change the condition safely. A model can correct a malformed search query. It cannot restore an expired service credential, repair a broken dependency, or establish whether a timed-out payment committed.
Returning an observation keeps the agent loop alive and spends more inference tokens. Raising an exception transfers control to the caller, where deployment recovery, cancellation, and business reconciliation belong. Neither choice turns failure into success. See 1.2.2 for the ReAct loop itself; this lesson decides what information crosses its failure boundary.
How it works
Classify cause, repairability, and outcome certainty
Create a failure-policy table for each tool before exposing it to the agent. Record the failure category, whether another attempt is safe, the permitted recipient, and the terminal outcome. Keep outcome certainty separate from cause: a network timeout can be transient while the result of a write remains unknown.
Use the following distinctions when implementing that policy:
| Failure | Deciding condition | Mechanism and recipient | Cost or risk |
|---|---|---|---|
| Correctable tool input | The model can supply a valid alternative without extra authority | Return a sanitized tool observation with the invalid field and permitted correction | Another model turn and validation pass |
| Valid business rejection | The request is valid but the operation is unavailable under business rules | Return a domain result, such as no matching inventory | The model must not report completion |
| Temporary dependency failure | Repeating the operation is safe and fits the remaining budget | Adapter retry policy; raise after exhaustion | Extra traffic and elapsed time; see 2.4.2 |
| Authorization or configuration defect | Repair requires an operator or caller decision | Raise a classified exception to the caller | Request fails until the owner fixes the cause |
| Ambiguous write outcome | The remote system might have committed | Caller reconciliation using the operation identifier | Duplicate side effects if blindly repeated; see 2.4.4 |
| Cancellation | The caller no longer wants execution | Propagate asyncio.CancelledError after cleanup | Continued work wastes capacity and can create unwanted writes |
These are application policy categories, not NVIDIA exception class names. The adapter must translate its dependency’s actual response into the chosen category. Do not infer retry safety from the exception’s text alone.
Configure the NVIDIA failure boundary
Choose the error boundary for the configured agent; the three agents below require nvidia-nat[langchain]. For ReAct, use pass_tool_call_errors_to_agent; see 1.2.2 for its loop and recovery budgets. The defaults differ by agent:
Agent _type | Error control and default | Failure destination |
|---|---|---|
react_agent | pass_tool_call_errors_to_agent: true | Errors go to the agent; false raises an exception |
tool_calling_agent | handle_tool_errors: true | Tool errors are caught and returned in a ToolMessage so the agent can retry |
rewoo_agent | raise_tool_call_error: true | Raises immediately; false includes the error message in the tool response passed to the next tool |
ReWOO also documents tool_call_max_retries with a default of 3. Do not transfer a retry count or error-handling flag from one agent to another. These workflow controls do not replace classification inside the tool adapter.
For a ReAct workflow that mixes correctable input errors and privileged writes, return expected, safe domain outcomes explicitly from the adapter and configure unexpected tool exceptions to escape with pass_tool_call_errors_to_agent: false. This prevents an infrastructure exception from becoming another model instruction. The adapter owns which information it returns; the workflow owns whether uncaught tool exceptions reach its caller.
Model-output parsing failures have a separate recovery budget; see 1.2.2.
Preserve useful information without leaking internals
A repair observation should identify the attempted operation, the invalid input, and the allowed next step. For example, an application-defined result can say that date_range exceeds the permitted reporting interval and request a shorter range. The error should not expose service credentials, full stack traces, or an unrestricted alternate endpoint.
In the toolkit, function middleware can preprocess inputs, postprocess outputs, and short-circuit execution. The documented FunctionMiddleware.function_middleware_invoke interface receives call_next; an adapter or wrapper can validate before calling it and translate expected failures into safe results. Keep unexpected exceptions visible to the caller rather than converting every exception into an answer-shaped string.
Cancellation is neither a repair observation nor a classified dependency failure: propagate it after cleanup (see 1.8.2).
Key distinctions and trade-offs
An observation changes the agent’s next decision; a retry repeats an execution path. A corrected query is a different input, while repeating a timed-out request unchanged is a transport recovery attempt. Count and measure those separately so that a small tool retry limit does not hide repeated model-directed calls.
A business rejection is also different from a runtime exception. An unavailable reservation is a valid result that the assistant can explain. An inability to contact the reservation service is an execution failure. Converting both into “not available” produces false business information and sends the wrong signal to operations.
Passing errors to the model improves recovery only when the model has the information and authority needed to repair them. Raising everything loses useful interactive correction; returning everything hides defects and increases token consumption. The tool owner defines expected domain failures, while the workflow owner chooses the escaping-exception policy.
Architecture / decision scenario
A hospital employee assistant prepares staff-training reports. It has a six-second response target and two tools: a read-only report search and an enrollment writer. Search rejects date ranges longer than 31 days; enrollment requires a service identity and can modify an employee’s record. These are deployment requirements, not toolkit defaults.
A proposed design returns every exception to the model because it can reformulate requests. The application architect rejects that blanket policy. A 60-day search becomes a sanitized observation requesting a range of at most 31 days. The adapter uses an application-defined, request-scoped correction_attempts counter to permit one corrected search call; if that call is also invalid, it raises to the caller instead of returning another repair observation. An enrollment authorization failure escapes to the caller and alerts the service owner; another prompt cannot grant the missing permission.
If enrollment times out after submission, the caller uses the stored enrollment operation identifier to reconcile its status before another write. The assistant reports that enrollment is unconfirmed. It does not turn the timeout into an invitation to try a different employee identifier. pass_tool_call_errors_to_agent: false handles uncaught exceptions, while expected search corrections remain ordinary adapter results. The tool owner tests each category, and the workflow owner verifies that the six-second budget includes any corrective model turn.
Common exam traps
- Treating every exception as useful model feedback.
- Treating a valid business rejection as proof that the dependency failed.
- Assuming a tool retry limit also bounds model-directed corrections or elapsed time.
- Returning raw exception strings that expose credentials or operational details.
- Swallowing cancellation and continuing side-effecting work.
- Reporting an unknown write outcome as either confirmed success or confirmed failure.
What to remember
Send the model only failures it can safely act on. Return expected domain outcomes deliberately, raise infrastructure and authority failures to their owner, and preserve uncertainty after ambiguous writes. Configure the selected agent’s error boundary explicitly and keep cancellation separate from ordinary recovery.
Knowledge check
A NeMo Agent Toolkit react_agent workflow has two tools: a report search the model can correct by shortening a date range, and a privileged enrollment writer. The adapter returns expected date-range corrections as ordinary results. Unexpected infrastructure exceptions must reach the caller instead of the model. Which workflow setting meets this requirement?
pass_tool_call_errors_to_agent: truehandle_tool_errors: falseraise_tool_call_error: truepass_tool_call_errors_to_agent: falsepass_tool_call_errors_to_agent defaults to true , which turns every escaping exception into model input; false raises it to the caller, while the adapter returns expected corrections as ordinary results. handle_tool_errors belongs to the Tool Calling agent and raise_tool_call_error to ReWOO, so neither changes a ReAct workflow.An enrollment tool’s service identity starts receiving authorization denials after a credential rotation. The agent could call the tool again with different arguments. Where should this failure go?
A booking adapter’s read-only availability lookup returns “no rooms available” both when the hotel has no inventory and when it cannot reach the reservation service. Operations sees no dependency alerts during an outage, and users are told the hotel is full. How should the adapter handle an unreachable reservation service?
A ReAct assistant with pass_tool_call_errors_to_agent: false rejects report-search ranges longer than 31 days with a sanitized correction. The adapter’s transport retry limit is 2, yet traces show one request making six model-directed corrected searches, breaking the six-second target. The team wants to keep one correction per request. What should it add?
References
- NVIDIA, Configure the ReAct Agent
- NVIDIA, Configure the Tool Calling Agent
- NVIDIA, Configure the ReWOO Agent
- NVIDIA, Middleware
- Python Software Foundation, Coroutines and Tasks