In CrewAI, what happens to a crew run when a tool's _run raises an exception?

## The default behaviour CrewAI executes a tool through a usage layer, not by calling your function directly from the agent loop. That layer is what converts a Python exception into something an LLM can act on. In practice: the exception is caught, an error observation is produced, it is appended to the agent's message history as the result of that tool call, and the loop continues. The crew keeps running. This is deliberate — an agent framework whose runs died on the first 429 would be useless — but it means **your tool's failures become prompt content**, and that reframes how you should write them. ## Two layers of failure ### 1. Argument validation, before your code CrewAI validates the arguments the model produced against the tool's `args_schema`. A missing required field, a string where an int was declared, an unparseable date — these are rejected before `_run` executes, and the validation message goes back to the model. This layer is free error handling and it is the reason a tight Pydantic schema with per-field `Field(description=...)` is worth writing: it converts "the model guessed the format wrong" from a crash inside your code into a self-correcting turn. ### 2. Execution failures, inside your code Anything your `_run` body raises — a timeout, an auth failure, a KeyError on an unexpected response shape — is caught and surfaced to the model. What the model sees is derived from the exception, so an unhandled `KeyError: 'items'` becomes context the LLM has to interpret. It has no idea what your response schema is. It will often respond by retrying identically, which is the worst case. ## Why raising is the lazy option The error text is prompt engineering under a different name. Compare: - Raised, unhandled: a traceback fragment or `HTTPError: 500 Server Error for url ...`. The model learns almost nothing actionable and tends to repeat the call. - Caught and shaped: `"upstream search is unavailable; do not retry this call — proceed using the notes already gathered"`. The model has an instruction it can follow. So the discipline is: catch the failures you expect inside `_run`, classify them, and return a concise string that names the cause *and the next action*. Reserve raising for genuinely unexpected states. Also keep the text short — a 4 KB error body in context is billed on every subsequent turn of that agent's loop, and it crowds out the actual work. ## Retry, and who owns it Some failures should never reach the model at all. A connection reset, a 429 with a `Retry-After`, a transient DNS blip: retry those *inside* `_run` with a bounded backoff, because a code-level retry costs milliseconds while a model-level retry costs a full round trip and tokens. Failures that need a *decision* — no results, ambiguous input, permission denied — belong to the model, because the model is the thing that can choose a different approach. ## Bounding the loop An agent that cannot make progress will keep trying. The bounds available are the agent's iteration limit (`max_iter`) and its rate limit (`max_rpm`), and CrewAI additionally discourages an agent from repeating an identical failing call rather than letting it spin on the same input forever. Set `max_iter` deliberately for agents holding fragile tools; the default is generous, and "generous" times "a tool that is down" equals a large bill and a task that eventually returns an apology instead of an answer. ## Caching interacts badly here Crew-level tool caching is on by default and keys on tool plus arguments. If a failure result gets cached, the model's retry is answered from the cache and never re-executes — so the agent sees the same error no matter what, and concludes the capability is dead. Give any tool that can fail a `cache_function` that returns False for error and empty results. ## Observability Because failures are absorbed into the conversation, they are invisible in a naive "did the crew succeed" check: `kickoff()` returns a `CrewOutput` and the run looks green while a tool failed forty times. Log inside `_run` — before the return, on every path — and emit a metric per failure class. When you are debugging, `verbose=True` on the agent or crew shows the tool calls and their observations in the console, which is usually the fastest way to see that the model has been staring at the same error for six iterations. ## The interview answer Lead with "the run continues, the error becomes an observation". Then make the senior point: because the error is prompt content, error text is an interface you design; retry transients in code and escalate decisions to the model; bound iterations; and don't let a failure land in the cache.