AG-UI: एजेंट-यूज़र इंटरैक्शन के लिए एक हल्का प्रोटोकॉल

एजेंटिक ऐप्स को AG-UI की क्यों ज़रूरत है

कोड देखने से पहले, समझते हैं कि हमें नए प्रोटोकॉल की ज़रूरत पड़ी ही क्यों। बात आती है फंक्शन और एजेंट के मौलिक अंतर पर।

रिक्वेस्ट/रिस्पॉन्स की सीमा

पारंपरिक वेब डेवलपमेंट में इंटरैक्शन ट्रांज़ैक्शनल होते हैं। आप यूज़र प्रोफ़ाइल मांगते हैं, और सर्वर उसे भेज देता है। यह एक बार का लेन-देन है।

एजेंट्स, हालांकि, अप्रत्याशित होते हैं और समय लेते हैं। जब आप किसी एजेंट से कहते हैं कि "पता लगाओ कि टीममेट के मर्ज के बाद आपका CI पाइपलाइन अचानक क्यों फेल होने लगी," तो वह तुरंत कोई JSON ऑब्जेक्ट नहीं लौटाता। इसके बजाय, वह संभवतः यह करेगा:

1. GitHub से पिछली 50 कमिट लॉग्स खींचना (Action)।
2. ध्यान देना कि एक नई डिपेंडेंसी लॉकफाइल अपडेट किए बिना जोड़ दी गई (Observation)।
3. उस पैकेज वर्ज़न को ज्ञात CVEs के विरुद्ध क्रॉस-रेफरेंस करना (Reasoning)।
4. पूछना कि आप मर्ज को रोल बैक करना चाहते हैं या आगे पैच करना (Human-in-the-loop)।

मैं इसे आगे "इवेंट टाइप्स" अनुभाग में समझाऊंगा, लेकिन अभी के लिए बस इतना जान लें कि एक साधारण HTTP रिक्वेस्ट इस सब के पूरा होने का इंतज़ार करते हुए टाइम आउट हो जाएगा। आपको इन आंशिक अपडेट्स को स्ट्रीम करने का तरीका चाहिए ताकि यूज़र जमे हुए स्क्रीन को न देखता रहे।

एजेंट्स की विशिष्ट ज़रूरतें

एजेंट्स को टेक्स्ट से आगे बढ़कर द्वि-दिशात्मक सूचना प्रवाह चाहिए। उन्हें स्टेट को सिंक्रोनाइज़ करना होता है।

मान लें कोई एजेंट आपकी रिपोर्ट लिखने में मदद कर रहा है। यह सिर्फ चैट नहीं है; यह डॉक्युमेंट एडिट कर रहा है। आप और एजेंट, दोनों, एक साथ टाइप कर सकते हैं। AG-UI इसे "डॉक्युमेंट" को साझा स्टेट मानकर संभालता है, और कुशल अपडेट्स के जरिए आपकी स्क्रीन और एजेंट की मेमोरी को बिना एक-दूसरे के काम को ओवरराइट किए सिंक में रखता है।

एजेंट्स और UIs कैसे संवाद करते हैं

AG-UI पुराने Remote Procedure Call (RPC) मॉडल की जगह Event-Sourcing मॉडल लाता है। अंतिम उत्तर का इंतज़ार करने के बजाय, एजेंट लगातार ऐसे इवेंट्स की स्ट्रीम भेजता है जो बताते हैं कि वह क्या कर रहा है।

इवेंट स्ट्रीम

AG-UI स्ट्रीम को अपने एजेंट के दिमाग के न्यूज़ टिकर की तरह समझें। क्लाइंट एप्लिकेशन (आपका फ्रंटएंड) इस टिकर को सब्सक्राइब करता है और जो देखता है उसके आधार पर UI अपडेट करता है। यह अप्रोच लॉजिक को डिकपल करती है: आपके React फ्रंटएंड को यह जानने की ज़रूरत नहीं कि एजेंट कैसे सोच रहा है, बस यह जानना काफी है कि क्या दिखाना है।

AG-UI इंतज़ार के गैप से बचाता है। चित्र: लेखक।

कोर इवेंट टाइप्स

प्रोटोकॉल मानक इवेंट टाइप्स परिभाषित करता है जो लगभग हर इंटरैक्शन परिस्थिति को कवर करते हैं। यहां मुख्य वाले हैं जो आप देखेंगे:

1. TEXT_MESSAGE_*: ऐसे इवेंट्स जो जनरेटेड टेक्स्ट को टुकड़ों में स्ट्रीम करते हैं। इसमें आमतौर पर _START, _CONTENT (टोकन स्ट्रीम), और _END इवेंट्स होते हैं, जो मिलकर परिचित "टाइपिंग" इफ़ेक्ट बनाते हैं।

2. TOOL_CALL: संकेत देता है कि एजेंट कुछ करना चाहता है, जैसे मौसम देखना या डेटाबेस क्वेरी करना। महत्वपूर्ण बात यह है कि AG-UI टूल कॉल के arguments को भी स्ट्रीम कर सकता है, जिससे आपका UI एजेंट के "बोलना" खत्म करने से पहले ही फॉर्म्स को प्री-फिल कर सके।

3.  STATE_DELTA: सहयोग के लिए मुख्य काम करने वाला। हर बार पूरा डॉक्युमेंट फिर से भेजने के बजाय, एजेंट एक छोटा "डिफ" भेजता है (जैसे "इंडेक्स 5 पर 'hello' जोड़ो")।

4. INTERRUPT: सेफ्टी वॉल्व। अगर एजेंट किसी संवेदनशील एक्शन पर पहुंचता है (जैसे "Delete Database"), तो वह एक इंटरप्ट इवेंट एमिट करता है। फ्लो तब तक रुका रहता है जब तक यूज़र अप्रूवल इवेंट नहीं भेज देता।

मल्टीमोडैलिटी और थिंकिंग स्टेप्स

प्रोटोकॉल केवल टेक्स्ट तक सीमित नहीं है। यह मल्टीमोडैलिटी को संभालता है—यानी बातचीत के साथ छवियां, ऑडियो, और फाइल अटैचमेंट्स को स्ट्रीम करना। यह Thinking Steps को भी मानकीकृत करता है, जिसमें एजेंट के आंतरिक विचारों (reasoning traces) को अंतिम सार्वजनिक प्रतिक्रिया से अलग किया जाता है। आपने ChatGPT जैसे टूल्स में ऐसा पैटर्न देखा होगा, जहां प्रोग्रेस इंडीकेटर्स या इंटरमीडिएट स्टेप्स अंतिम उत्तर से अलग दिखते हैं। इससे आपको तय करने की सुविधा मिलती है कि यूज़र्स को निष्पादन प्रोग्रेस दिखानी है या केवल अंतिम परिणाम।

AG-UI के बिल्डिंग ब्लॉक्स

अब जब आप फ्लो समझ चुके हैं, तो देखते हैं वे विशेषताएं जो डेवलपर्स के लिए AG-UI को शक्तिशाली बनाती हैं।

जेनरेटिव UI

टेक्स्ट अच्छा है, लेकिन कई बार चार्ट बेहतर होता है। जेनरेटिव UI एजेंट को रनटाइम पर यह तय करने देता है कि उसे टेक्स्ट की जगह कोई UI कॉम्पोनेंट दिखाना चाहिए।

AG-UI इवेंट्स स्ट्रीम करता है; A2UI कॉम्पोनेंट्स परिभाषित करता है। चित्र: लेखक।

यहां एक भेद है जो अक्सर लोगों को उलझा देता है (मैं इसे फ्रेमवर्क सेक्शन में फिर छुऊंगा): AG-UI डिलीवरी मैकेनिज़्म (ट्रांसपोर्ट लेयर) है, और A2UI (Agent-to-User Interface) UI की परिभाषा (पेलोड) है। कोई एजेंट AG-UI के TOOL_CALL इवेंट का उपयोग A2UI पेलोड ट्रांसपोर्ट करने के लिए कर सकता है—एक घोषणात्मक JSON ट्री जो किसी UI कॉम्पोनेंट (जैसे "स्टॉक प्राइस कार्ड") का वर्णन करता है। आपका फ्रंटएंड इसे प्राप्त करता है और वास्तविक चार्ट रेंडर करता है।

JSON Patch के साथ साझा स्टेट

साझा स्टेट को संभालना पेचीदा होता है। यदि एजेंट हर सेकंड 5MB का विशाल कॉन्टेक्स्ट ऑब्जेक्ट भेजे, तो आपका ऐप रेंगने लगेगा।

AG-UI इसे JSON Patch (RFC 6902) से हल करता है। जैसा कि मैंने स्टेट सिंक्रोनाइज़ेशन के संदर्भ में पहले कहा था, जब एजेंट अपनी मेमोरी में कोई मान बदलता है, तो वह अंतर की गणना करता है और एक STATE_DELTA इवेंट भेजता है।

[
  {
    "op": "replace",
    "path": "/user/status",
    "value": "active"
  }
]संचालित द्वारा

क्लाइंट इस हल्के निर्देश को प्राप्त करता है और इसे अपनी लोकल स्टेट पर लागू कर देता है। यही दक्षता एजेंट्स के साथ रीयल-टाइम सहयोग को संभव बनाती है।

प्रोटोकॉल परिदृश्य में AG-UI

आपने MCP (Model Context Protocol) जैसे अन्य प्रोटोकॉल के बारे में सुना होगा। यह जानना महत्वपूर्ण है कि स्टैक में AG-UI कहाँ फिट बैठता है ताकि आप गलत काम के लिए गलत टूल न चुनें।

एजेंटिक स्टैक

मैं इसे संचार के त्रिकोण के रूप में देखना पसंद करता हूँ:

1. MCP (Agent ↔ Tools): यह एजेंट को बैकएंड दुनिया—डेटाबेस, GitHub रिपोज़, और आंतरिक APIs—से जोड़ता है। इसका लक्ष्य सूचना प्राप्त करना है।
2. A2A (Agent ↔ Agent): यह एजेंट्स को एक-दूसरे से बात करने देता है, कार्यों को सब-एजेंट्स को सौंपता है।
3. AG-UI (Agent ↔ User): यह "आखिरी मील" है। यह एजेंट की बुद्धिमत्ता को मानव यूज़र से जोड़ता है।

एजेंट्स को जोड़ने वाली प्रोटोकॉल त्रिमूर्ति। चित्र: लेखक।

AG-UI को परवाह नहीं कि एजेंट ने डेटा कैसे पाया (वह MCP का काम है, जैसा मैंने ऊपर बताया); इसे सिर्फ इस बात की परवाह है कि वह डेटा आपको कैसे दिखाया जाए।

AG-UI का इम्प्लीमेंटेशन

अब देखते हैं कि व्यवहार में यह कैसा दिखता है। डेवलपर्स आमतौर पर AG-UI से तीन तरीकों में से किसी एक से जुड़ते हैं: 1) Agentic Apps बनाना (फ्रंटएंड को एजेंट से कनेक्ट करना), 2) इंटीग्रेशन बनाना (किसी फ्रेमवर्क को संगत बनाना), या 3) क्लाइंट्स बनाना (नए फ्रंटएंड बनाना)। आपमें से अधिकांश पहले वर्ग में होंगे।

मैं कोड तुरंत समझाऊंगा, पर पहले इतना समझ लें कि आप आमतौर पर कच्चे प्रोटोकॉल हैंडलर्स खुद नहीं लिखेंगे। लाइब्रेरीज़ पैकेजिंग संभालती हैं। लेकिन फ्लो समझना डिबगिंग के लिए ज़रूरी है।

इवेंट चैनल स्थापित करना

अधिकांश इम्प्लीमेंटेशन Server-Sent Events (SSE) का उपयोग करते हैं क्योंकि वे सरल, फ़ायरवॉल-फ्रेंडली हैं, और सर्वर से क्लाइंट तक एक-तरफ़ा स्ट्रीमिंग के लिए उपयुक्त हैं। मैंने पहले इशारा किया था, लेकिन WebSockets की तुलना में इस प्रोटोकॉल को हल्का बनाने में SSE ही कुंजी है।

एक सामान्य सेटअप में (जैसे Microsoft Agent Framework या CopilotKit के साथ), आपका सर्वर एक एंडपॉइंट एक्सपोज़ करता है जो कनेक्शन को स्ट्रीम में अपग्रेड कर देता है।

सरल इवेंट सब्सक्रिप्शन

यहां एक वैचारिक उदाहरण है कि फ्रंटएंड क्लाइंट स्ट्रीम को कैसे सुनता है। ध्यान दें कि हम अलग-अलग इवेंट टाइप्स को हैंडल करके UI को कैसे अपडेट करते हैं।

// Connect to the AG-UI stream
const eventSource = new EventSource('/api/agent/stream');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'TEXT_MESSAGE_CONTENT':
      // Append text to the chat window
      updateChatLog(data.content);
      break;

    case 'TOOL_CALL_START':
      // Show a "Processing..." indicator or the specific tool UI
      showToolIndicator(data.tool_name);
      break;

    case 'STATE_DELTA':
      // Apply the JSON patch to our local state store
      applyPatch(localState, data.patch);
      break;

    case 'INTERRUPT':
      // Prompt the user for permission
      showApprovalModal(data.message);
      break;
  }
};संचालित द्वारा

यह पैटर्न एजेंट की आंतरिक लॉजिक की जटिलता को छिपा देता है। आपका फ्रंटएंड बस एजेंट द्वारा भेजे गए इवेंट्स का "प्लेयर" है।

इंटीग्रेशन और इकोसिस्टम सपोर्ट

आपको यह सब शून्य से बनाने की ज़रूरत नहीं है। इकोसिस्टम तेज़ी से परिपक्व हो रहा है, और बड़े प्लेटफॉर्म्स व फ्रेमवर्क्स इवेंट-ड्रिवन इंटरैक्शन पैटर्न्स पर तेजी से एकमत हो रहे हैं।

टूल्स का "गोल्डन ट्रायंगल"

Microsoft एजेंट डेवलपमेंट के लिए "गोल्डन ट्रायंगल" का वर्णन करता है:

1. DevUI: एजेंट की सोच प्रक्रिया को विज़ुअलाइज़ करने के लिए (डिबगिंग)।
2. OpenTelemetry: परफॉर्मेंस और लागत मापने के लिए।
3. AG-UI: यूज़र से कनेक्ट करने के लिए।

समर्थित फ्रेमवर्क्स

इकोसिस्टम तेज़ी से फैल रहा है। बड़े खिलाड़ियों से आगे भी, व्यापक स्तर पर सपोर्ट बढ़ रहा है:

1. Microsoft Agent Framework: ASP.NET Core (Microsoft.Agents.AI.Hosting.AGUI) के लिए नेटिव मिडलवेयर है।

2. CopilotKit: AG-UI के लिए "ब्राउज़र" की तरह काम करता है, एक पूर्ण React फ्रंटएंड देता है जो बॉक्स से बाहर इन इवेंट्स को रेंडर करना जानता है।

3. Python इकोसिस्टम: LangGraph, CrewAI, Mastra, Pydantic AI, Agno, और LlamaIndex जैसे फ्रेमवर्क्स को AG-UI एंडपॉइंट्स के रूप में एक्सपोज़ किया जा सकता है।

4. SDKs: जबकि TypeScript और Python प्रमुख हैं, Kotlin, Go, Dart, Java, और Rust के लिए SDKs सक्रिय हैं या विकास में हैं।

विश्वसनीयता, डिबगिंग, और सुरक्षा

AI और ब्राउज़र के बीच सीधी लाइन खोलना जोखिम लाता है। यहां बताया गया है कि अपने एप्लिकेशन को सुरक्षित कैसे रखें।

विश्वसनीय फ्रंटएंड सर्वर

किसी क्लाइंट को कभी भी आपके कच्चे एजेंट रनटाइम से सीधे कनेक्ट न होने दें। जैसा कि मैंने "एजेंटिक ऐप्स को AG-UI की क्यों ज़रूरत है" सेक्शन में ज़ोर देकर कहा था, हमेशा एक Trusted Frontend Server (BFF पैटर्न) का उपयोग करें। यह सर्वर गेटकीपर की तरह काम करता है। यह एजेंट को यूज़र का संदेश भेजने से पहले ऑथेंटिकेशन, रेट लिमिटिंग, और इनपुट वेलिडेशन जोड़ता है।

सुरक्षा विचार

प्रॉम्प्ट इंजेक्शन

दुर्भावनापूर्ण यूज़र s prompt injection attacks के ज़रिए आपके एजेंट के निर्देशों को ओवरराइड करने की कोशिश कर सकते हैं। जैसा कि मैंने पहले बताया, आपकी मिडलवेयर को इनपुट्स को सैनिटाइज़ करना चाहिए।

अनधिकृत टूल कॉल्स

सिर्फ इसलिए कि कोई एजेंट किसी फ़ाइल को हटा सकता है, इसका मतलब यह नहीं कि वर्तमान यूज़र को ऐसा करने की इजाज़त होनी चाहिए। आपका विश्वसनीय सर्वर यूज़र की परमिशन के आधार पर एजेंट के लिए उपलब्ध टूल्स को फ़िल्टर करे।

स्टेट सुरक्षा

क्योंकि स्टेट JSON पैचेज़ के माध्यम से साझा होता है, प्रोटोटाइप पॉल्यूशन से सावधान रहें। सुनिश्चित करें कि आपकी पैचिंग लाइब्रेरी __proto__ जैसी संरक्षित प्रॉपर्टीज़ को संशोधित करने से रोकती है।

Dojo के साथ डिबगिंग

यदि आपका एजेंट अजीब व्यवहार कर रहा है, तो AG-UI Dojo का उपयोग करें। यह एक टेस्ट सूट है जो आपको कच्ची इवेंट स्ट्रीम को विज़ुअलाइज़ करने देता है। यह आपको malformed JSON पैचेज़ या ऐसे टूल कॉल्स जैसी समस्याएं पकड़ने में मदद करता है जो फायर तो हो रहे हैं लेकिन परिणाम नहीं दे रहे।

निष्कर्ष

हमने AG-UI की आर्किटेक्चर, इवेंट टाइप्स, और इम्प्लीमेंटेशन पैटर्न्स को कवर किया है।

अब, मैं मानता हूँ कि औसत एकल डेवलपर या किसी छोटी कंपनी का व्यक्ति व्यावहारिक रूप से "AG-UI अपनाकर" अचानक "अपने फ्रंटएंड को बैकएंड से डिकपल" नहीं कर देगा। इसमें बड़े आर्किटेक्चरल निर्णय, कई टीमों की सहमति, और ऐसे संसाधन लगेंगे जो अधिकांश लोगों के पास नहीं होते।

लेकिन AG-UI को समझना तब भी मायने रखता है जब आप इसे लागू नहीं कर रहे हों। जब आप एजेंट फ्रेमवर्क्स का मूल्यांकन कर रहे हों या यह तय कर रहे हों कि इन-हाउस बनाना है या कोई प्लेटफॉर्म उपयोग करना है, तो यह जानना कि "अच्छा" एजेंट-UI संवाद कैसा दिखता है, आपको बेहतर निर्णय देता है। आप पहचान पाएंगे जब कोई टूल आपको भुरभुरा पैटर्न अपनाने पर मजबूर कर रहा हो।

अगर आप इन प्रणालियों को बनाने में और गहराई से उतरना चाहते हैं, तो हमारे Introduction to AI Agents और Building Scalable Agentic Systems कोर्सेज़ देखें और अपनी स्किल्स को अगले स्तर पर ले जाएं।