Lesson 07 · Shapes · 13 min
Guarding actions
Most tools only read. Getting a read wrong wastes a call. A tool that changes something — issues a refund, sends a message, cancels an order — is a different category, because getting it wrong produces consequences no retry can undo.
The instinct is to write a careful prompt. Prompts are guidance, not enforcement, and an agent that follows one nine times in ten will still take the tenth action. Enforcement belongs in the tool.
- Preconditions: refuse until the required checks have happened. The refund tool here refuses until the refunds policy has been read.
- Validation: check the arguments against reality. A refund larger than the order total is refused regardless of how confidently it was requested.
- Idempotency: a second identical write should be a no-op, not a second effect.
- Refusal as information: return a clear reason. "Refused: order is in transit and not refundable yet" lets the loop adapt; a bare error makes it retry.
A refused write is a good outcome, not a failure. The lab includes a task asking for a refund on an order still in transit. The correct behaviour is to discover that it is ineligible and explain so — and the interesting thing to watch is whether the agent accepts the refusal or keeps trying to force it through.
The lab marks every side-effecting call in the trace. In a real system that mark is your audit trail: for any agent action, you should be able to show which iteration caused it and what the agent knew at the time.
Checkpoint
Produce a run where a write is correctly refused and the agent explains why rather than retrying.