# Practices for Embedding AI Agents in Software # Dry-run & Commit / Plan-then-Apply 🎯 The Hook An LLM hallucinated a payment amount and your agent executed it. With a dry-run step, you would have caught it before any money moved. 🔥 The Problem LLMs can hallucinate parameters, and tool calls carry real-world side effects. When these two combine, an agent may execute an irreversible operation with a nonexistent resource ID or a wildly wrong amount. Without a preview step, humans have no way to inspect what the agent intends to do until the damage is done. 💡 The Pattern Split side-effect operations into two phases: plan (dry-run) and apply (commit). In the dry-run phase, compute a diff of what would change without modifying any state. Present the diff for approval, then execute the commit only after authorization. Graduate approval by risk level: human approval for high-risk, automated policy checks for medium, auto-approve for low. Attach a TTL to each plan and re-verify preconditions at commit time to guard against state drift between phases. ✅ When to Use Use when: - The agent executes irreversible operations (data deletion, external API writes, billing) - Mistakes carry financial, legal, or operational consequences - A few seconds to minutes of latency for review is acceptable Don't use when: - All operations are read-only - All operations are reversible and low-cost (e.g., chat response generation) - Latency constraints are too tight to allow an approval step ⚠️ Pitfalls - TOCTOU: state can change between plan and commit. Always re-verify preconditions at commit time - When external APIs lack a dry-run mode, substitute with parameter validation and simulation, and clearly mark the diff as "estimated" - If the commit endpoint can be called without a valid plan ID, the entire dry-run can be bypassed 🔧 Implementation Approach - Structure tool execution as a three-phase pipeline: dry-run (compute diff only), approval (risk-based), and commit (execute), with each phase as a separate endpoint - Include before/after values, blast radius, rollback procedures, and a precondition state hash in the plan object, re-verifying preconditions at commit time to counter TOCTOU - Require both a valid plan ID and an approval token as mandatory parameters on the commit endpoint, making dry-run bypass structurally impossible - Set a TTL on each plan and force re-planning if expired, preventing execution based on stale diffs #AIAgents# #SoftwareArchitecture#