Σημείωση
Η πρόσβαση σε αυτή τη σελίδα απαιτεί εξουσιοδότηση. Μπορείτε να δοκιμάσετε να συνδεθείτε ή να αλλάξετε καταλόγους.
Η πρόσβαση σε αυτή τη σελίδα απαιτεί εξουσιοδότηση. Μπορείτε να δοκιμάσετε να αλλάξετε καταλόγους.
Αυτός ο οδηγός γρήγορης εκκίνησης σάς καθοδηγεί στη δημιουργία ενός παράγοντα προσαρμοσμένης μηχανής που απαντά με οποιοδήποτε μήνυμα στέλνετε σε αυτόν.
Προαπαιτούμενα στοιχεία
Python 3.9 ή νεότερη έκδοση.
- Για να εγκαταστήσετε την Python, μεταβείτε https://www.python.org/downloads/στο και ακολουθήστε τις οδηγίες για το λειτουργικό σύστημά σας.
- Για να επαληθεύσετε την έκδοση, σε έναν τύπο
python --versionπαραθύρου τερματικού .
Ένα πρόγραμμα επεξεργασίας κώδικα της επιλογής σας. Αυτές οι οδηγίες χρησιμοποιούν το Visual Studio Code.
Εάν χρησιμοποιείτε Visual Studio Code, εγκαταστήστε την επέκταση Python
Προετοιμασία του έργου και εγκατάσταση του SDK
Δημιουργήστε ένα έργο Python και εγκαταστήστε τις απαιτούμενες εξαρτήσεις.
Ανοίξτε ένα τερματικό και δημιουργήστε έναν νέο φάκελο
mkdir echo cd echoΑνοίξτε τον φάκελο χρησιμοποιώντας το Visual Studio Code χρησιμοποιώντας αυτή την εντολή:
code .Δημιουργήστε ένα εικονικό περιβάλλον με τη μέθοδο της επιλογής σας και ενεργοποιήστε το είτε μέσω του Visual Studio Code είτε σε ένα τερματικό.
Όταν χρησιμοποιείτε το Visual Studio Code, μπορείτε να χρησιμοποιήσετε αυτά τα βήματα με εγκατεστημένη την επέκταση Python .
Πατήστε το πλήκτρο F1, πληκτρολογήστε
Python: Create environmentκαι πατήστε Enter.Επιλέξτε Venv για να δημιουργήσετε ένα
.venvεικονικό περιβάλλον στον τρέχοντα χώρο εργασίας.Επιλέξτε μια εγκατάσταση Python για να δημιουργήσετε το εικονικό περιβάλλον.
Η τιμή μπορεί να μοιάζει κάπως έτσι:
Python 1.13.6 ~\AppData\Local\Programs\Python\Python313\python.exe
Εγκατάσταση του SDK Agents
Χρησιμοποιήστε το pip για να εγκαταστήσετε το πακέτο microsoft-agents-hosting-aiohttp με αυτή την εντολή:
pip install microsoft-agents-hosting-aiohttp
Δημιουργία της εφαρμογής διακομιστή και εισαγωγή των απαιτούμενων βιβλιοθηκών
Δημιουργήστε ένα αρχείο με ονομασία
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συνάρτηση που θα χρησιμοποιήσουμε στο επόμενο αρχείο.Στον ίδιο κατάλογο, δημιουργήστε ένα αρχείο με την ονομασία
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)
Δοκιμή του παράγοντα τοπικά
Από ένα άλλο τερματικό (για να διατηρήσετε τον παράγοντα σε λειτουργία) εγκαταστήστε το Microsoft 365 Agents Playground με αυτή την εντολή:
npm install -g @microsoft/teams-app-test-toolNote
Αυτή η εντολή χρησιμοποιεί 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Εκτελέστε το εργαλείο δοκιμής για να αλληλεπιδράσετε με τον παράγοντα χρησιμοποιώντας αυτή την εντολή:
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 και εγκαθιστώντας τις απαιτούμενες εξαρτήσεις
Ανοίξτε ένα τερματικό και δημιουργήστε έναν νέο φάκελο
mkdir echo cd echoΠροετοιμασία του έργου node.js
npm init -yΕγκατάσταση του SDK Agents
npm install @microsoft/agents-hosting-expressΑνοίξτε τον φάκελο χρησιμοποιώντας το 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
Δοκιμή του παράγοντα τοπικά
Από ένα άλλο τερματικό (για να διατηρήσετε τον παράγοντα σε λειτουργία) εγκαταστήστε το 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Εκτελέστε το εργαλείο δοκιμής για να αλληλεπιδράσετε με τον παράγοντα χρησιμοποιώντας αυτή την εντολή:
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 χειρισμό.
Επόμενα βήματα
Αυτή η γρήγορη εκκίνηση σάς δείχνει πώς μπορείτε να κάνετε λήψη και εκτέλεση του δείγματος 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.
- .NET 8.0 SDK
- Visual Studio ή Visual Studio Code
- Γνώση του ASP.NET Core και ασύγχρονος προγραμματισμός στη C#
-
Λήψη του δείγματος από το
quickstartGitHub
Άνοιγμα της λύσης
Ανοίξτε το αρχείο
QuickStart.csprojλύσης στο Visual Studio.Εκτελέστε το έργο.
Σε αυτό το σημείο, ο παράγοντας εκτελείται τοπικά χρησιμοποιώντας τη θύρα 3978.
Δοκιμάστε τον πράκτορά σας τοπικά
Εγκαταστήστε το Agents Playground εάν δεν το έχετε κάνει ήδη.
winget install agentsplaygroundΞεκινήστε τον παράγοντα στο Visual Studio ή Visual Studio Code
Ξεκινήστε τον Έλεγχο εφαρμογών του Teams. Σε μια γραμμή εντολών:
agentsplayground- Το εργαλείο ανοίγει ένα πρόγραμμα περιήγησης web που εμφανίζει το Εργαλείο δοκιμής εφαρμογής Teams, έτοιμο να στείλει μηνύματα στον πράκτορά σας.
Ο πράκτορας που εκτελείτε στη θύρα 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 για να επιστρέψετε στο πρόγραμμα-πελάτη.
Τώρα που γνωρίζετε τα βασικά στοιχεία, δείτε τα επόμενα βήματα και εργαστείτε για να προσθέσετε προσαρμοσμένη λογική χειρισμού στον πράκτορά σας και να στείλετε πίσω διαφορετικά συμβάντα.
Επόμενα βήματα
- Μάθετε περισσότερα σχετικά με τις Δραστηριότητες και την εργασία με δραστηριότητες
- Εξετάστε τα συμβάντα AgentApplication στα οποία μπορείτε να απαντήσετε από το πρόγραμμα-πελάτη
- Εξετάστε τα συμβάντα TurnContext που μπορείτε να σταλούν πίσω στο πρόγραμμα-πελάτη
- Προμήθεια πόρων Azure Bot για χρήση με το SDK Agent
- Ρυθμίστε τις παραμέτρους του παράγοντα .NET για χρήση του OAuth
Το Agents Playground είναι διαθέσιμο από προεπιλογή, εάν χρησιμοποιείτε ήδη το Κιτ εργαλείων Microsoft 365 Agents. Μπορείτε να χρησιμοποιήσετε έναν από τους παρακάτω οδηγούς εάν θέλετε να ξεκινήσετε με το κιτ εργαλείων: