Guide
To debug a CrewAI agent in production, stop reading the final output and start reading the boundaries: what each tool actually returned, what crossed each handoff, and how many provider calls the whole crew made. Nearly every production failure in a multi-agent system is invisible in the final answer, because the system's job is to produce a plausible final answer regardless of what happened on the way there.
That is the part that makes agent debugging different from ordinary service debugging. A failed HTTP call in a normal service produces a stack trace. A failed tool call inside an agent produces a sentence, and the agent reads the sentence and keeps going.
This is the most common silent failure and the least visible. A tool raises, the wrapper catches it
and returns something like "Error: connection timed out", and that string goes back to the
model as an observation. The model does what it is built to do: it reasons over the text and produces
an answer that does not depend on the tool having worked.
The output looks fine. The run is worthless. Diagnose it by logging tool returns separately from tool successes — a call that returned is not a call that worked. In practice that means a typed result your crew logic inspects before the model does, so a failure can short the task instead of becoming narrative material.
When agent A finishes and agent B begins, what crosses is the task output. The reasoning, the discarded options and the constraints A discovered do not cross unless they were written into that output.
Most reports of "the second agent ignored the requirement" are not attention failures. The requirement was never in the payload. Log the exact object crossing every handoff boundary and the question stops being interpretive: either the constraint is in there or it is not.
A loop is usually a specification problem wearing a reasoning problem's clothes. If a task's expected output describes a state the agent has no tool to verify, it cannot confirm success, so it tries again. It will keep trying until the iteration ceiling stops it.
When you see a max-iteration termination, compare the task's success condition against the tools that agent actually holds. If nothing in its toolset can answer "am I done?", the loop was structural and no amount of prompt tuning removes it.
Agents in a crew usually share provider credentials. When one hits a limit and retries, and another retries behind it, the retries compound against the same quota. The early symptom is latency rather than errors, which is why this often gets diagnosed as "the model got slower".
Count requests per provider across the whole crew, not per agent. The per-agent view looks healthy because no single agent is doing anything unusual — the limit is shared and only the aggregate crosses it.
The same crew can take different valid routes to the same goal, and chasing that is wasted effort. What should be stable is structural: the handoff carried its required fields, the tool was called, the result had the expected shape.
Assert on structure, not on wording. Tests that compare final text will fail on successful runs and pass on broken ones, which is the worst of both.
Everything above depends on having recorded something at the moment it happened. Rerunning a crew does not reproduce the run you are trying to explain. At minimum, per run:
None of that needs a platform. It needs deciding what to write down before the failure, because after the failure the information is gone.
Because a tool error is returned to the agent as text, and text is exactly what the agent is built to reason over. If your tool catches an exception and returns a string like "error: timeout", the LLM treats that as an observation and writes around it. The fix is to make tool failures structurally distinguishable from tool results — return a typed failure your crew logic checks before the model sees it, and log the raw exception separately.
Handoffs pass a task output, not the reasoning that produced it. If the second agent needs a constraint the first one discovered, that constraint has to be in the output, not implied by it. Log the exact payload crossing each handoff boundary — most "the agent ignored X" reports turn out to be X never having crossed the boundary at all.
Usually a task whose completion condition the model cannot verify from the tools available. The agent tries, cannot confirm success, and tries again. Look for tasks whose expected_output describes a state the agent has no tool to check — that combination produces loops that look like reasoning failures but are specification failures.
A rate limit hit by one agent inside a crew usually retries, and a retry storm from several agents against the same provider key compounds. The first symptom is normally latency, not errors. Instrument per-provider request counts across the whole crew, not per agent, because the limit is shared and the per-agent view will look fine.
No, and treating it as one wastes time. The same crew can take different valid paths on identical input. What should be deterministic is the shape of the result and the boundaries between agents. Assert on structure — did the handoff carry the required fields, did the tool get called at all — rather than on wording.
FleetHelp watches these boundaries for you and tells you which one broke, in plain language, when an agent fleet misbehaves — the tool that returned without working, the handoff that dropped a field, the crew that looped because it could not check its own success condition. It is agent-to-agent support: your agents get a place to ask for help, and you get told what actually happened rather than what the final answer claimed.