Common Fundamentals Mistakes New Agent Builders Make

This page enumerates the recurring fundamentals mistakes that show up when teams first ship multi-turn, tool-using agents.

Use it as a retro catalog and as a pre-flight review for new agent projects.

How to Use This List

• Read by area when debugging; read top to bottom when onboarding.
• For each incident, tag the nearest mistake number and link the fix rule.
• Do not treat the list as shame - treat it as patterns that appear under time pressure.
• Pair with AI Agent Fundamentals Rules Best Practices to convert fixes into lasting checkboxes.

Scope Mistakes (1–5)

1. Building an agent when a script already knows the path - every run re-discovers a fixed workflow with tokens and flaky branches.

   • Why it happens: "Agent" is treated as the modern default for any LLM feature.
   • Fix: Apply Scope Rules; encode stable paths in code or a workflow tool.

2. No written definition of done - the loop cannot succeed because success was never operationalized.

   • Why it happens: Goals stay as stakeholder prose ("make support better").
   • Fix: Write a pass/fail goal and out-of-scope list before tools are wired.

3. Granting write tools on day one - the first prototype can already email, refund, or delete.

   • Why it happens: Desire to demo full autonomy early.
   • Fix: Start read-only; add irreversible tools only after stops, evals, and gates exist.

4. Tool inventory sprawl - twenty overlapping tools make selection noisy and insecure.

   • Why it happens: "Might need it later" permissions.
   • Fix: Cap tools to the current goal; split agents rather than inventing mega-tools.

5. Jumping to multi-agent before one agent is bounded - handoffs multiply unbounded cost and confusion.

   • Why it happens: Architecture fashion outruns fundamentals.
   • Fix: Prove a single agent with stops and scope first.

Stopping Mistakes (6–10)

6. No max turns - the process runs until someone kills the worker or the bill shocks the team.

   • Why it happens: Demos exit "naturally" on short prompts.
   • Fix: Enforce max turns in runtime code for every production path (Stopping-Condition Rules).

7. Max turns without wall-clock timeout - one hung tool freezes the run forever inside a "safe" turn budget.

   • Why it happens: Teams only think in model iterations, not wall time.
   • Fix: Whole-run and per-tool timeouts.

8. Trusting the model to announce completion - free-text "I'm done" with failing tests or empty deliverables.

   • Why it happens: Chat UX habits transfer into agent runtimes.
   • Fix: Goal predicates and oracles (tests, schema validation, ticket ids).

9. Infinite polite retries - the agent re-calls the same search or rebuild with identical arguments.

   • Why it happens: No-progress detection is missing; errors look temporary.
   • Fix: Signature counters, error classification, escalate instead of blind retry.

10. Silent death on stop - UX shows nothing; operators cannot tell timeout from success.

    • Why it happens: Stops were added as afterthoughts without product states.
    • Fix: Machine-readable stop reasons surfaced to logs and users.

Context Mistakes (11–15)

11. Unbounded transcript growth - every tool dump stays forever until quality collapses.

    • Why it happens: Fear of amnesia; large context marketing.
    • Fix: Explicit trim/summarize policy (Context Discipline).

12. Mixing stable policy with volatile state in one blob - dates, ids, and one-off notes invalidate structure and caches.

    • Why it happens: Fastest way to "just add a sentence."
    • Fix: Sectioned system policy; dynamic facts in turn payloads.

13. Re-pasting entire files each turn - token burn and stale copies.

    • Why it happens: Tools return whole files; nobody caps adapters.
    • Fix: Truncate/summarize at tool boundary; pass references and slices.

14. Unreviewed system-prompt accretion - contradictory instructions accumulate across engineers.

    • Why it happens: Each defensive line seems cheap.
    • Fix: Owner + reason for every policy change; prune unjustified lines.

15. Ignoring what the model actually saw - debugging only the final answer, not the window.

    • Why it happens: Logs omit prompts and tool results.
    • Fix: Trace policy, transcript slices, and tool payloads per turn (redact secrets).

Model and Cost Mistakes (16–20)

16. Hardcoding one frontier model everywhere - outages and price changes require code archaeology.

    • Why it happens: Safety theater during the first spike.
    • Fix: Logical model policies (Model-Swapping Rules).

17. Escalating tier without evidence - cost rises without measured quality gain.

    • Why it happens: Stronger feels safer.
    • Fix: Eval samples before promotion; de-escalate when data allows.

18. Forgetting that turns multiply tokens - budgeting as if each request were single-shot chat.

    • Why it happens: Chat pricing intuition.
    • Fix: Estimate tokens × expected turns × price; enforce stops as cost fuses.

19. No record of which model ran - retros cannot correlate quality or spend.

    • Why it happens: Gateway or SDK hides identity.
    • Fix: Persist resolved model id and policy name on every run.

20. Swapping models without re-testing tools - tool-calling skill differs by tier and provider.

    • Why it happens: Assumes all chat models are interchangeable agents.
    • Fix: Tool-specific evals on each candidate tier.

Process Mistakes (21–24)

21. Demo code becomes production - notebook loops with no policy ship behind an API.

    • Why it happens: Pressure to show progress.
    • Fix: Promote only through a checklist of fundamentals rules.

22. No owner for agent standards - each squad reinvents bounds differently.

    • Why it happens: Agents treated as feature code only, not platform.
    • Fix: Named owner for fundamentals defaults; review on a cadence.

23. Skipping evals until after users complain - regressions hide in "vibes."

    • Why it happens: Harder to write oracles for soft tasks.
    • Fix: Even a small golden set beats none; expand with incidents.

24. Treating fundamentals as optional polish - teams buy frameworks first, bounds never.

    • Why it happens: Tooling excitement outruns systems thinking.
    • Fix: Read Why Fundamentals Rules Prevent Early Agent Project Failures and enforce the core list before multi-agent ambition.

FAQs

Related

• Why Fundamentals Rules Prevent Early Agent Project Failures - mental model behind these failures.
• The Core Agent Fundamentals Rules: A Quick-Reference List - positive defaults that prevent the mistakes.
• Scope Rules: When a Problem Actually Needs an Agent - fixes for mis-scope.
• Stopping-Condition Rules Every Agent Must Implement - fixes for runaway loops.
• AI Agent Fundamentals Rules Best Practices - checklist form of the remedies.

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.