Schnellstart: Erstellen und Testen eines einfachen Agents

Diese Schnellstartanleitung führt Sie durch das Erstellen eines benutzerdefinierten Modul-Agents , der mit jeder nachricht antwortet, die Sie an das Modul senden.

Voraussetzungen

• Python 3.9 oder höher.

  • Um Python zu installieren, wechseln Sie zu https://www.python.org/downloads/, und folgen Sie den Anweisungen für Ihr Betriebssystem.
  • Um die Version zu überprüfen, geben Sie in einem Terminalfenstertyp python --versionan.

• Ein Code-Editor Ihrer Wahl. Diese Anweisungen verwenden Visual Studio Code.

  Wenn Sie Visual Studio Code verwenden, installieren Sie die Python-Erweiterung.

Initialisieren des Projekts und Installieren des SDK

Erstellen Sie ein Python-Projekt, und installieren Sie die erforderlichen Abhängigkeiten.

1. Öffnen eines Terminals und Erstellen eines neuen Ordners

   mkdir echo
   cd echo
   

2. Öffnen Sie den Ordner mit Visual Studio Code mit diesem Befehl:

   code .
   

3. Erstellen Sie eine virtuelle Umgebung mit der von Ihnen gewählten Methode, und aktivieren Sie sie entweder über Visual Studio Code oder in einem Terminal.

   Wenn Sie Visual Studio Code verwenden, können Sie diese Schritte mit der installierten Python-Erweiterung ausführen.

   1. Drücken Sie F1, geben Sie Python: Create environmentein, und drücken Sie die EINGABETASTE.

      1. Wählen Sie Venv aus, um eine .venv virtuelle Umgebung im aktuellen Arbeitsbereich zu erstellen.

      2. Wählen Sie eine Python-Installation aus, um die virtuelle Umgebung zu erstellen.

         Der Wert sieht möglicherweise wie folgt aus:

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

4. Installieren des Agents SDK

   Verwenden Sie pip , um das microsoft-agents-hosting-aiohttp-Paket mit diesem Befehl zu installieren:

   pip install microsoft-agents-hosting-aiohttp
   

Erstellen der Serveranwendung und Importieren der erforderlichen Bibliotheken

1. Erstellen Sie eine Datei mit dem Namen start_server.py, kopieren Sie den folgenden Code, und fügen Sie sie ein:

   # 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
   

   Dieser Code definiert eine start_server Funktion, die wir in der nächsten Datei verwenden werden.

2. Erstellen Sie im selben Verzeichnis eine Datei app.py mit dem folgenden Code.

   # 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
   

Erstellen Sie eine Instanz des Agents als AgentAnwendung

app.pyFügen Sie im Folgenden den folgenden Code hinzu, um die AGENT_APP Als Instanz des AgentApplicationObjekts zu erstellen, und implementieren Sie drei Routen, um auf drei Ereignisse zu reagieren:

• Konversationsaktualisierung
• Die Meldung /help
• alle anderen Aktivitäten

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

Starten Sie den Webserver, um auf localhost:3978 zu lauschen.

Am Ende von app.py starten Sie den Webserver mit start_server.

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

Führen Sie den Agenten lokal im anonymen Modus aus

Führen Sie in Ihrem Terminal den folgenden Befehl aus:

python app.py

Das Terminal sollte Folgendes zurückgeben:

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

Testen Sie den Agenten lokal

1. Installieren Sie von einem anderen Terminal (um den Agent auf dem Laufenden zu halten) den Microsoft 365 Agents Playground mit diesem Befehl:

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

   Hinweis

   Dieser Befehl verwendet npm, da der Microsoft 365-Agents-Playground nicht mit Pip verfügbar ist.

   Das Terminal sollte etwa wie folgt zurückgeben:

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

2. Führen Sie das Testtool aus, um mit Ihrem Agent mit diesem Befehl zu interagieren:

   teamsapptester
   

   Das Terminal sollte etwa wie folgt zurückgeben:

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

Der teamsapptester Befehl öffnet Ihren Standardbrowser und stellt eine Verbindung mit Ihrem Agent bereit.

Jetzt können Sie eine beliebige Nachricht senden, um die Echoantwort anzuzeigen, oder die Nachricht /help senden, um zu sehen, wie diese Nachricht an den _help Handler weitergeleitet wird.

Diese Schnellstartanleitung führt Sie durch das Erstellen eines benutzerdefinierten Modul-Agents , der mit jeder nachricht antwortet, die Sie an das Modul senden.

Voraussetzungen

• Node.js v22 oder höher

  • Um Node.js zu installieren, wechseln Sie zu nodejs.org, und befolgen Sie die Anweisungen für Ihr Betriebssystem.
  • Um die Version zu überprüfen, geben Sie in einem Terminalfenstertyp node --versionan.

• Ein Code-Editor Ihrer Wahl. Diese Anweisungen verwenden Visual Studio Code.

Initialisieren des Projekts und Installieren des SDK

Verwenden Sie npm, um ein Node.js-Projekt zu initialisieren, indem Sie eine package.json erstellen und die erforderlichen Abhängigkeiten installieren.

1. Öffnen eines Terminals und Erstellen eines neuen Ordners

   mkdir echo
   cd echo
   

2. Initialisieren des node.js Projekts

   npm init -y
   

3. Installieren des Agents SDK

   npm install @microsoft/agents-hosting-express
   

4. Öffnen Sie den Ordner mit Visual Studio Code mit dem folgenden Befehl:

   code .
   

Importieren der erforderlichen Bibliotheken

Erstellen Sie die Datei index.mjs , und importieren Sie die folgenden NPM-Pakete in Ihren Anwendungscode:

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

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

Implementieren des EchoAgent als AgentApplication

index.mjsFügen Sie im Folgenden den folgenden Code hinzu, um die EchoAgent Erweiterung der AgentApplication zu erstellen, und implementieren Sie drei Routen, um auf drei Ereignisse zu reagieren:

• Konversationsaktualisierung
• Die Meldung /help
• alle anderen Aktivitäten

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

Starten Sie den Webserver, um auf localhost:3978 zu lauschen.

Am Ende von index.mjs starten Sie den Webserver mit startServer basierend auf Express und verwenden Sie MemoryStorage als Turn-Zustandsspeicher.

startServer(new EchoAgent(new MemoryStorage()))

Führen Sie den Agenten lokal im anonymen Modus aus

Führen Sie in Ihrem Terminal den folgenden Befehl aus:

node index.mjs

Das Terminal sollte folgendes zurückgeben:

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

Testen Sie den Agenten lokal

1. Installieren Sie von einem anderen Terminal (um den Agent auf dem Laufenden zu halten) den Microsoft 365 Agents Playground mit diesem Befehl:

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

   Das Terminal sollte etwa wie folgt zurückgeben:

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

2. Führen Sie das Testtool aus, um mit Ihrem Agent mit diesem Befehl zu interagieren:

   node_modules/.bin/teamsapptester
   

   Das Terminal sollte etwa wie folgt zurückgeben:

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

Der teamsapptester Befehl öffnet Ihren Standardbrowser und stellt eine Verbindung mit Ihrem Agent bereit.

Jetzt können Sie eine beliebige Nachricht senden, um die Echoantwort anzuzeigen, oder die Nachricht /help senden, um zu sehen, wie diese Nachricht an den _help Handler weitergeleitet wird.

Diese Schnellstartanleitung führt Sie durch das Erstellen eines benutzerdefinierten Modul-Agents , der mit jeder nachricht antwortet, die Sie an das Modul senden.

Voraussetzungen

• .NET 8.0 SDK oder höher

  • Um das .NET SDK zu installieren, wechseln Sie zu dotnet.microsoft.com, und folgen Sie den Anweisungen für Ihr Betriebssystem.
  • Um die Version zu überprüfen, geben Sie in einem Terminalfenstertyp dotnet --versionan.

• Ein Code-Editor Ihrer Wahl. Diese Anweisungen verwenden Visual Studio Code.

Initialisieren des Projekts und Installieren des SDK

Verwenden Sie dotnet , um ein neues Webprojekt zu erstellen und die erforderlichen Abhängigkeiten zu installieren.

1. Öffnen eines Terminals und Erstellen eines neuen Ordners

   mkdir echo
   cd echo
   

2. Initialisieren des .NET-Projekts

   dotnet new web
   

3. Installieren des Agents SDK

   dotnet add package Microsoft.Agents.Hosting.AspNetCore
   

4. Öffnen Sie den Ordner mit Visual Studio Code mit diesem Befehl:

   code .
   

Importieren der erforderlichen Bibliotheken

Program.cs, ersetzen Sie den vorhandenen Inhalt und fügen Sie die folgenden using Statements hinzu, um die SDK-Pakete in Ihren Anwendungscode zu importieren.

// 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;

Implementieren des EchoAgent als AgentApplication

Fügen Sie nach Program.cs den using Anweisungen den folgenden Code hinzu, um die EchoAgent erweiternde AgentApplication zu erstellen, und implementieren Sie Routen zum Reagieren auf Ereignisse.

• Konversationsaktualisierung
• Alle anderen Aktivitäten

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

Einrichten des Webservers und Registrieren der Agentanwendung

Fügen Sie Program.cs nach den using Anweisungen den folgenden Code hinzu, um den Webhost zu konfigurieren, den Agenten zu registrieren und den /api/messages-Endpunkt zuzuordnen.

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

Setzen Sie den Webserver so, dass er auf localhost:3978 lauscht.

Aktualisieren Sie in launchSettings.json die applicationURL zu http://localhost:3978, damit die App auf dem richtigen Port lauscht.

Führen Sie den Agenten im anonymen Modus lokal aus.

Führen Sie in Ihrem Terminal den folgenden Befehl aus:

dotnet run

Das Terminal sollte etwa wie folgt zurückgeben:

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

Testen Sie den Agenten lokal

1. Installieren Sie den Microsoft 365 Agents Playground mit dem folgenden Befehl von einem anderen Terminal (um den Agent auf dem Laufenden zu halten):

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

   Hinweis

   Dieser Befehl verwendet npm, da der Microsoft 365 Agents Playground als npm-Paket verteilt wird.

   Das Terminal sollte etwa wie folgt zurückgeben:

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

2. Führen Sie das Testtool aus, um mit Ihrem Agent mit diesem Befehl zu interagieren:

   teamsapptester
   

   Das Terminal sollte etwa wie folgt zurückgeben:

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

Der teamsapptester Befehl öffnet Ihren Standardbrowser und stellt eine Verbindung mit Ihrem Agent bereit.

Geben Sie in der Texteingabe eine nachricht ein, und senden Sie sie, um die Echoantwort anzuzeigen.

Nächste Schritte

• Sehen Sie sich Agents SDK-Beispiele auf GitHub an
• Erfahren Sie mehr über die Aktivitäten und das Arbeiten mit Aktivitäten
• Überprüfen Sie die Agent Application-Ereignisse, auf die vom Client aus reagiert werden können
• Überprüfen Sie die TurnContext-Ereignisse, die Sie an den Client zurückgesendet haben.
• Bereitstellen von Azure Bot-Ressourcen für die Verwendung mit agents SDK
• Konfigurieren Des .NET-Agents für die Verwendung von OAuth

Der Agents-Playground ist standardmäßig verfügbar, wenn Sie bereits das Microsoft 365 Agents Toolkit verwenden. Sie können eines der folgenden Leitfäden verwenden, wenn Sie mit dem Toolkit beginnen möchten:

• Erstellen von .NET-Agents in Visual Studio mit dem Microsoft 365 Agents Toolkit
• Erstellen von JavaScript-Agents in Visual Studio Code mit dem Microsoft 365 Agents Toolkit