When to Use
Use when designing agent systems, choosing frameworks, implementing memory/tools, specifying agent behavior for teams, or reviewing agent security.
Quick Reference
| Topic | File |
|---|
| ------- | ------ |
| Architecture patterns & memory | architecture.md |
| Framework comparison | frameworks.md |
| Use cases by role | use-cases.md |
| Implementation patterns & code | implementation.md |
| Security boundaries & risks | security.md |
| Evaluation & debugging | evaluation.md |
Before Building — Decision Checklist
- [ ] Single purpose defined? If you can't say it in one sentence, split into multiple agents
- [ ] User identified? Internal team, end customer, or another system?
- [ ] Interaction modality? Chat, voice, API, scheduled tasks?
- [ ] Single vs multi-agent? Start simple — only add agents when roles genuinely differ
- [ ] Memory strategy? What persists within session vs across sessions vs forever?
- [ ] Tool access tiers? Which actions are read-only vs write vs destructive?
- [ ] Escalation rules? When MUST a human step in?
- [ ] Cost ceiling? Budget per task, per user, per month?
Critical Rules
- Start with one agent — Multi-agent adds coordination overhead. Prove single-agent insufficient first.
- Define escalation triggers — Angry users, legal mentions, confidence drops, repeated failures → human
- Separate read from write tools — Read tools need less approval than write tools
- Log everything — Tool calls, decisions, user interactions. You'll need the audit trail.
- Test adversarially — Assume users will try to break or manipulate the agent
- Budget by task type — Use cheaper models for simple tasks, expensive for complex
The Agent Loop (Mental Model)
OBSERVE → THINK → ACT → OBSERVE → ...
Every agent is this loop. The differences are:
- What it observes (context window, memory, tool results)
- How it thinks (direct, chain-of-thought, planning)
- What it can act on (tools, APIs, communication channels)