Architecture for agents that survive production
Agent demos are easy and agent products are hard. The gap is entirely in the constraints, and it is where most projects fail.
The short answer
Design the tools first. Each capability becomes a small function with a strict contract, validated inputs and predictable errors. The agent can only act through those functions, which makes the whole system testable — you can unit test a tool, you cannot unit test a vibe.
Then constrain the loop: a hard step limit, a spend ceiling per run, timeouts on every tool, and approval gates before anything consequential. An agent without a step limit will eventually loop, and it will do it on a weekend.
- Tools as tested functions with strict contracts
- Hard limits on steps, time and spend per run
- Approval gates on consequential actions
- Full traces you can read, replay and share
- An evaluation set of real tasks with known outcomes
- A kill switch that works mid-run
The three failures that kill agent projects
The first is unbounded loops. An agent with no step limit and a task it cannot complete will keep trying, and each attempt costs money. Every agent needs a hard ceiling on steps, on wall-clock time and on spend, enforced outside the model's own judgement.
The second is silent tool failure. When a tool returns an error the model does not understand, it often carries on as if the call succeeded, and the wrong answer arrives with full confidence. Tools must return structured, explicit failures, and the agent must be built to stop rather than improvise around them.
The third is no trace. When an agent produces a bad outcome and nobody can reconstruct which tools ran in what order with what inputs, debugging is guesswork. Tracing is not an observability nicety here; it is the only way to improve the system.
Designing tools the model can use
Most agent failures are tool-design failures. A tool with eight optional parameters and a vague description will be called incorrectly. One that does a single job, with two arguments and a description written for a competent stranger, will not.
Return values matter as much. Give back the smallest useful result rather than a raw API response, because every irrelevant field is context spent on nothing and an opportunity to misread. And make failures unambiguous: 'no customer found with that ID' is usable, a stack trace is not.
When not to build an agent
If the sequence of steps is known in advance, write the sequence. A workflow with a model call at three fixed points is cheaper, faster, more testable and easier to debug than an agent that rediscovers the same route every run.
Agents earn their complexity when the path genuinely varies with the input and the branching is too wide to enumerate. That is a smaller set of problems than the current enthusiasm suggests, and choosing the boring workflow is usually the senior decision.
Frequently asked questions
When should we not build an agent?
When the task has fewer than three steps, when the goal is ambiguous, or when errors are costly and nobody will review the output. A single well-designed prompt or a plain rules engine beats an agent in all three cases.
How many tools should an agent have?
Fewer than you think. Reliability drops noticeably as the tool count grows because selection gets harder. Two focused agents usually beat one agent with fifteen tools.
How do you debug an agent?
Traces. Every step records the reasoning, the tool called, the arguments and the result, replayable afterwards. Without that you are guessing at a non-deterministic system, which is not debugging.
Do multi-agent systems work?
Sometimes, for genuinely separable roles. Often they multiply failure modes and cost for no gain. We would want a measured reason before choosing one.
Tell us what you are building.
Send a short description of the problem and we will reply within one business day with an honest view of scope, cost and whether we are the right person for it.
Or email directly: contact@hire-ai-dev.com