Lab note · · 9 min read

Building reliable AI agents: structured prompting engineering

An agent that emits free text is unreliable. Structured output, explicit limits and a declared failure path are the difference between a nice demo and a system you can depend on.

AIAgentsPrompt engineering

After building several agents working in real security paths, I judge them by one criterion: can this agent fail in a way I can understand? An agent that gives a beautiful answer on success and pure ambiguity on failure cannot be used in any path where a decision depends on it.

1. Structured output, not free text

The weakest link in agents is the stage where the model's reply becomes a value the code uses. So the model is always asked for a fixed shape: decision, numeric confidence and a short reason — with pre-declared fields. If the reply does not match the shape, it is rejected, not cleverly repaired.

2. Four states are mandatory

  • Success: a clear decision with a reason.
  • Known failure: a classifiable error (timeout, missing field, malformed output).
  • Out of scope: the request is beyond the agent's remit — it must refuse clearly rather than guess.
  • Unknown: the dangerous one — if the agent cannot classify, it hands back to a human path or a declared fallback.
The rule I hold to: on ignorance the result is "I don't know", passed as an explicit value — not a guessed answer. Any agent in a security path must be able to say "I don't know".

3. The timeout is part of the logic, not of the settings

System stability must not depend on the mood of an external service. The timeout is fixed in code, with a predefined fallback when it is exceeded. In our case the fallback is conservatism (a challenge or a delay), not a hard decision.

4. Full logging of every call

Every agent call is logged with the input, the requested shape, the reply as received, the final decision and the call duration. Without that log you cannot answer the most important operational question: why did the agent decide what it decided in that case?

5. Evaluate before shipping, not after

Before any agent runs on a real path it is tested against a prepared set built to be adversarial: clear cases, boundary cases, and hostile cases crafted to tempt the model out of shape. An agent that does not pass the boundary set does not ship.

6. No execution from inside the model

The model proposes, the program executes after validation. Any direct action (running a command, modifying data, sending an external request) happens outside the model, with bounded permissions and an audit log. That separation is what prevents "hallucinations that execute".

Two lines to close

A reliable agent is not the smartest one, it is the most explicable one when it fails. If you always know why it decided what it decided, and why it refused what it refused, you are building a system; otherwise you are building a slide deck.