# Practices for Embedding AI Agents in Software # Read-Free / Write-Gated 🎯 The Hook Approving every single tool call is a recipe for approval fatigue, where the rubber-stamp on a dangerous write operation is just one click away. Separate reads from writes and focus human attention where it matters. 🔥 The Problem Agents mix side-effect-free reads with irreversible writes. Gating everything equally drowns humans in approval requests. Since reads dominate most workloads, approval fatigue sets in fast, and the critical write approvals get waved through without scrutiny. Remove all gates, though, and you risk irreversible damage from unchecked writes. 💡 The Pattern Split tool calls into "read" (search, fetch, reference) and "write" (create, update, delete, send). Let reads flow freely while gating writes with authorization, validation, approval, and audit. Classify R/W statically at tool registration time in code, never by LLM judgment. Graduate write gate strictness by reversibility: irreversible operations like email sends or payments require human approval, while reversible ones like draft saves pass through policy validation only. This dramatically reduces approval fatigue while maintaining safety for side effects. ✅ When to Use Use when: - Read and write operations are mixed, with reads making up the majority - Irreversible writes exist (email sends, payments, production DB changes) - You need to preserve human review bandwidth for high-risk operations Don't use when: - Reads themselves access sensitive data (PII lookups, confidential documents) and need authorization too - All operations are read-only with no writes at all - It's an experimental environment where all operations are reversible and low-cost ⚠️ Pitfalls - Never let the LLM classify read vs. write. Injection can make it label a write tool as "read," bypassing the gate entirely - Watch for "reads with side effects" like API call counters or view history tracking - Applying the same gate strictness to reversible and irreversible writes brings approval fatigue right back 🔧 Implementation Approach - Assign type (read/write) and gate mode (none/auto/human_approval) statically at tool registration, making it structurally impossible for the LLM to reclassify at runtime - Implement the write path as a pipeline of input validation, gate evaluation, execution, and full audit logging, while reads log only metadata - Graduate write gate strictness using a reversibility flag, combining irreversible operations with mandatory dry-run as a prerequisite - Enforce all gate logic in deterministic code at the gateway layer, with zero reliance on prompt-based access control #AIAgents# #SoftwareArchitecture#