Γρήγορη εκκίνηση: Δημιουργία και δοκιμή βασικού παράγοντα

Αυτός ο οδηγός γρήγορης εκκίνησης σας καθοδηγεί στη δημιουργία ενός προσαρμοσμένου παράγοντα που απαντά με το ίδιο μήνυμα που του στέλνετε.

Προαπαιτούμενα στοιχεία

• Python 3.9 ή νεότερη έκδοση.

  • Για να εγκαταστήσετε την Python, μεταβείτε στο https://www.python.org/downloads/ και ακολουθήστε τις οδηγίες για το λειτουργικό σας σύστημα.
  • Για να επαληθεύσετε την έκδοση, στο τερματικό πληκτρολογήστε python --version.

• Ένας επεξεργαστής κώδικα της επιλογής σας. Αυτές οι οδηγίες χρησιμοποιούν Visual Studio Code.

  Εάν χρησιμοποιείτε το Visual Studio Code, εγκαταστήστε την επέκταση Python

Αρχικοποιήστε το έργο και εγκαταστήστε το SDK

Δημιουργήστε ένα έργο Python και εγκαταστήστε τις απαιτούμενες εξαρτήσεις.

1. Ανοίξτε ένα τερματικό και δημιουργήστε έναν νέο φάκελο

   mkdir echo
   cd echo
   

2. Ανοίξτε το φάκελο στο Visual Studio Code χρησιμοποιώντας αυτήν την εντολή:

   code .
   

3. Δημιουργήστε ένα εικονικό περιβάλλον με τη μέθοδο της επιλογής σας και ενεργοποιήστε το είτε μέσω του Visual Studio Code είτε σε ένα τερματικό.

   Όταν χρησιμοποιείτε το Visual Studio Code, μπορείτε να ακολουθήσετε αυτά τα βήματα με εγκατεστημένη την επέκταση Python.

   1. Πατήστε F1, πληκτρολογήστε Python: Create environment και πατήστε Enter.

      1. Επιλέξτε Venv για να δημιουργήσετε ένα εικονικό περιβάλλον .venv στον τρέχοντα χώρο εργασίας.

      2. Επιλέξτε μια εγκατάσταση Python για να δημιουργήσετε το εικονικό περιβάλλον.

         Η τιμή έχει την εξής μορφή:

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

4. Εγκαταστήστε το SDK παραγόντων

   Χρησιμοποιήστε το pip για να εγκαταστήσετε το πακέτο microsoft-agents-hosting-aiohttp με αυτήν την εντολή:

   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}")

Ξεκινήστε τον διακομιστή web να ακούει στο localhost:3978

Στο τέλος του app.py, ξεκινήστε τον διακομιστή web χρησιμοποιώντας 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 Agents Playground με αυτήν την εντολή:

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

   Σημείωμα

   Αυτή η εντολή χρησιμοποιεί npm, καθώς το Microsoft 365 Agents Playground δεν είναι διαθέσιμο μέσω pip.

   Το τερματικό θα πρέπει να εμφανίσει κάτι όπως:

   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 ανοίγει το προεπιλεγμένο πρόγραμμα περιήγησης και συνδέεται με τον παράγοντα σας.

Τώρα μπορείτε να στείλετε οποιοδήποτε μήνυμα για να δείτε την απάντηση τύπου echo, ή να στείλετε το μήνυμα /help για να δείτε πώς δρομολογείται αυτό το μήνυμα στον χειριστή _help.

Αυτός ο οδηγός γρήγορης εκκίνησης σας καθοδηγεί στη δημιουργία ενός προσαρμοσμένου παράγοντα που απαντά με το ίδιο μήνυμα που του στέλνετε.

Προαπαιτούμενα στοιχεία

• Node.js v22 ή νεότερο

  • Για να εγκαταστήσετε το Node.js, μεταβείτε στο nodejs.org και ακολουθήστε τις οδηγίες για το λειτουργικό σας σύστημα.
  • Για να επαληθεύσετε την έκδοση, στο τερματικό πληκτρολογήστε node --version.

• Ένας επεξεργαστής κώδικα της επιλογής σας. Αυτές οι οδηγίες χρησιμοποιούν Visual Studio Code.

Αρχικοποιήστε το έργο και εγκαταστήστε το SDK

Χρησιμοποιήστε npm για να αρχικοποιήσετε ένα έργο node.js, δημιουργώντας ένα package.json και εγκαθιστώντας τις απαιτούμενες εξαρτήσεις

1. Ανοίξτε ένα τερματικό και δημιουργήστε έναν νέο φάκελο

   mkdir echo
   cd echo
   

2. Αρχικοποιήστε το έργο node.js

   npm init -y
   

3. Εγκαταστήστε το SDK παραγόντων

   npm install @microsoft/agents-hosting-express
   

4. Ανοίξτε το φάκελο στο Visual Studio Code με αυτήν την εντολή:

   code .
   

Εισάγετε τις απαιτούμενες βιβλιοθήκες

Δημιουργήστε το αρχείο index.mjs και εισάγετε τα παρακάτω πακέτα NPM στον κώδικα της εφαρμογής σας:

• @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, επεκτείνοντας το AgentApplication, και να υλοποιήσετε τρεις διαδρομές για να ανταποκριθείτε σε τρία συμβάντα:

• Ενημέρωση συνομιλίας
• το μήνυμα /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)
  }
}

Ξεκινήστε τον διακομιστή web να ακούει στο localhost:3978

Στο τέλος του index.mjs, ξεκινήστε τον διακομιστή web χρησιμοποιώντας τη συνάρτηση startServer, η οποία βασίζεται στο express και χρησιμοποιεί το 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 Agents Playground με αυτήν την εντολή:

   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 ανοίγει το προεπιλεγμένο πρόγραμμα περιήγησης και συνδέεται με τον παράγοντα σας.

Τώρα μπορείτε να στείλετε οποιοδήποτε μήνυμα για να δείτε την απάντηση τύπου echo, ή να στείλετε το μήνυμα /help για να δείτε πώς δρομολογείται αυτό το μήνυμα στον χειριστή _help.

Αυτός ο οδηγός γρήγορης εκκίνησης σας καθοδηγεί στη δημιουργία ενός προσαρμοσμένου παράγοντα που απαντά με το ίδιο μήνυμα που του στέλνετε.

Προαπαιτούμενα στοιχεία

• .NET 8.0 SDK ή νεότερο

  • Για να εγκαταστήσετε το .NET SDK, μεταβείτε στη διεύθυνση dotnet.microsoft.com και ακολουθήστε τις οδηγίες για το λειτουργικό σας σύστημα.
  • Για να επαληθεύσετε την έκδοση, στο τερματικό πληκτρολογήστε dotnet --version.

• Ένας επεξεργαστής κώδικα της επιλογής σας. Αυτές οι οδηγίες χρησιμοποιούν Visual Studio Code.

Αρχικοποιήστε το έργο και εγκαταστήστε το SDK

Χρησιμοποιήστε το dotnet για να δημιουργήσετε ένα νέο έργο web και να εγκαταστήσετε τις απαιτούμενες εξαρτήσεις.

1. Ανοίξτε ένα τερματικό και δημιουργήστε έναν νέο φάκελο

   mkdir echo
   cd echo
   

2. Αρχικοποιήστε το έργο .NET

   dotnet new web
   

3. Εγκαταστήστε το SDK παραγόντων

   dotnet add package Microsoft.Agents.Hosting.AspNetCore
   

4. Ανοίξτε το φάκελο στο Visual Studio Code χρησιμοποιώντας αυτήν την εντολή:

   code .
   

Εισάγετε τις απαιτούμενες βιβλιοθήκες

Στο Program.cs, αντικαταστήστε το υπάρχον περιεχόμενο και προσθέστε τις παρακάτω using δηλώσεις για να εισαγάγετε τα πακέτα SDK στον κώδικα της εφαρμογής σας:

// Program.cs
using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App;
using Microsoft.Agents.Builder.State;
using Microsoft.Agents.Core.Models;
using Microsoft.Agents.Hosting.AspNetCore;
using Microsoft.Agents.Storage;
using Microsoft.AspNetCore.Builder;

Υλοποιήστε το EchoAgent ως AgentApplication

Στο Program.cs, μετά τις δηλώσεις using, προσθέστε τον ακόλουθο κώδικα για να δημιουργήσετε το EchoAgent που επεκτείνει το AgentApplication και να υλοποιήσετε διαδρομές για απόκριση σε συμβάντα:

• Ενημέρωση συνομιλίας
• Οποιαδήποτε άλλη δραστηριότητα

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

   private async Task WelcomeMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
   {
        foreach (ChannelAccount member in turnContext.Activity.MembersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text("Hello and Welcome!"), cancellationToken);
            }
        }
    }

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

Ρύθμιση του διακομιστή web και καταχώρηση της εφαρμογής παράγοντα

Στο Program.cs, μετά τις δηλώσεις using, προσθέστε τον ακόλουθο κώδικα για να διαμορφώσετε τον διακομιστή web, να καταχωρήσετε τον παράγοντα και να αντιστοιχίσετε το τελικό σημείο /api/messages:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient();
builder.AddAgentApplicationOptions();
builder.AddAgent<EchoAgent>();
builder.Services.AddSingleton<IStorage, MemoryStorage>();

var app = builder.Build();

app.MapPost("/api/messages", async (HttpRequest request, HttpResponse response, IAgentHttpAdapter adapter, IAgent agent, CancellationToken cancellationToken) =>
{
    await adapter.ProcessAsync(request, response, agent, cancellationToken);
});

app.Run();

Ρυθμίστε τον διακομιστή web να ακούει στο localhost:3978

Στο launchSettings.json, ενημερώστε το applicationURL σε http://localhost:3978 ώστε η εφαρμογή να ακούει στη σωστή θύρα.

Εκτελέστε τον παράγοντα τοπικά σε ανώνυμη λειτουργία

Από το τερματικό σας, εκτελέστε αυτήν την εντολή:

dotnet run

Το τερματικό θα πρέπει να εμφανίσει κάτι όπως:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:3978

Δοκιμή του παράγοντα τοπικά

1. Σε ένα δεύτερο τερματικό (για να συνεχίσει να λειτουργεί ο παράγοντας), εγκαταστήστε το Microsoft 365 Agents Playground με την παρακάτω εντολή:

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

   Σημείωμα

   Αυτή η εντολή χρησιμοποιεί το npm επειδή το Microsoft 365 Agents Playground διανέμεται ως πακέτο npm.

   Το τερματικό θα πρέπει να εμφανίσει κάτι όπως:

   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 ανοίγει το προεπιλεγμένο πρόγραμμα περιήγησης και συνδέεται με τον παράγοντα σας.

Στο πεδίο κειμένου, εισαγάγετε και στείλτε οποιοδήποτε μήνυμα για να δείτε την απάντηση επανάληψης.

Επόμενα βήματα

• Δείτε δείγματα του SDK παραγόντων στο GitHub
• Μάθετε περισσότερα για τις Δραστηριότητες και τη διαχείρισή τους
• Εξετάστε τα συμβάντα AgentApplication στα οποία μπορείτε να ανταποκριθείτε από τον πελάτη
• Ελέγξτε τα συμβάντα TurnContext που μπορείτε να στείλετε πίσω στον πελάτη
• Προετοιμάστε πόρους Azure Bot για χρήση με το Agents SDK
• Ρύθμιση παραμέτρων παράγοντα .NET για χρήση του OAuth

Η πλατφόρμα δοκιμών Agents Playground είναι διαθέσιμη από προεπιλογή εάν χρησιμοποιείτε ήδη το κιτ εργαλείων παραγόντων Microsoft 365. Μπορείτε να χρησιμοποιήσετε έναν από τους παρακάτω οδηγούς εάν θέλετε να ξεκινήσετε με την εργαλειοθήκη:

• Δημιουργία παραγόντων .NET στο Visual Studio με χρήση του Κιτ εργαλείων παραγόντων Microsoft 365
• Δημιουργία παραγόντων JavaScript στο Visual Studio Code με το Κιτ εργαλείων παραγόντων Microsoft 365