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

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

Προαπαιτούμενα

• 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 Agents

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

Τώρα μπορείτε να στείλετε οποιοδήποτε μήνυμα για να δείτε την απάντηση ηχούς ή να στείλετε το μήνυμα /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 Agents

   npm install @microsoft/agents-hosting-express
   

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

   code .
   

Εισαγωγή των απαιτούμενων βιβλιοθηκών

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

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

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

Υλοποιήστε το EchoAgent ως Εφαρμογή Πράκτορα

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

Τώρα μπορείτε να στείλετε οποιοδήποτε μήνυμα για να δείτε την απάντηση ηχούς ή να στείλετε το μήνυμα /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 Agents

   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 ως Εφαρμογή Πράκτορα

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

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

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

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

Στο 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 για χρήση με το SDK Agent
• Ρυθμίστε τις παραμέτρους του παράγοντα .NET για χρήση του OAuth

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

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