Everyone obsesses over the prompt. They fine-tune the greeting, tweak the tone, and worry whether the model sounds warm enough. That is a distraction. When an AI agent starts sending real emails to real users, the danger is not that it writes "Best regards" instead of "Cheers." The danger is that you cannot tell, with certainty, what happened between the agent's decision and the message landing in an inbox. I look at the boundary first. That is where production systems quietly die.
The Contract Is the Weak Point
AI demos are forgiving. A smooth conversation in a browser window hides a mess of assumptions. In production, the real vulnerability sits at the contract between three things: the agent's decision, the tool that executes the action, and the step that verifies the result. If that boundary is blurry, the system works beautifully right up until it does not. Then it fails silently, sends duplicates to an entire customer segment, or fires off messages at the wrong time with no clear record of why. The prompt might read like poetry. The architecture underneath can still be held together with string.
Stop Letting the Agent Write Freely
The most common mistake is giving the agent a blank page. Teams let it describe an email in raw text and then trust a downstream tool to parse intent from prose. That is brittle. An LLM might suggest a reasonable intent, but your infrastructure does not need creativity. It needs a contract. It needs specific fields that a machine can validate without ambiguity.
When an agent emits an email request, the output should carry exactly what the plumbing requires:
- Template version: Which version of the email body is being used, so you know what the user saw.
- Recipient scope: Who gets this, defined by user IDs or segment rules, not by natural language like "the user who just signed up."
- Trace ID: A unique identifier that follows this request from the agent through your executor, through the email provider, and into your logs.
- Time window: When this send is valid, so stale agent decisions do not trigger midnight emails hours later.
- Idempotency: A key that prevents the same logical send from firing twice if the agent retries or the network hiccups.
Raw text is a terrible API. It leaves room for ambiguity about urgency, audience, and action. Specific fields are machine-readable, auditable, and testable. They turn a vague instruction into a verifiable command.
Actions, Not Prose
Instead of handing the agent an open-ended writing task, restrict it to a menu of allowed actions. Think of it like an internal API with a fixed enum. The agent does not draft a subject line or wonder about salutations. It chooses an action such as send_review_request or send_retry_notice. That is the extent of its creative freedom.
A deterministic executor then takes that action key, pulls the correct template from version control, hydrates it with sanitized data, fills the recipient list from a verified source, and builds the final command. The agent decides what needs to happen. Boring, predictable code decides how it happens.
This separation makes the system easy to test. You can verify that a given input state reliably triggers send_retry_notice without running an LLM inference at all. Your unit tests become fast and deterministic because they check mapping logic, not model temperature. Your integration tests focus on whether the executor maps the action correctly to the email service, not whether the model was having a good day.
Build in Five Layers
A solid system does not emerge from a single prompt. It is built in layers, and each layer owns a single, clear responsibility.
1. The backend reduces the event to safe data.
Whether the trigger is a webhook, a database change, or a scheduled job, this layer sanitizes inputs, strips unexpected fields, and hands the agent only what it needs. If a webhook payload contains twenty fields but the agent only needs two, pass the two. No raw user text should reach the decision layer unchecked.
2. The agent picks an action from the fixed schema.
It sees the context, makes a judgment call, and outputs one of the predetermined action keys along with the required metadata. It does not draft prose. It does not guess at recipients. It returns a structured payload that the next layer can validate against a JSON schema.
3. टूल अनुमतियों (permissions) और आवश्यक फ़ील्ड्स को सत्यापित करता है।
क्या इस एजेंट कॉन्टेक्स्ट के पास इस उपयोगकर्ता के लिए send_review_request को ट्रिगर करने का अधिकार है? क्या प्राप्तकर्ता स्कोप (recipient scope) खाली नहीं है और अनुमत सीमाओं के भीतर है? क्या आपकी लॉग में idempotency key मौजूद और अद्वितीय (unique) है? क्या trace ID सही ढंग से बनी है? किसी भी ईमेल सेवा को छूने से पहले, यहीं पर स्पष्ट रूप से विफल (fail) हो जाएं।
4. ईमेल सेवा trace ID के साथ भेजने की प्रक्रिया को लॉग करती है।
आपके सिस्टम से निकलने वाले प्रत्येक संदेश में प्रोवाइडर के API के माध्यम से और आपके observability stack में वह trace identifier होना चाहिए। यदि कोई उपयोगकर्ता शिकायत करता है कि उसे दो प्रतियां मिली हैं, तो आप एक ID को क्वेरी करके ठीक से देख पाने में सक्षम होने चाहिए कि डुप्लीकेशन कहाँ से शुरू हुआ: एक रिट्राइड एजेंट कॉल (retried agent call), एक अस्थिर एक्जीक्यूटर (flaky executor), या एक गलत व्यवहार करने वाला कॉलबैक (misbehaving callback)।
5. एंड-टू-एंड टेस्ट सामग्री और प्रभाव के लिए वास्तविक इनबॉक्स की जाँच करता है।
रेंडर किए गए संदेश को वास्तविक मेलबॉक्स में खोलें। क्या विषय पंक्ति (subject line) सही ढंग से भरी गई है? क्या अनसब्सक्राइब लिंक काम कर रहा है? क्या प्राथमिक कॉल-टू-एक्शन (call-to-action) बटन पर क्लिक करने से सही उपयोगकर्ता स्थिति (user state) के साथ सही पेज खुलता है? एक सफल यूनिट टेस्ट का मतलब है कि कोड चला। केवल इनबॉक्स टेस्ट ही आपको बताता है कि ईमेल वास्तव में किसी इंसान के लिए काम कर रहा है।
अनुमान लगाने के बजाय साक्ष्य (Evidence)
जब इस पाइपलाइन में कोई टेस्ट विफल होता है, तो आपको साक्ष्य के चार विशिष्ट टुकड़ों की आवश्यकता होती है। इससे कम कुछ भी स्वीकार न करें।
- एजेंट का मूल निर्णय। उसने कौन सा एक्शन चुना, और पूरा इनपुट कॉन्टेक्स्ट क्या था?
- टूल से सामान्यीकृत (normalized) कमांड। टेम्पलेट, हाइड्रेशन लॉजिक और वैलिडेशन नियमों को लागू करने के बाद डिटरमिनिस्टिक एक्जीक्यूटर (deterministic executor) ने क्या बनाया?
- अलग किए गए (isolated) इनबॉक्स में संदेश। यह इस बात का लॉग नहीं है कि आपको क्या लगता है कि आपने क्या भेजा, बल्कि वास्तविक MIME संदेश, हेडर और सब कुछ है, जिसे एक समर्पित टेस्ट मेलबॉक्स में कैप्चर किया गया है।
- लिंक पर क्लिक करने के बाद अंतिम प्रभाव। परिणामी पेज स्टेट, डेटाबेस परिवर्तन, या बाहरी घटना जो यह साबित करती है कि ईमेल ने अपना उद्देश्य पूरा कर लिया है।
यदि एक भी टुकड़ा गायब है, तो आपकी टीम धारणाओं (assumptions) से उस कमी को पूरा कर देगी। वे अनुमान लगाएंगे। ऑटोमेशन में अनुमान लगाना महंगा पड़ता है। यह घंटों बर्बाद करता है, विश्वास को कम करता है, और हर घटना को एक फॉरेंसिक रहस्य में बदल देता है न कि एक...