Agent Engineering Best Practices
Copy page
Design AI agents that are focused, safe, and reliable. Learn the principles, patterns, and techniques for building high-quality agent systems.
Agent engineering is the discipline of designing AI agents that reliably accomplish their goals without over-constraining them. The key principle: treat tokens and attention as a shared budget. Prefer small, high-signal prompts plus strong output contracts over long prose.
This section covers the full lifecycle of agent design — from choosing the right pattern, to writing effective prompts, to testing and iterating on deployed agents.
Who this is for
These best practices apply to anyone designing AI agents — whether you're building single-purpose reviewers, multi-phase workflow orchestrators, or deciding if an agent is even the right tool for the job.
Section overview
Operating Principles
Core principles that guide every agent design decision — treating attention as scarce, optimizing for reliability, and writing for execution.
Choosing the Right Pattern
Decide between agents, skills, and always-on rules. Pick the right agent pattern: subagent vs workflow orchestrator.
Prompt Structure
Structure agent prompts for correct execution — role and mission, scope, workflow checklists, tool policies, and output contracts.
Personality and Identity
Write effective role and mission statements that guide agent judgment without creating risky escape hatches.
LLM Failure Modes
A catalog of systematic LLM failure modes and concrete techniques to guard against them in agent prompts.
Workflow Orchestrators
Design multi-phase coordinators that spawn subagents, aggregate results, and iterate with quality gates.
Handoff Protocol
Structure context passing between agents with handoff packets, return packets, and procedural patterns.
Testing and Iteration
Tune delegation behavior, debug underperformance, and update existing agents without drift.
Key concepts
Agents vs skills vs rules
Not every task needs an agent. Choose the lightest mechanism that reliably achieves the goal:
| Mechanism | Use when | Why |
|---|---|---|
| Always-on rules | Repo-wide constraints, commands, conventions | Applied everywhere; no routing needed |
| Skills | Reusable instructions in the main conversation context | Reuse without context isolation |
| Subagent | Single specialized worker/reviewer with tool restrictions | Isolated context + least-privilege tools |
| Workflow orchestrator | Multi-phase pipeline coordinating other agents | Encodes phase order, dispatch, aggregation, iteration |
The "Goldilocks zone" of strictness
Agent prompts should hit the right altitude — specific enough to guide, general enough to generalize:
| Failure mode | Symptom | Example |
|---|---|---|
| Too rigid | Brittle enumeration; breaks on unexpected inputs | "If .ts do X. If .tsx do Y. If .js do Z..." |
| Too vague | Abstract principles without concrete signals | "Be helpful and thorough." |
| Just right | Heuristics that generalize + clear escalation | "Prioritize correctness over style. When uncertain, ask." |
Quick reference: strictness by task type
- High freedom: heuristics + output contract (reviews, audits, brainstorming)
- Medium: step sequence + required checks (refactors, migrations)
- Low: scripts/commands + strict validation loops (fragile operations)