ai-agent-design

AI Agent Design

An agent is a model in a loop with tools. That loop turns a wrong answer into a wrong action — so agent engineering is 20% prompting and 80% designing the action space so that the worst plausible sequence of tool calls is survivable. Build the cage before you build the brain.

Rule 0: Minimum viable autonomy

A workflow (fixed steps, model used inside steps) beats an agent (model chooses steps) whenever the steps are knowable in advance — cheaper, faster, testable, debuggable. Reach for a real agent loop only when the path genuinely varies per input (open-ended research, debugging, multi-step tasks with branching). Most "agents" in production should be pipelines with one or two agentic steps; start there and earn each degree of freedom you grant.

Tools — the real interface (design these hardest)

The model is a user of your tools; bad tool design causes most agent failures:

• One tool = one clear capability, named for intent (create_invoice, not run_query). Descriptions are prompts — state what it does, when to use it, when NOT to, and what it returns. Put decision guidance in the description, not hope in the model.
• Schemas do the enforcing: enums for closed choices, required vs optional made explicit, formats specified. Every parameter a schema validates is a hallucination class deleted.
• Errors are steering: return machine-readable, actionable failures ("date must be YYYY-MM-DD, got 'yesterday'") — the model reads errors and self-corrects; a bare 500 teaches it nothing and burns a loop iteration. Design tool errors as carefully as tool successes.
• Right-size the granularity: too atomic (5 calls to do one obvious thing) wastes loops and invites mis-sequencing; too broad (do_everything(params)) hides the decisions you wanted the model to make. A tool should map to one user-meaningful action.
• Tool results are context: return compact, relevant summaries with IDs for follow-up, not 40KB JSON dumps that flood the window.
• Building on a protocol (MCP or equivalent) beats bespoke integrations: tools become reusable across models and hosts — but the design rules above still decide quality.