ai-agent-patterns

Design patterns for agents that don't crash.

An interactive reference of 12 battle-tested design patterns for building reliable AI agent systems. Every pattern was discovered the hard way — running 7 AI agents in a production organization across 200+ sessions and 155 commits over 6 months.

Most agent tutorials show you how to get a demo working. This reference shows you what happens next: the retry storm that crashes your orchestrator, the shared state that corrupts when two agents write simultaneously, the agent that responds "Done." to every follow-up question. If you are building agents that need to survive past the first week, these patterns are your field guide.

| # | Pattern | Complexity | Problem | |---|---------|-----------|---------| | 01 | Death and Resurrection | Foundational | Agent sessions reset but knowledge must persist | | 02 | Circuit Breaker | Intermediate | Failing agent retries indefinitely, cascading failures | | 03 | Heartbeat Monitor | Foundational | Zero visibility during agent execution |

| # | Pattern | Complexity | Problem | |---|---------|-----------|---------| | 04 | Conversation Mode Switch | Intermediate | Task persona overrides conversational intent | | 05 | Structured Handoff | Foundational | Agent-to-agent handoffs lose context | | 06 | Hollow Response Guard | Foundational | Agents respond "Done." with no substance |

| # | Pattern | Complexity | Problem | |---|---------|-----------|---------| | 07 | Workspace Isolation | Intermediate | Shared workspace causes agent crosstalk | | 08 | Atomic File State | Advanced | Concurrent JSON writes corrupt data | | 09 | Error Classification | Intermediate | Permanent errors retry forever |

| # | Pattern | Complexity | Problem | |---|---------|-----------|---------| | 10 | Capacity-Gated Dispatch | Intermediate | Over-dispatch causes r