सहायक के साथ डिज़ाइन

विनिर्देश क्षेत्र में API डिज़ाइन किए जाते हैं। इसमें AI चैट के साथ मौजूदा दस्तावेज़ और उसका पूर्वावलोकन दिखता है। आप सामान्य भाषा में अपनी ज़रूरत बता सकते हैं और वास्तव में लागू होने वाले बदलावों पर पूरा नियंत्रण रख सकते हैं।

अनुमोदन का चक्र

मॉडल दस्तावेज़ को सीधे नहीं बदलता। प्रक्रिया जानबूझकर स्पष्ट चरणों में बाँटी गई है:

you describe an intent
        |
the model reads current state and proposes operations
        |
the host validates the proposal
        |
you review a patch card and Apply or Reject
        |
the change is merged into the document

यह अलगाव डिज़ाइन का मुख्य निर्णय है। मॉडल उद्देश्य समझकर संरचना सुझाता है; होस्ट ऐप्लिकेशन निश्चित नियमों के अनुसार हर कार्रवाई जाँचता है; आप हर बदलाव की मंज़ूरी देते हैं। आपकी पुष्टि के बिना किसी प्रस्ताव को लागू हुआ नहीं माना जाता।

बदलाव के कार्ड

बदलाव का कार्ड उसका सार और सटीक कार्रवाइयाँ दिखाता है, जैसे नया पथ जोड़ना:

{
  "type": "patch",
  "summary": "Add GET /products endpoint",
  "ops": [
    { "op": "add", "path": ["paths", "/products"], "value": { "get": {} } }
  ],
  "affects": { "paths": ["/paths/~1products"], "resources": ["Product"] }
}

पथ के खंड ऐरे के तत्व होते हैं, JSON Pointer स्ट्रिंग नहीं। नया पथ जोड़ने का लक्ष्य ["paths", "/products"] होता है और उसके पैरेंट कंटेनर अपने आप बन जाते हैं।

मौजूदा कार्रवाइयों में छोटे, सटीक बदलाव

किसी मौजूदा कार्रवाई को बदलते समय सहायक पूरी कार्रवाई दोबारा नहीं भेजता, क्योंकि इससे वे फ़ील्ड मिट जाएँगे जिन्हें उसने दोबारा नहीं भेजा। इसके बजाय वह छोटी कार्रवाइयाँ बनाता है, जो केवल ज़रूरी हिस्से को बदलती हैं, भले ही वह संरचना में कई स्तर अंदर हो:

एक क्वेरी पैरामीटर जोड़ना:

{ "op": "add", "path": ["paths", "/products", "get", "parameters", "-"], "value": {} }

प्रतिक्रिया का स्कीमा बढ़ाना:

{ "op": "replace", "path": ["paths", "/products", "get", "responses", "200", "content", "application/json", "schema", "properties", "total"], "value": { "type": "integer" } }

एक फ़ील्ड बदलना:

{ "op": "replace", "path": ["paths", "/products", "get", "summary"], "value": "..." }

पूरे ऐरे को दोबारा भेजने के बजाय "-" टोकन से नए तत्व जोड़े जाते हैं। पैरामीटर की पहचान (in, name) जोड़ी से होती है, इसलिए मौजूदा पैरामीटर दोहराया नहीं जाता। ऐप्लिकेशन प्रस्तावित मान को मौजूदा कार्रवाई में मिलाता है और बाकी सभी हिस्से सुरक्षित रखता है।

इसी वजह से बार-बार सुधार भरोसेमंद रहते हैं: “अब limit पैरामीटर जोड़ो” या “नाम अनिवार्य करो” कहने पर केवल वही फ़ील्ड बदलता है और बाकी कार्रवाई जस की तस रहती है।

पढ़ने वाले टूल हर प्रस्ताव का आधार हैं

उत्तर देने से पहले मॉडल अनुमान लगाने के बजाय केवल-पढ़ने वाले टूल से मौजूदा स्थिति की सटीक जानकारी ले सकता है:

spec.overview: शीर्षक, संस्करण, प्रोटोकॉल, गिनतियाँ, टैग, सर्वर और सुरक्षा;
spec.listOperations: सार और टैग सहित हर कार्रवाई METHOD /path के रूप में;
spec.presentOperations: सभी कार्रवाइयों की केवल-पढ़ने योग्य सूची का कार्ड;
spec.getOperation: एक कार्रवाई की पूरी परिभाषा और उससे संदर्भित स्कीमा;
spec.getSchema: एक कंपोनेंट स्कीमा, जिसमें अनिवार्य फ़ील्ड और विवरण शामिल हैं।

अगर कार्रवाई की पूरी संरचना दिखाई न दे, तो मॉडल को उसे बदलने से पहले पढ़ना चाहिए।

बड़े अनुरोध चरणों में पूरे होते हैं

“एक ई-कॉमर्स API बनाओ” जैसे बड़े अनुरोध पर सहायक सब कुछ एक साथ नहीं देता:

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

दायरा स्पष्ट होते ही सहायक बनाए जाने वाले एंडपॉइंट का plan भी देता है, ताकि बदलाव आने से पहले आप काम की रूपरेखा देख सकें।

लक्ष्य से भटकने से बचाव

काम को अनुरोध के अनुरूप रखने के लिए ऐप्लिकेशन कुछ नियम लागू करता है:

मौजूदा दस्तावेज़ ही स्थिति का प्रामाणिक स्रोत है; दस्तावेज़ में न होने पर मॉडल यह नहीं मानता कि पिछला बदलाव लागू हो चुका है;
केंद्रित मोड में केवल सक्रिय लक्ष्य और स्पष्ट रूप से संदर्भित कंपोनेंट स्कीमा बदले जाते हैं; अन्य एंडपॉइंट में अपने आप बदलाव नहीं होते;
किसी दूसरे METHOD /path का स्पष्ट उल्लेख जानबूझकर किया गया कार्य-परिवर्तन माना जाता है;
लागू और अस्वीकृत प्रस्ताव इतिहास में दर्ज रहते हैं; पहले से मौजूद बदलाव दोबारा नहीं सुझाया जाता।

ज़रूरी जानकारी दिखाई न देने पर सहायक उसे गढ़ने के बजाय सटीक सवाल पूछता है।

अन्य कार्ड

हर उत्तर बदलाव का प्रस्ताव नहीं होता:

प्रश्न कार्ड विकल्पों में से चुनाव करने को कहते हैं;
सत्यापन कार्ड गुणवत्ता जाँच के परिणाम सफल, चेतावनी और त्रुटि स्थितियों के साथ दिखाते हैं;
कार्रवाई कार्ड ठोस अगले कदम देते हैं, जैसे परिदृश्य चलाना या कार्यक्षेत्र खोलना;
डेटा-टेबल कार्ड एंडपॉइंट या स्कीमा के लिए ठोस नमूना या परीक्षण पंक्तियाँ दिखाते हैं।

संबंधित: अनुरोध कार्यक्षेत्र, परिदृश्य परीक्षण, AI और मॉडल।

A2A एजेंट

x-protocol: a2a से संस्करणयुक्त एजेंट संदेश, टास्क कार्रवाइयाँ और SSE अपडेट डिज़ाइन तथा डीबग करें। एक्सटेंशन फ़ील्ड और JSON-RPC, REST तथा डेस्कटॉप gRPC बाइंडिंग के लिए A2A एजेंट देखें।

अनुमोदन का चक्र​

बदलाव के कार्ड​

मौजूदा कार्रवाइयों में छोटे, सटीक बदलाव​

पढ़ने वाले टूल हर प्रस्ताव का आधार हैं​

बड़े अनुरोध चरणों में पूरे होते हैं​

लक्ष्य से भटकने से बचाव​

अन्य कार्ड​

A2A एजेंट​