Agent 365 अवलोकनीयता अवधारणाएँ

यह आलेख एजेंट Agent 365 के पीछे के डेटा मॉडल की व्याख्या करता है - टेलीमेट्री एजेंट क्या उत्सर्जित करते हैं, कौन इसे उत्सर्जित कर सकता है, यह कहां उतरता है, और लागू होने वाली सीमाएं। ये अवधारणाएँ हर एकीकरण पथ पर लागू होती हैं: Microsoft OpenTelemetry Distro, Agent 365 SDK, और प्रत्यक्ष OTel।

नोट

वायर-स्तर के विवरण — प्रमाणीकरण में URL रूट्स, सीमा और ड्रॉप स्थितियों में HTTP त्रुटि कोड, और प्रति-रिक्वेस्ट आकार और रेट लिमिट्स — विशेष रूप से सीधे OTel पथ पर लागू होते हैं। SDK और डिस्ट्रो इन तकनीकी विवरणों को आपके लिए संभाल लेते हैं। इस आलेख का शेष भाग (शब्दावली, डेटा फ़्लो, पहचान मॉडल, स्कोप, ड्रॉप कंडीशन, डेटा कहाँ प्रदर्शित होता है) हर पथ पर लागू होता है।

अपना एकीकरण पथ चुनें

तीन पथ Agent 365 में एक ही स्पैन डेटा मॉडल का उत्सर्जन करते हैं। एक विकल्प चुनें:

  • Microsoft OpenTelemetry Distro - नए एकीकरण के लिए अनुशंसित। एकीकृत observability SDK Agent 365 , Microsoft फाउंड्री, Azure मॉनिटर, और अधिक भर में।
  • Agent 365 SDK (Observability SDK) - पूर्ववर्ती SDK। यह बिना किसी ब्रेकिंग परिवर्तन के काम करता रहेगा, लेकिन अब नए एकीकरण के लिए सुझाए गए पथ नहीं है; मौजूदा SDK उपयोगकर्ताओं के लिए माइग्रेशन मार्गदर्शन जल्द ही उपलब्ध होगा।
  • Direct OTel - कच्चा OTLP/HTTP पथ। इसे केवल तब उपयोग करें जब आपके पास पहले से OpenTelemetry पाइपलाइन हो, आपका एजेंट फ्रेमवर्क Agent 365 SDK का उपयोग नहीं कर सकता हो, या आपका एजेंट ऐसी भाषा में लिखा हो जिसे SDK अभी तक सपोर्ट नहीं करता (जैसे Java)।

आप चाहे जो पथ चुनें, नीचे वर्णित डेटा मॉडल, पहचान मॉडल, स्कोप, सीमाएं और डाउनस्ट्रीम सतहें सभी पर लागू होते हैं।

शब्दकोष

  • अनुप्रयोग ID(appId): वह अनुप्रयोग पहचानकर्ता जो तब जारी किया जाता है जब कोई Microsoft Entra ऐप या Microsoft Entra एजेंट ID एजेंट पहचान पंजीकृत की जाती है।
    • यह OAuth client_id के बराबर है, न कि Microsoft Entra ऑब्जेक्ट ID।
    • इन दस्तावेज़ों में, "एजेंट आईडी" ID "ब्लूप्रिंट ID" दोनों से तात्पर्य appId है।
  • वार्तालाप: एजेंट सहभागिता का एक तर्क थ्रेड, उदाहरण के लिए Teams चैट थ्रेड।
    • gen_ai.conversation.id द्वारा पहचाना जाता है।
    • एक रन के लिए प्राथमिक संयोजन कुंजी।
  • चैनल: वह surface जिसमें एजेंट चलता है: msteams, outlook, web, आदि।
  • चलाएँ: एक उपयोगकर्ता संदेश में, एक एजेंट उत्तर देता है। OTel के एक पेड़ के रूप में मॉडलिंग की गई एक traceId

यह कैसे काम करता है

Agent 365 और इसमें टेलीमेट्री किस तरह शामिल होती है, इसका अवलोकन देखने के लिए Microsoft Agent 365 का अवलोकन देखें।

आप टेलीमेट्री OpenTelemetry ट्रेस डेटा के रूप में भेजते हैं:

  • स्पैन का पेड़ रन का वर्णन करता है (एक उपयोगकर्ता संदेश अंदर, एक एजेंट उत्तर बाहर)।
  • प्रत्येक स्पैन एक एकल चरण का वर्णन करता है - शीर्ष-स्तरीय एजेंट आह्वान, एक LLM कॉल, एक टूल कॉल, या अंतिम उत्तर।

डेटा प्रवाह

   Your agent code

        |
        v

   +---------------+
   | OTel SDK or   |
   | raw HTTP      |
   +---------------+

        |
        v

   POST /traces  agent365.svc.cloud.microsoft

        |
        v

  +-------------------------------------+
  | Microsoft Defender                  |
  |   (CloudAppEvents table             |
  |    in advanced hunting)             |
  |                                     |
  | Microsoft Purview                   |
  |                                     |
  | Microsoft 365 admin center          |
  |   (agent inventory and              |
  |    security views)                  |
  +-------------------------------------+

पहचान मॉडल

एजेंट पहचान मॉडल (मानक Microsoft Entra ऐप पंजीकरण बनाम Microsoft Entra एजेंट ID एजेंट पहचान ब्लूप्रिंट, जिसमें AI टीम के साथी भी शामिल हैं) की पूरी जानकारी के लिए, Agent 365 विकास की शुरुआत करें देखें। आपके द्वारा चुना गया पहचान मॉडल यह निर्धारित करता है कि आप किस प्रमाणीकरण फ़्लो और समापन बिंदु का उपयोग करेंगे।

यदि आपके एजेंट के पास कोई Microsoft Entra पंजीकरण नहीं है, तो वह सीधे इन मार्गों का उपयोग नहीं कर सकता है। वैकल्पिक ID एट्रिब्यूट के माध्यम से एजेंट की पहचान करें (एट्रिब्यूट संदर्भ देखें) और उपयुक्त इनग्रेशन पथ के बारे में Agent 365 टीम से संपर्क करें।

प्रमाणीकरण

प्रमाणीकरण इस बात पर विभाजित होता है कि आपकी सेवा स्वयं प्रमाणीकरण करती है या किसी उपयोगकर्ता की ओर से करती है। शाखा OAuth फ़्लो, अनुमति देने वाले टोकन दावे और URL मार्ग को निर्धारित करती है।

  • सेवा स्वयं को प्रमाणित करती है: कोई साइन-इन उपयोगकर्ता नहीं - स्वायत्त, अनुसूचित, या ईवेंट-संचालित।

    • OAuth फ़्लो: सेवा-से-सेवा (S2S) क्लाइंट क्रेडेंशियल्स।
    • टोकन दावा: roles
    • URL रूट/observabilityService/...

  • सेवा उपयोगकर्ता की ओर से प्रमाणित करती है: AI साथियों के लिए, या एजेंट के अपने उपयोगकर्ता खाते के लिए।

    • OAuth फ़्लो: की ओर से (OBO).
    • टोकन दावा: scp
    • URL रूट/observability/...

एक ही एजेंट ऐप दोनों फ़्लो में भाग ले सकता है, जैसे कि एक AI टीम का साथी जो रात में स्वायत्त सारांश पास भी चलाता है। अधिक जानकारी के लिए, ऑटोनॉमस ऐप OAuth फ़्लो और On-Behalf-Of फ़्लोदेखें।

पहचान मॉडल और फ़्लो के प्रत्येक संयोजन के लिए टोकन प्राप्त करने की पूरी प्रक्रिया देखने के लिए एकीकरण गाइड में प्रमाणीकरण रेसिपी देखें।

एजेंट की पहचान URL से बंधी हुई है

URL में {agentId} कॉलिंग अनुप्रयोग के appId के बराबर होना चाहिए (जो आपके टोकन में appid या azp क्लेम है)। मिलान न होने पर 403 Forbidden लौटाया जाता है। ब्लूप्रिंट से प्राप्त पहचान के लिए, {agentId} वास्तव में एजेंट पहचान appId होता है, न कि ब्लूप्रिंट appId।

इसके अतिरिक्त, आपको हर span में gen_ai.agent.id को उसी appId पर सेट करना आवश्यक है; सर्वर इन-पेलोड एजेंट पहचान को प्रमाणित एजेंट के खिलाफ सत्यापित करता है और असमानताओं को अस्वीकार करता है। यह चरण गलती से कई एजेंटों से एक अनुरोध में स्पैन को मिलाता है।

स्कोप (प्रत्यायोजित) या ऐप रोल (अनुप्रयोग) वह नामित अनुमति है जिसे Microsoft Entra पहुँच टोकन में जोड़ता है। Agent 365 टेलीमेट्री के लिए, अनुमति Agent365.Observability.OtelWrite Agent 365 ऑब्जर्वेबिलिटी संसाधन (ऑडियंस 9b975845-388f-4429-889e-eab1ef63949c) पर है।

एक ही अनुमति नाम को दोनों प्रकार के रूप में पंजीकृत किया गया है:

  • स्वायत्त (S2S / क्लाइंट-क्रेडेंशियल्स) फ़्लो के लिए ऐप भूमिका । यहroles क्लेम में आता है। <resource>/.default द्वारा चयनित।
  • प्रत्यायोजित कार्यक्षेत्र OBO फ़्लो के लिए। यहscp क्लेम में आता है। द्वारा चयनित<resource>/Agent365.Observability.OtelWrite (या <resource>/.default)

Agent 365 एक रीड-साइड अनुमति भी प्रदान करता है, Agent365.Observability.OtelRead जिसका उपयोग वे ऑपरेटर करते हैं जो Agent 365 टेलीमेट्री को क्वेरी करते हैं। अधिकांश सहभागी को इसकी आवश्यकता नहीं होती है - ये दस्तावेज़ केवल अंतर्ग्रहण को कवर करते हैं।

अपने अनुप्रयोग में अनुमति जोड़ना

  • एक मानक Microsoft Entra ऐप पंजीकरण के लिए: Azure पोर्टल में, एजेंट की ऐप पंजीकरण पर API अनुमतियों के अंतर्गत Agent365.Observability.OtelWrite (S2S के लिए ऐप रोल, प्रत्यायोजित के लिए स्कोप) जोड़ें।
  • एक ब्लूप्रिंट के लिए: Microsoft Entra एजेंट ID एजेंट आइडेंटिटी ब्लूप्रिंट से बनाए गए एजेंट उस ब्लूप्रिंट पर परिभाषित OAuth अनुमतियाँ स्वचालित रूप से इनहेरिट करते हैं, इसलिए टैनेंट एडमिन को अनुमतियाँ केवल एक बार पूर्व-प्रावधान करनी होती हैं। उस ब्लूप्रिंट से निर्मित प्रत्येक एजेंट इंस्टेंस को ये अनुमतियाँ स्वचालित रूप से प्राप्त होती हैं। एजेंट पहचान ब्लूप्रिंट के लिए इनहेरिट करने योग्य अनुमतियाँ कॉन्फ़िगर करें देखें।

टोकन में भूमिका/ कार्यक्षेत्र जोड़ने से पहले, ग्राहक के टैनेंट में मौजूद टैनेंट व्यवस्थापक को सहमति देनी होगी। Microsoft 365 संसाधनों तक एजेंटों को पहुँच प्रदान करें देखें.

यदि सहमति नहीं दी जाती है, तो टोकन प्राप्त करना AADSTS65001 ("उपयोगकर्ता या व्यवस्थापक ने सहमति नहीं दी है") के साथ विफल हो जाता है, या टोकनroles / scp दावे के बिना जारी किया जाता है और इनजेशन समाप्ति बिंदु 403 के साथ अनुरोध को अस्वीकार कर देता है।

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

सीमाएं और ड्रॉप शर्तें

इन सीमाओं की पूर्व जानकारी एकीकरण के दौरान अप्रत्याशित समस्याओं को रोकती है — अधिकांश सीमाएं बिना सूचना के लागू हो जाती हैं (API अनुरोध स्वीकार कर लेता है, लेकिन डेटा कभी डाउनस्ट्रीम में दिखाई नहीं देता)।

वायर-स्तर सीमाएँ:

  • api-version=1 प्रत्येक अनुरोध में आवश्यक है।
  • अधिकतम अनुरोध बॉडी आकार 1 MB है। बड़े अनुरोध मिलते हैं 413 Payload Too Large।
  • दोनों रूट में अलग-अलग दर सीमाएँ हैं। पर, 429सम्मान Retry-After (दूसरे पर1 सेट) और जिटर के साथ वापस आ जाएं।

त्रुटि प्रतिसाद

  • 403 Forbidden--टोकन में आवश्यक ऐप भूमिका/कार्यक्षेत्र नहीं है, या {agentId} URL में आपके टोकन के appid / azp से मेल नहीं खाता है।
  • 413 Payload Too Large--बॉडी 1 MB से अधिक है।
  • 429 Too Many Requests--दर सीमा हिट; हॉनर Retry-After: 1 और जिटर के साथ वापस जाएं।

ड्रॉप कंडीशन्स (HTTP द्वारा अनुरोध स्वीकार कर लिया गया, लेकिन डेटा डाउनस्ट्रीम में नहीं दिखता):

# स्थिति व्यवहार
1 स्पैन gen_ai.operation.name गायब है या {invoke_agent, execute_tool, chat, output_messages} में नहीं है प्रति-स्पैन ड्रॉप। partialSuccess.rejectedSpans + errorMessage में सामने आया।
2 ग्राहक टैनेंट के किसी भी उपयोगकर्ता को Microsoft 365 E7 या Microsoft Agent 365 लाइसेंस असाइन नहीं किया गया है। टैनेंट में कम से कम एक उपयोगकर्ता के पास लाइसेंस असाइन किया गया होना चाहिए (टैनेंट में SKU का मौजूद होना पर्याप्त नहीं है - असाइनमेंट डिफेंडर बैकएंड वर्कफ़्लो को शुरू करता है)। लाइसेंस प्राप्त उपयोगकर्ता वही व्यक्ति होना जरूरी नहीं है जो एजेंट को कॉल कर रहा है। पूरा अनुरोध चुपचाप छोड़ दिया गया। `200 { "partialSuccess": null }`रिटर्न्स

200 ओके अंतर्ग्रहण का प्रमाण नहीं है। डेटा भूमि की पुष्टि करने के लिए सत्यापन फ़्लो का उपयोग करें।

आपका डेटा कहां दिखाई देता है

एक बार स्वीकार किए जाने पर, आपके स्पैन तीन ग्राहक-उन्मुख अनुभवों में दिखाई देते हैं। तीनों रन के रूट में एक वैध invoke_agent अवधि पर निर्भर करते हैं। केवल chat / execute_tool / output_messages स्पैन वाले रन को Defender advanced hunting ( CloudAppEvents तालिका) में क्वेरी किया जा सकता है, लेकिन यह अन्य सभी surface पर अदृश्य है।

Microsoft Defender एजेंट गतिविधि (invoke_agent, execute_tool, chat) एजेंट-गतिविधि दृश्य में दिखाई देती है। टेनेंट प्रशासक और सुरक्षा विश्लेषक व्यक्तिगत रन, टूल्स और इनफेरेंस कॉल्स में गहराई से जांच कर सकते हैं। एजेंट-गतिविधि दृश्य invoke_agent स्पैन पर आधारित होते हैं; इसके अभाव में, रन वहाँ दिखाई नहीं देता, हालांकि चाइल्ड स्पैन अभी भी एडवांस्ड हंटिंग के माध्यम से क्वेरी किए जा सकते हैं। एडवांस हंटिंग दृश्य - CloudAppEvents - हर ऑपरेशन स्वीकार करता है: ActionType ऑपरेशन को दर्शाता है (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) और प्रत्येक स्पैन के फ़ील्ड RawEventData के अंदर होते हैं। ग्राहक-दृश्यमान फ़ील्ड नाम सीधे उन स्पैन एट्रिब्यूट से मेल खाते हैं जिन्हें आपने भेजा है: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id, और इसी तरह। पूर्ण मैपिंग के लिए एट्रिब्यूट संदर्भ देखें।

Microsoft 365 व्यवस्थापन केंद्र। एजेंट गतिविधि एजेंट-इन्वेंट्री और सुरक्षा दृश्य में भी दिखाई देती है, जिनका उपयोग टैनेंट व्यवस्थापक अपने टेनेंट में एजेंट्स को नियंत्रित करने के लिए करते हैं। एडमिन सेंटर केवल invoke_agent पंक्तियाँ ही इनजेस्ट करता है: जिन एजेंट्स के पासinvoke_agent टेलीमेट्री नहीं है, वे इन्वेंटरी में दिखाई नहीं देते, और जो रन केवल chat / execute_tool / output_messages उत्सर्जित करते हैं, वे यहां अदृश्य होते हैं। जिन एट्रिब्यूट को व्यवस्थापक केंद्र पढ़ता है (एजेंट ID, एजेंट नाम, ब्लूप्रिंट ID, कॉलर पहचान, वार्तालाप ID, चैनल, त्रुटि स्थिति), वे सभी invoke_agentस्पैन से प्राप्त होती हैं।

Microsoft Purview एजेंट गतिविधि Microsoft Purview में अनुपालन व्यवस्थापकों को भी दिखाई देती है, जहाँ वे एजेंट रन पर डेटा-प्रसंस्करण और नीति नियम (डेटा लॉस प्रिवेंशन, रिटेंशन, संचार अनुपालन, आदि) को कॉन्फ़िगर कर सकते हैं। वे एट्रिब्यूट जिन पर Purview नीतियाँ आधारित होती हैं (एजेंट ID / ब्लूप्रिंट ID, कॉलर पहचान, वार्तालाप / चैनल, अनुरोध और प्रत्युत्तर संदेश), सभी invoke_agentस्पैन और उसके वंशजों से आती हैं।

अगले चरण

  • एट्रिब्यूट संदर्भ - हर एट्रिब्यूट के लिए विनिर्देश, आवश्यकताएँ, और मूल्य-चयन मार्गदर्शन।
  • समस्या निवारण - अंतर्ग्रहण, सामान्य नुकसान और त्रुटि प्रतिक्रियाओं की पुष्टि करना।
  • पिछली बार को अपडेट किया गया