When an agent misbehaves

A diagnostic order for the six things that actually go wrong, starting with the trace.

Work through these in order. The order is not arbitrary — it runs from the things that are cheap to check and commonly wrong, to the things that are expensive to check and rarely wrong.

Open the trace, not the board
The board shows the outcome. The trace shows the inputs, every tool call and what it returned, the decision, and the cost. Nearly every question about agent behaviour is answered in the tool-call list, and usually by something returning less than expected rather than by the agent reasoning badly.
Check whether the run stopped or failed
These are different outcomes and they mean different things. Stopped is correct behaviour — a source was unreachable, a limit was reached, an input did not make sense. Failed is an error. Reading a week of stops as failures is the most common misdiagnosis there is.
Check the tool list before the brief
An agent that never does a thing you asked for frequently cannot: the tool is not on its list, or the connection is read-only where the job needs a write. This looks exactly like a briefing problem and is not one.
Check the ceiling
An agent whose ceiling is nothing will read, classify, draft and hand off, and will not spend. If work stops precisely at the point money is involved, this is why, and it is the intended behaviour rather than a fault.
Check the approval queue
Work that looks stalled is often work that is waiting, correctly, on a person who does not know they are on the queue. Look at the oldest waiting item before concluding anything about the agent.
Then, and only then, look at the brief
If the tools are right, the ceiling is right, the queue is being read, and the trace shows the agent had what it needed and still chose wrongly — now it is the brief. See writing briefs for what is usually missing.

Two things that look like agent problems and are not

A connector that is listed but not connected: The catalogue lists every connector Hawi has a definition for. A definition is not a live connection. If an agent cannot see a system, check the connection is added to the workspace and verified before you look at anything else.
A model change nobody made: If an agent's stored model has been retired, the product surfaces that the selection needs re-picking rather than quietly routing elsewhere. An agent that has stopped running may be waiting for that choice.

When an agent misbehaves

A diagnostic order for the six things that actually go wrong, starting with the trace.

Work through these in order. The order is not arbitrary — it runs from the things that are cheap to check and commonly wrong, to the things that are expensive to check and rarely wrong.

Open the trace, not the board
The board shows the outcome. The trace shows the inputs, every tool call and what it returned, the decision, and the cost. Nearly every question about agent behaviour is answered in the tool-call list, and usually by something returning less than expected rather than by the agent reasoning badly.
Check whether the run stopped or failed
These are different outcomes and they mean different things. Stopped is correct behaviour — a source was unreachable, a limit was reached, an input did not make sense. Failed is an error. Reading a week of stops as failures is the most common misdiagnosis there is.
Check the tool list before the brief
An agent that never does a thing you asked for frequently cannot: the tool is not on its list, or the connection is read-only where the job needs a write. This looks exactly like a briefing problem and is not one.
Check the ceiling
An agent whose ceiling is nothing will read, classify, draft and hand off, and will not spend. If work stops precisely at the point money is involved, this is why, and it is the intended behaviour rather than a fault.
Check the approval queue
Work that looks stalled is often work that is waiting, correctly, on a person who does not know they are on the queue. Look at the oldest waiting item before concluding anything about the agent.
Then, and only then, look at the brief
If the tools are right, the ceiling is right, the queue is being read, and the trace shows the agent had what it needed and still chose wrongly — now it is the brief. See writing briefs for what is usually missing.

Two things that look like agent problems and are not

A connector that is listed but not connected: The catalogue lists every connector Hawi has a definition for. A definition is not a live connection. If an agent cannot see a system, check the connection is added to the workspace and verified before you look at anything else.
A model change nobody made: If an agent's stored model has been retired, the product surfaces that the selection needs re-picking rather than quietly routing elsewhere. An agent that has stopped running may be waiting for that choice.