Agents

--- name: Agents description: Design, build, and deploy AI agents with architecture patterns, framework selection, memory systems, and production safety. ---

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

1. Start with one agent — Multi-agent adds coordination overhead. Prove single-agent insufficient first.
2. Define escalation triggers — Angry users, legal mentions, confidence drops, repeated failures → human
3. Separate read from write tools — Read tools need less approval than write tools
4. Log everything — Tool calls, decisions, user interactions. You'll need the audit trail.
5. Test adversarially — Assume users will try to break or manipulate the agent
6. 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)