Shipping your first LLM agent: what the tutorials skip

A weekend demo of an LLM agent feels like magic. The same agent in front of real users, three weeks later, feels like a pager going off at 2am. The gap is almost never the model. It is the plumbing.

Tools are an API contract, not a prompt

The biggest reliability win is treating every tool as a strict, typed contract: describe exactly what it does, what it returns, and what it must never do. Validate the arguments before you run anything.

• Give each tool one job and a precise description.
• Validate arguments and reject bad calls with a readable error.
• Make every call idempotent so a retry can never double-charge or double-send.

Make every step observable

You cannot debug what you cannot see. Log the full input and output of every step, including the raw model response and each tool result. When something breaks, you want a transcript, not a guess.

def call_tool(name, args):
    log.info("tool.start", name=name, args=args)
    result = TOOLS[name](**args)
    log.info("tool.end", name=name, result=result)
    return result

Fail loudly, retry narrowly

Cap the agent loop. If it has not finished in N steps, stop and surface the partial result instead of spinning forever. Retry a single failed tool call, not the entire conversation.

An agent that admits it is stuck is more useful than one that confidently does the wrong thing.

None of this is glamorous. That is the point. The teams whose agents survive contact with users are the ones who got the boring parts right first.