क्विकस्टार्ट: एक बेसिक एजेंट बनाएं और उसका परीक्षण करें

यह क्विकस्टार्ट आपको एक कस्टम इंजन एजेंट बनाने के माध्यम से मार्गदर्शन करता है जो आपके द्वारा भेजे गए किसी भी संदेश का जवाब देता है।

पूर्वावश्यकताएँ

• पायथन 3.9 या नया।

  • पायथन स्थापित करने के लिए, पर जाएं https://www.python.org/downloads/, और अपने ऑपरेटिंग सिस्टम के निर्देशों का पालन करें।
  • संस्करण को सत्यापित करने के लिए, टर्मिनल विंडो में टाइप करें python --version.

• अपनी पसंद का एक कोड संपादक। ये निर्देश Visual Studio कोड का उपयोग करें।

  यदि आप Visual Studio कोड का उपयोग करते हैं, तो Python एक्सटेंशन स्थापित करें

प्रोजेक्ट को प्रारंभ करें और SDK स्थापित करें

एक पायथन प्रोजेक्ट बनाएं और आवश्यक निर्भरताएं स्थापित करें।

1. एक टर्मिनल खोलें और एक नया फ़ोल्डर बनाएं

   mkdir echo
   cd echo
   

2. इस आदेश का उपयोग करके Visual Studio कोड का उपयोग कर फ़ोल्डर खोलें:

   code .
   

3. अपनी पसंद की विधि के साथ एक आभासी वातावरण बनाएं और इसे विजुअल स्टूडियो कोड या टर्मिनल में सक्रिय करें।

   Visual Studio कोड का उपयोग करते समय, आप स्थापित पायथन एक्सटेंशन के साथ इन चरणों का उपयोग कर सकते हैं।

   1. F1 दबाएँ, लिखें Python: Create environment, और Enter दबाएँ.

      1. वर्तमान कार्यक्षेत्र में वर्चुअल वातावरण बनाने के लिए .venv का चयन करें।

      2. वर्चुअल वातावरण बनाने के लिए एक पायथन इंस्टॉलेशन का चयन करें।

         मान इस तरह दिख सकता है:

         Python 1.13.6 ~\AppData\Local\Programs\Python\Python313\python.exe

4. एजेंट SDK स्थापित करें

   इस कमांड के साथ microsoft-agents-hosting-aiohttp पैकेज को स्थापित करने के लिए pip का उपयोग करें:

   pip install microsoft-agents-hosting-aiohttp
   

सर्वर अनुप्रयोग बनाएँ और आवश्यक लाइब्रेरीज़ आयात करें

1. नाम start_server.pyकी एक फ़ाइल बनाएँ, निम्न कोड की प्रतिलिपि बनाएँ, और उसमें चिपकाएँ:

   # start_server.py
   from os import environ
   from microsoft_agents.hosting.core import AgentApplication, AgentAuthConfiguration
   from microsoft_agents.hosting.aiohttp import (
      start_agent_process,
      jwt_authorization_middleware,
      CloudAdapter,
   )
   from aiohttp.web import Request, Response, Application, run_app
   
   
   def start_server(
      agent_application: AgentApplication, auth_configuration: AgentAuthConfiguration
   ):
      async def entry_point(req: Request) -> Response:
         agent: AgentApplication = req.app["agent_app"]
         adapter: CloudAdapter = req.app["adapter"]
         return await start_agent_process(
               req,
               agent,
               adapter,
         )
   
      APP = Application(middlewares=[jwt_authorization_middleware])
      APP.router.add_post("/api/messages", entry_point)
      APP.router.add_get("/api/messages", lambda _: Response(status=200))
      APP["agent_configuration"] = auth_configuration
      APP["agent_app"] = agent_application
      APP["adapter"] = agent_application.adapter
   
      try:
         run_app(APP, host="localhost", port=environ.get("PORT", 3978))
      except Exception as error:
         raise error
   

   यह कोड एक start_server फ़ंक्शन को परिभाषित करता है जिसे हम अगली फ़ाइल में उपयोग करेंगे।

2. एक ही निर्देशिका में, निम्न कोड के साथ नामित app.py एक फ़ाइल बनाएँ।

   # app.py
   from microsoft_agents.hosting.core import (
      AgentApplication,
      TurnState,
      TurnContext,
      MemoryStorage,
   )
   from microsoft_agents.hosting.aiohttp import CloudAdapter
   from start_server import start_server
   

AgentApplication के रूप में एजेंट की एक आवृत्ति बनाएँ

app.py में, AGENT_APP को AgentApplication का उदाहरण के रूप में बनाने के लिए निम्नलिखित कोड जोड़ें, और तीन घटनाओं का उत्तर देने के लिए तीन मार्ग लागू करें:

• बातचीत अपडेट
• संदेश /help
• कोई अन्य गतिविधि

AGENT_APP = AgentApplication[TurnState](
    storage=MemoryStorage(), adapter=CloudAdapter()
)

async def _help(context: TurnContext, _: TurnState):
    await context.send_activity(
        "Welcome to the Echo Agent sample 🚀. "
        "Type /help for help or send a message to see the echo feature in action."
    )

AGENT_APP.conversation_update("membersAdded")(_help)

AGENT_APP.message("/help")(_help)


@AGENT_APP.activity("message")
async def on_message(context: TurnContext, _):
    await context.send_activity(f"you said: {context.activity.text}")

लोकलहोस्ट में सुनने के लिए वेब सर्वर प्रारंभ करें:3978

app.py के बाद, वेब सर्वर शुरू करने के लिए start_server का उपयोग करें।

if __name__ == "__main__":
    try:
        start_server(AGENT_APP, None)
    except Exception as error:
        raise error

एजेंट को स्थानीय रूप से अनाम मोड में चलाएँ

अपने टर्मिनल से, यह कमांड चलाएं:

python app.py

टर्मिनल को निम्नलिखित वापस करना चाहिए:

======== Running on http://localhost:3978 ========
(Press CTRL+C to quit)

स्थानीय रूप से एजेंट का परीक्षण करें

1. किसी अन्य टर्मिनल से (एजेंट को चालू रखने के लिए) इस कमांड के साथ Microsoft 365 एजेंट खेल का मैदान स्थापित करें:

   npm install -g @microsoft/teams-app-test-tool
   

   नोट

   यह कमांड npm का उपयोग करता है क्योंकि Microsoft 365 Agents Playground पाइप का उपयोग करके उपलब्ध नहीं है।

   टर्मिनल को कुछ इस तरह वापस करना चाहिए:

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. इस कमांड का उपयोग करके अपने एजेंट के साथ इंटरैक्ट करने के लिए परीक्षण टूल चलाएँ:

   teamsapptester
   

   टर्मिनल को कुछ इस तरह वापस करना चाहिए:

   Telemetry: agents-playground-cli/serverStart {"cleanProperties":{"options":"{\"configFileOptions\":{\"path\":\"<REDACTED: user-file-path>\"},\"appConfig\":{},\"port\":56150,\"disableTelemetry\":false}"}}
   
   Telemetry: agents-playground-cli/cliStart {"cleanProperties":{"isExec":"false","argv":"<REDACTED: user-file-path>,<REDACTED: user-file-path>"}}
   
   Listening on 56150
   Microsoft 365 Agents Playground is being launched for you to debug the app: http://localhost:56150
   started web socket client
   started web socket client
   Waiting for connection of endpoint: http://127.0.0.1:3978/api/messages
   waiting for 1 resources: http://127.0.0.1:3978/api/messages
   wait-on(37568) complete
   Telemetry: agents-playground-server/getConfig {"cleanProperties":{"internalConfig":"{\"locale\":\"en-US\",\"localTimezone\":\"America/Los_Angeles\",\"channelId\":\"msteams\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"installationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"conversationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   

कमांड आपके डिफ़ॉल्ट ब्राउज़र को teamsapptester खोलता है और आपके एजेंट से जुड़ता है।

अब आप प्रतिध्वनि उत्तर देखने के लिए कोई भी संदेश भेज सकते हैं, या यह देखने के लिए संदेश /help भेज सकते हैं कि वह संदेश हैंडलर को _help कैसे रूट किया गया है।

अगले कदम

एजेंट SDK के साथ उपयोग करने के लिए Azure बॉट संसाधनों का प्रावधान करें

यह क्विकस्टार्ट आपको एक कस्टम इंजन एजेंट बनाने के माध्यम से मार्गदर्शन करता है जो आप इसे जो कुछ भी भेजते हैं उसका जवाब देते हैं।

पूर्वावश्यकताएँ

• Node.js v22 या नया

  • स्थापित करने Node.js nodejs.org पर जाएँ और अपने ऑपरेटिंग सिस्टम के लिए आने वाले अनुदेशों का पालन करें.
  • संस्करण को सत्यापित करने के लिए, टर्मिनल विंडो में टाइप करें node --version.

• अपनी पसंद का एक कोड संपादक। ये निर्देश Visual Studio कोड का उपयोग करें।

प्रोजेक्ट को प्रारंभ करें और SDK स्थापित करें

package.json बनाकर और आवश्यक निर्भरताएँ स्थापित करके node.js प्रोजेक्ट प्रारंभ करने के लिए उपयोग npm करें

1. एक टर्मिनल खोलें और एक नया फ़ोल्डर बनाएं

   mkdir echo
   cd echo
   

2. node.js प्रोजेक्ट प्रारंभ करें

   npm init -y
   

3. एजेंट SDK स्थापित करें

   npm install @microsoft/agents-hosting-express
   

4. इस आदेश का उपयोग करके Visual Studio कोड का उपयोग कर फ़ोल्डर खोलें:

   code .
   

आवश्यक लाइब्रेरीज़ आयात करें

फ़ाइल index.mjs बनाएं और अपने एप्लिकेशन कोड में निम्नलिखित एनपीएम पैकेज आयात करें:

• @microsoft/agents-hosting
• @microsoft/agents-hosting-express

// index.mjs
import { startServer } from '@microsoft/agents-hosting-express'
import { AgentApplication, MemoryStorage } from '@microsoft/agents-hosting'

EchoAgent को AgentApplication के रूप में लागू करें

मेंindex.mjs, EchoAgent का विस्तार बनाने के लिए निम्न कोड जोड़ें, और तीन घटनाओं का प्रतिसाद देने के लिए तीन मार्ग कार्यान्वित करें:

• बातचीत अपडेट
• संदेश /help
• कोई अन्य गतिविधि

class EchoAgent extends AgentApplication {
  constructor (storage) {
    super({ storage })

    this.onConversationUpdate('membersAdded', this._help)
    this.onMessage('/help', this._help)
    this.onActivity('message', this._echo)
  }

  _help = async context => 
    await context.sendActivity(`Welcome to the Echo Agent sample 🚀. 
      Type /help for help or send a message to see the echo feature in action.`)

  _echo = async (context, state) => {
    let counter= state.getValue('conversation.counter') || 0
    await context.sendActivity(`[${counter++}]You said: ${context.activity.text}`)
    state.setValue('conversation.counter', counter)
  }
}

लोकलहोस्ट में सुनने के लिए वेब सर्वर प्रारंभ करें:3978

index.mjs के अंत में, startServer का उपयोग करके वेब सर्वर शुरू करें, जो MemoryStorage को टर्न स्टेट स्टोरेज के रूप में इस्तेमाल करता है और एक्सप्रेस पर आधारित है।

startServer(new EchoAgent(new MemoryStorage()))

एजेंट को स्थानीय रूप से अनाम मोड में चलाएँ

अपने टर्मिनल से, यह कमांड चलाएं:

node index.mjs

टर्मिनल को यह वापस करना चाहिए:

Server listening to port 3978 on sdk 0.6.18 for appId undefined debug undefined

स्थानीय रूप से एजेंट का परीक्षण करें

1. किसी अन्य टर्मिनल से (एजेंट को चालू रखने के लिए) इस कमांड के साथ Microsoft 365 एजेंट खेल का मैदान स्थापित करें:

   npm install -D @microsoft/teams-app-test-tool
   

   टर्मिनल को कुछ इस तरह वापस करना चाहिए:

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. इस कमांड का उपयोग करके अपने एजेंट के साथ इंटरैक्ट करने के लिए परीक्षण टूल चलाएँ:

   node_modules/.bin/teamsapptester
   

   टर्मिनल को कुछ इस तरह वापस करना चाहिए:

   Telemetry: agents-playground-cli/serverStart {"cleanProperties":{"options":"{\"configFileOptions\":{\"path\":\"<REDACTED: user-file-path>\"},\"appConfig\":{},\"port\":56150,\"disableTelemetry\":false}"}}
   
   Telemetry: agents-playground-cli/cliStart {"cleanProperties":{"isExec":"false","argv":"<REDACTED: user-file-path>,<REDACTED: user-file-path>"}}
   
   Listening on 56150
   Microsoft 365 Agents Playground is being launched for you to debug the app: http://localhost:56150
   started web socket client
   started web socket client
   Waiting for connection of endpoint: http://127.0.0.1:3978/api/messages
   waiting for 1 resources: http://127.0.0.1:3978/api/messages
   wait-on(37568) complete
   Telemetry: agents-playground-server/getConfig {"cleanProperties":{"internalConfig":"{\"locale\":\"en-US\",\"localTimezone\":\"America/Los_Angeles\",\"channelId\":\"msteams\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"installationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"conversationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   

कमांड आपके डिफ़ॉल्ट ब्राउज़र को teamsapptester खोलता है और आपके एजेंट से जुड़ता है।

अब आप प्रतिध्वनि उत्तर देखने के लिए कोई भी संदेश भेज सकते हैं, या यह देखने के लिए संदेश /help भेज सकते हैं कि वह संदेश हैंडलर को _help कैसे रूट किया गया है।

अगले कदम

एजेंट SDK के साथ उपयोग करने के लिए Azure बॉट संसाधनों का प्रावधान करें

यह क्विकस्टार्ट आपको दिखाता है कि GitHub से क्विकस्टार्ट/एम्प्टी एजेंट नमूना कैसे डाउनलोड और चलाया जाए।

Microsoft 365 एजेंट SDK के साथ आरंभ करने के दो मुख्य तरीके हैं:

• क्लोन करें और GitHub पर उपलब्ध QuickStart/Empty Agent एजेंट नमूने को चलाएं

• Microsoft 365 एजेंट टूलकिट का उपयोग करें। एजेंट टूलकिट में विजुअल स्टूडियो और विजुअल स्टूडियो कोड के लिए दो अंतर्निहित टेम्पलेट हैं जो माइक्रोसॉफ्ट 365 एजेंट एसडीके का उपयोग करते हैं जो एक क्विकस्टार्ट/खाली एजेंट और एक मौसम एजेंट के साथ शुरू करने के लिए उपयोग करते हैं जो सिमेंटिक कर्नेल या लैंगचेन के साथ Azure फाउंड्री या OpenAI सेवाओं का उपयोग करता है।

पूर्वावश्यकताएँ

आरंभ करने से पहले आपको कुछ चीजों की आवश्यकता है। ये चरण .NET quickstart पर QuickStart/Empty एजेंट नमूने का उपयोग करते हैं, या आप किसी भी एजेंट SDK नमूने का उपयोग कर सकते हैं।

• .NET 8.0 SDK
• Visual Studio या Visual Studio कोड
• सी # में ASP.NET कोर और एसिंक्रोनस प्रोग्रामिंग का ज्ञान
• GitHub से नमूना डाउनलोड करें quickstart

समाधान खोलें

1. Visual Studio में समाधान फ़ाइल QuickStart.csproj खोलें।

2. प्रोजेक्ट चलाएँ.

इस बिंदु पर, आपका एजेंट पोर्ट 3978 का उपयोग करके स्थानीय रूप से चल रहा है।

स्थानीय रूप से अपने एजेंट का परीक्षण करें

1. यदि आपने पहले से नहीं किया है तो एजेंट खेल का मैदान स्थापित करें।

   winget install agentsplayground
   

2. Visual Studio या Visual Studio कोड में एजेंट प्रारंभ करें

3. टीम ऐप परीक्षक शुरू करें। कमांड प्रॉम्प्ट पर: agentsplayground

   • यह टूल एक वेब ब्राउज़र खोलता है जो Teams App Test टूल दिखाता है, जो आपके एजेंट को संदेश भेजने के लिए तैयार है।

4. पोर्ट 3978 पर आपका रनिंग एजेंट आपके ब्राउज़र में एजेंट प्लेग्राउंड से स्वचालित रूप से कनेक्ट हो जाना चाहिए और आपको स्थानीय रूप से चल रहे अपने एजेंट के साथ बातचीत करने में सक्षम होना चाहिए

एजेंट कैसे काम करता है?

एजेंट SDK के साथ, एक एजेंट AgentApplication और AgentApplicationOptions वर्गों का उपयोग करके बनाया गया है। यह नमूने की फ़ाइल में Program.cs बनाया गया है।

अपना एजेंट बनाएं

आप नमूने में देख सकते हैं कि जब एजेंट का निर्माण हो रहा है, तो AgentApplicationOptions लोड हो जाता है और आपका कस्टम एजेंट वर्ग MyAgent.cs, जो AgentApplication से विरासत लेता है।

// Add AgentApplicationOptions from appsettings section "AgentApplication".
builder.AddAgentApplicationOptions();

// Add the AgentApplication, which contains the logic for responding to
// user messages.
builder.AddAgent<MyAgent>();

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

builder.Services.AddSingleton<IStorage, MemoryStorage>();

शेष एजेंट एप्लिकेशन मानक .NET होस्टिंग पैटर्न का उपयोग करता है, और एक विशिष्ट समापन बिंदु पर संदेशों को स्वीकार करने के लिए मार्ग जोड़ता है। ये मार्ग एजेंट गतिविधि को स्वीकार करने के लिए IAgent इंटरफ़ेस का उपयोग करते हैं, और डेवलपर्स को AgentApplicationगतिविधि पेलोड के साथ काम करने के लिए ऑब्जेक्ट प्रदान करते हैं जो चैनल/क्लाइंट से इसे पास किया गया है। गतिविधियों और गतिविधियों के साथ काम करने के बारे में अधिक जानें

// This receives incoming messages from Azure Bot Service or other SDK Agents
var incomingRoute = app.MapPost("/api/messages", async (HttpRequest request, HttpResponse response, IAgentHttpAdapter adapter, IAgent agent, CancellationToken cancellationToken) =>
{
    await adapter.ProcessAsync(request, response, agent, cancellationToken);
});

किसी विधि में नया कस्टम तर्क जोड़ें

डेवलपर्स उस वर्ग में कस्टम MyAgent.cs तर्क जोड़ते हैं जो लागू करता है AgentApplication। यह वर्ग आपके कॉन्फ़िगरेशन से किसी भी विशिष्ट सेटिंग्स को कॉन्फ़िगर करने के लिए उपयोग करता AgentApplicationOptions है और Program.cs एजेंट एसडीके से ईवेंट श्रोताओं को पंजीकृत करता है, जो उस वर्ग में उपलब्ध AgentApplication है जो क्लाइंट से उन ईवेंट को ट्रिगर किए जाने पर आपकी संबंधित कस्टम विधि को संदर्भित करता है।

निम्न उदाहरण में, OnConversationUpdate विधि को ट्रिगर करता है WelcomeMessageAsync और OnActivity विधि को OnMessageAsyncट्रिगर करता है।

   public MyAgent(AgentApplicationOptions options) : base(options)
   {
      OnConversationUpdate(ConversationUpdateEvents.MembersAdded, WelcomeMessageAsync);
      OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
   }

उन घटनाओं को आपके में MyProgram.cs कॉन्फ़िगर किए गए समापन बिंदु के माध्यम से रूट किया जाता है और ऐसे कई ईवेंट हैं जिनका आप उपयोग कर सकते हैं। सबसे आम है OnActivity. SDK टूल द्वारा लागू किए जाने वाले इवेंट के बारे में ज़्यादा जानने के लिए, गतिविधियों के साथ काम करने और गतिविधि प्रोटोकॉल विनिर्देश के बारे में ज़्यादा जानकारी लें.

एक बार जब आपकी विधि ट्रिगर हो जाती है, उदाहरण OnMessageAsync के लिए बारी समाप्त करने के लिए, आप अपने कस्टम तर्क में टर्नकॉन्टेक्स्ट क्लास के उपलब्ध तरीकों और इंस्टेंस का उपयोग करके क्लाइंट को संदेश वापस भेजने के लिए जवाब देने के लिए चुन सकते हैं जो आपकी विधि में एक पैरामीटर होना चाहिए जैसा कि निम्न उदाहरण में दिखाया गया है:

private async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
{
   await turnContext.SendActivityAsync($"You said: {turnContext.Activity.Text}", cancellationToken: cancellationToken);
}

टिप

क्लाइंट पर लौटने के लिए उपलब्ध अन्य टर्नकॉन्टेक्स्ट विधियों की समीक्षा करें।

अब आप मूल बातें जानते हैं, अगले चरणों की जाँच करें और अपने एजेंट में कस्टम हैंडलर तर्क जोड़ने और विभिन्न घटनाओं को वापस भेजने के लिए काम करें।

अगले कदम

• गतिविधियों और गतिविधियों के साथ काम करने के बारे में अधिक जानें
• AgentApplication ईवेंट की समीक्षा करें जिनका आप क्लाइंट से जवाब दे सकते हैं
• टर्नकॉन्टेक्स्ट ईवेंट की समीक्षा करें जिन्हें आप क्लाइंट को वापस भेज सकते हैं
• एजेंट SDK के साथ उपयोग करने के लिए Azure बॉट संसाधनों का प्रावधान करें
• OAuth का उपयोग करने के लिए अपने .NET एजेंट को कॉन्फ़िगर करें

यदि आप पहले से ही Microsoft 365 एजेंट टूलकिट का उपयोग कर रहे हैं, तो एजेंट खेल का मैदान डिफ़ॉल्ट रूप से उपलब्ध है। यदि आप टूलकिट के साथ आरंभ करना चाहते हैं तो आप निम्न मार्गदर्शिकाओं में से एक का उपयोग कर सकते हैं:

• Microsoft 365 एजेंट टूलकिट का उपयोग करके विजुअल स्टूडियो में .NET एजेंट बनाएँ
• Microsoft 365 एजेंट टूलकिट के साथ Visual Studio कोड में JavaScript एजेंट बनाएँ