Κοινοποίηση μέσω


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

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

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

  • 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
    

Δημιουργία μιας παρουσίας του παράγοντα ως παράγονταΕφαρμογές

Στο 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
    

    Note

    Αυτή η εντολή χρησιμοποιεί 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 χειρισμό.

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

Προμήθεια πόρων Azure Bot για χρήση με το SDK Agent

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

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

  • 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 στον κωδικό εφαρμογής σας:

// 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 χειρισμό.

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

Προμήθεια πόρων Azure Bot για χρήση με το SDK Agent

Αυτή η γρήγορη εκκίνηση σάς δείχνει πώς μπορείτε να κάνετε λήψη και εκτέλεση του δείγματος QuickStart/Empty Agent από το GitHub.

Υπάρχουν δύο κύριοι τρόποι για να ξεκινήσετε με το SDK Microsoft 365 Agents:

  • Κλωνοποίηση και εκτέλεση του δείγματος παράγοντα QuickStart/Empty Agent που είναι διαθέσιμο στο GitHub

  • Χρησιμοποιήστε το Κιτ εργαλείων Microsoft 365 Agents. Το Κιτ εργαλείων Agents διαθέτει δύο ενσωματωμένα πρότυπα για το Visual Studio και τον Κώδικα Visual Studio που χρησιμοποιούν το SDK Πρακτόρων Microsoft 365 για την εκκίνηση με έναν Παράγοντα QuickStart/Empty και έναν Παράγοντα καιρού που χρησιμοποιεί υπηρεσίες Azure Foundry ή OpenAI με σημασιολογικό πυρήνα ή LangChain.

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

Χρειάζεστε μερικά πράγματα πριν ξεκινήσετε. Αυτά τα βήματα χρησιμοποιούν το δείγμα QuickStart/Empty Agent στη γρήγορη εκκίνηση .NET, αλλά μπορείτε επίσης να χρησιμοποιήσετε οποιοδήποτε δείγμα Agents SDK.

Άνοιγμα της λύσης

  1. Ανοίξτε το αρχείο QuickStart.csproj λύσης στο Visual Studio.

  2. Εκτελέστε το έργο.

Σε αυτό το σημείο, ο παράγοντας εκτελείται τοπικά χρησιμοποιώντας τη θύρα 3978.

Δοκιμάστε τον πράκτορά σας τοπικά

  1. Εγκαταστήστε το Agents Playground εάν δεν το έχετε κάνει ήδη.

    winget install agentsplayground
    
  2. Ξεκινήστε τον παράγοντα στο Visual Studio ή Visual Studio Code

  3. Ξεκινήστε τον Έλεγχο εφαρμογών του Teams. Σε μια γραμμή εντολών: agentsplayground

    • Το εργαλείο ανοίγει ένα πρόγραμμα περιήγησης web που εμφανίζει το Εργαλείο δοκιμής εφαρμογής Teams, έτοιμο να στείλει μηνύματα στον πράκτορά σας.
  4. Ο πράκτορας που εκτελείτε στη θύρα 3978 θα πρέπει να συνδέεται αυτόματα με την παιδική χαρά των αντιπροσώπων στο πρόγραμμα περιήγησής σας και θα πρέπει να μπορείτε να αλληλεπιδράσετε με τον πράκτορά σας που εκτελείται τοπικά

Πώς δουλεύει ο πράκτορας;

Με το Agents 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>();

Στη συνέχεια, ο χώρος αποθήκευσης φορτώνεται από προεπιλογή χρησιμοποιώντας την κλάση ΜνήμηΑποθήκευση. Αυτό επιτρέπει την παρακολούθηση του περιβάλλοντος σε όλες τις στροφές κατά τη χρήση του TurnState , ωστόσο, θα πρέπει να απενεργοποιηθεί στην παραγωγή για πιο μόνιμο χώρο αποθήκευσης, όπως blobsStorage ή CosmosDbPartitionedStorage.

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 καταχωρεί υπηρεσίες ακρόασης συμβάντων από το Agents SDK, που είναι διαθέσιμες στην κλάση που αναφέρεται στην AgentApplication αντίστοιχη προσαρμοσμένη μέθοδο όταν αυτά τα συμβάντα ενεργοποιούνται από το πρόγραμμα-πελάτη.

Στο παρακάτω παράδειγμα, η onConversationUpdate ενεργοποιεί τη μέθοδο και η WelcomeMessageAsynconActivity ενεργοποιεί τη μέθοδο OnMessageAsync.

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

Αυτά τα συμβάντα δρομολογούνται μέσω του τελικού σημείου που έχει ρυθμιστεί στο και MyProgram.cs υπάρχουν πολλά συμβάντα που μπορείτε να χρησιμοποιήσετε. Η συνηθέστερη περίπτωση είναι OnActivity. Για να μάθετε περισσότερα σχετικά με τα συμβάντα που υλοποιεί το SDK, δείτε περισσότερα σχετικά με την εργασία με δραστηριότητες και την προδιαγραφή του πρωτοκόλλου Δραστηριότητας.

Όταν ενεργοποιηθεί η μέθοδός σας, για παράδειγμα OnMessageAsync για να τερματίσετε τη στροφή, μπορείτε να επιλέξετε στην προσαρμοσμένη λογική σας να απαντήσετε για να στείλετε ένα μήνυμα πίσω στο πρόγραμμα-πελάτη, χρησιμοποιώντας τις διαθέσιμες μεθόδους και την παρουσία της κλάσης TurnContext που πρέπει να είναι μια παράμετρος στη μέθοδό σας, όπως φαίνεται στο παρακάτω παράδειγμα:

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

Συμβουλή

Εξετάστε τις άλλες διαθέσιμες μεθόδους TurnContext για να επιστρέψετε στο πρόγραμμα-πελάτη.

Τώρα που γνωρίζετε τα βασικά στοιχεία, δείτε τα επόμενα βήματα και εργαστείτε για να προσθέσετε προσαρμοσμένη λογική χειρισμού στον πράκτορά σας και να στείλετε πίσω διαφορετικά συμβάντα.

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

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