Twenty principlesfor agentic apps.
What 15 years of shipping software, and 20+ production AI systems, have left me recommending about building agentic applications and leading the people who do. A living list: I revise it when the world contradicts a rule.
- 01
Ship the thinnest slice to production.
A narrow system with real users teaches more in a week than a broad one in a demo environment teaches in a quarter. Idea to production in three months is a design constraint, not a boast.
- 02
Frameworks are replaceable. The architecture is not.
LangGraph, LlamaIndex, CrewAI and AutoGen will all be rewritten or retired. Keep orchestration, memory and tool boundaries explicit so swapping a library is a week, not a rewrite.
- 03
Narrow agents, explicit hand-offs.
One agent with one job is easier to evaluate, permission and replace than a generalist with every tool. Compose small agents through contracts you can test.
- 04
Make actions reversible, or idempotent.
Agents retry, loop and get interrupted. A retried call must not double-charge or double-send. Prefer operations you can undo, and treat the ones you can't as a separate class.
- 05
Ground answers in data the user may see.
Retrieval that ignores source permissions is a data leak with a nice interface. Carry access controls and freshness through ingestion, embedding and search.
- 06
Small toolset. Deny by default.
Every tool is attack surface. Give an agent only what its job needs, make each action allowed, approval-gated or denied, and make new tools justify the risk they add.
- 07
Short-lived, scoped credentials.
Hand each tool call a narrow, expiring, revocable capability, not a standing API key. A leaked token should be worth minutes, not months.
- 08
Treat every connector and tool output as untrusted.
MCP servers, web pages and retrieved documents can all carry instructions. Sandbox connectors, and treat what comes back as data, never as commands.
- 09
Humans approve the irreversible.
Money, deletions and outbound messages get an approval step. The agent proposes; a person disposes. Autonomy is something you widen as the record earns it.
- 10
Guardrails ship in v1.
Governance, explainability and red-teaming are architecture, not a phase two. Retrofitting them onto a system that already has users costs more than building them in.
- 11
Audit trail first.
If you can't replay a run, you don't own it. Build the record of who asked, what the agent saw, decided and did before building the feature that produces it.
- 12
Trace every run.
Correlate the request with retrieval, model and tool calls, and treat latency, failures and cost as first-class metrics. You can't debug an agent from its final answer.
- 13
Put models behind a gateway, and stay multi-vendor.
Route, budget, rate-limit and fall back in one place. Provider outages, price changes and deal changes then become configuration, not incidents.
- 14
Route by difficulty, not by prestige.
Send easy requests to cheap models and escalate to a frontier model only when the task needs it. Most of your traffic never needs the biggest model.
- 15
Budget every run, and keep a kill switch.
Cap tokens, steps, time and spend per run. A runaway loop is the new outage, and you want the brake before you need it.
- 16
Evaluation ships before features.
If you can't score retrieval and answers on your own data, you can't tell an improvement from a regression. Build the task set first and gate every release on it.
- 17
Make runs reproducible.
Pin model versions, fix seeds and prompts, record inputs. Nondeterminism you can't control makes debugging guesswork and audits impossible.
- 18
AI multiplies risk as well as output.
It speeds up mistakes as readily as work. Put the checks in CI, tests, types and policy, so they catch what a tired reviewer won't.
- 19
Stay in the code.
Leading a team is not a reason to leave the repository. Architecture decisions made without implementation context are guesses, and the team can tell.
- 20
Coach first, manage second.
The best output of a team lead is engineers who get promoted. Retention and growth are the lagging indicator of everything else being right.