A developer's field guide to AI agents

What an agent actually is

Strip away the marketing and an AI agent is a loop: a model that plans, calls tools, observes the results, and repeats until the task is done or it gives up. Everything else — memory systems, multi-agent orchestration, guardrails — is scaffolding around that loop.

The anatomy, concretely:

• Planner. The model itself, usually with a system prompt that defines its role, its available tools, and when to stop.
• Tools. Functions the model can invoke: shell commands, API calls, file edits, web search. Tools are the agent's hands; without them it's just a chatbot with ambitions.
• Memory. Short-term (the conversation context) and long-term (a vector store, a scratchpad file, a database). Agents without persistent memory re-learn the same lessons every session.
• Orchestration. The control flow — ReAct loops, plan-and-execute, or multi-agent handoffs — plus budgets: max steps, max tokens, max cost per run.

The failure modes nobody warns you about

Agents fail in boring, predictable ways. Knowing the catalog saves you weeks:

1. Tool thrash. The agent calls the same failing tool repeatedly, slightly varying the arguments, burning budget. Fix: track consecutive failures per tool and force a replan after three.
2. Context rot. Long runs accumulate stale observations. The model starts reasoning about a file state from 40 steps ago. Fix: compact aggressively — summarize and re-anchor every N steps.
3. Premature celebration. The agent declares victory without verifying. Fix: make verification a first-class step. Tests must pass, not just "look right."
4. Prompt injection via tool output. Any tool that reads external content (web pages, issues, files) can smuggle instructions into the context. Treat tool output as untrusted data, never as instructions.

Evals that actually catch things

Vibes-based testing ("I tried it and it seemed good") collapses the moment you ship. What works:

• Task-based evals. A fixed set of realistic tasks with programmatic checks. Run them on every prompt or model change, in CI, with diffs.
• Trajectory evals. Don't just check the final answer — check that the agent didn't take 47 steps to do a 5-step task. Step-count and cost-per-task are metrics, not trivia.
• Adversarial evals. Include tasks designed to trigger the failure modes above: poisoned tool output, ambiguous instructions, missing permissions.

A sane starting stack

If you're building your first production agent: one model, five or fewer tools, a hard step budget, trajectory logging from day one, and evals before the second feature. Complexity is the enemy — every additional agent in the system multiplies the failure surface.

The teams shipping reliable agents aren't using magic frameworks. They're using boring engineering: logging, budgets, tests, and the discipline to read the traces.