Schnellstart: Erstellen und Testen eines einfachen Agents

In diesem Quickstart lernen Sie, wie Sie einen benutzerdefinierten Engine-Agenten erstellen, der mit jeder Nachricht antwortet, die Sie ihm senden.

Voraussetzungen

  • Python 3.9 oder neuer.

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

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

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

Initialisieren Sie das Projekt und installieren Sie das SDK

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

  1. Öffnen Sie ein Terminal und erstellen Sie einen neuen Ordner

    mkdir echo
cd echo

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

    code .

  3. Erstellen Sie eine virtuelle Umgebung mit einer Methode Ihrer Wahl und aktivieren Sie sie entweder über Visual Studio Code oder im Terminal.

    Wenn Sie Visual Studio Code verwenden, können Sie diese Schritte ausführen, wenn die Python-Erweiterung installiert ist.

    1. Drücken Sie F1 und tippen Sie Python: Create environment und drücken die Eingabetaste.

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

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

        Der Werte könnte folgendermaßen aussehen:

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

  4. Installieren von Agents SDK

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

    pip install microsoft-agents-hosting-aiohttp

Erstellen Sie die Serveranwendung und importieren Sie die erforderlichen Bibliotheken

  1. Erstellen Sie eine Datei namens start_server.py, kopieren den folgenden Code und fügen ihn 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 in demselben Verzeichnis eine Datei mit dem Namen app.py und 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 Agenten als AgentApplication

Fügen Sie in app.py den folgenden Code hinzu, um AGENT_APP als Instanz von AgentApplication zu erstellen und drei Routen für die Reaktion auf drei Ereignisse zu implementieren:

  • Unterhaltungsupdate
  • Die Meldung /help
  • Jede andere Aktivität
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, damit er auf localhost:3978 hört

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

Ausführen des Agents im anonymen Modus

Führen Sie in Ihrem Terminal diesen Befehl aus:

python app.py

Das Terminal sollte Folgendes ausgeben:

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

Testen des Agents lokal

  1. Installieren Sie von einem anderen Terminal aus (um den Agenten am Laufen zu halten) den Microsoft 365 Agents Playground mit diesem Befehl:

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

    Anmerkung

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

    Das Terminal sollte in etwa Folgendes ausgeben:

    added 1 package, and audited 130 packages in 1s

19 packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities

  2. Starten Sie das Testtool, um mit Ihrem Agenten zu interagieren, mit folgendem Befehl:

    teamsapptester

    Das Terminal sollte in etwa Folgendes ausgeben:

    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 zu Ihrem Agenten her.

Ihr Agent im Agents-Playground

Jetzt können Sie eine beliebige Nachricht senden, um die Echo-Antwort zu sehen, oder die Nachricht /help senden, um zu sehen, wie diese Nachricht zum _help Handler weitergeleitet wird.

In diesem Quickstart lernen Sie, wie Sie einen benutzerdefinierten Engine-Agenten erstellen, der mit jeder Nachricht antwortet, die Sie ihm senden.

Voraussetzungen

  • Node.js v22 oder neuer

    • Um Node.js zu installieren, gehen Sie zu nodejs.org und folgen den Anweisungen für Ihr Betriebssystem.
    • Um die Version zu überprüfen, geben Sie in einem Terminalfenster Folgendes ein: node --version.

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

Initialisieren Sie das Projekt und installieren Sie das 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 Sie ein Terminal und erstellen Sie einen neuen Ordner

    mkdir echo
cd echo

  2. Initialisieren Sie das Node.js-Projekt

    npm init -y

  3. Installieren von 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:

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

Implementieren Sie den EchoAgent als AgentApplication

Fügen Sie in index.mjs den folgenden Code hinzu, um die EchoAgent zu erstellen, die von AgentApplication abgeleitet ist, und implementieren Sie drei Routen, um auf drei Ereignisse zu reagieren:

  • Unterhaltungsupdate
  • Die Meldung /help
  • Jede andere Aktivität
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, damit er auf localhost:3978 hört

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

Ausführen des Agents im anonymen Modus

Führen Sie in Ihrem Terminal diesen 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 des Agents lokal

  1. Installieren Sie von einem anderen Terminal aus (um den Agenten am Laufen zu halten) den Microsoft 365 Agents Playground mit diesem Befehl:

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

    Das Terminal sollte in etwa Folgendes ausgeben:

    added 1 package, and audited 130 packages in 1s

19 packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities

  2. Starten Sie das Testtool, um mit Ihrem Agenten zu interagieren, mit folgendem Befehl:

    node_modules/.bin/teamsapptester

    Das Terminal sollte in etwa Folgendes ausgeben:

    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 zu Ihrem Agenten her.

Ihr Agent im Agents-Playground

Jetzt können Sie eine beliebige Nachricht senden, um die Echo-Antwort zu sehen, oder die Nachricht /help senden, um zu sehen, wie diese Nachricht zum _help Handler weitergeleitet wird.

In diesem Quickstart lernen Sie, wie Sie einen benutzerdefinierten Engine-Agenten erstellen, der mit jeder Nachricht antwortet, die Sie ihm senden.

Voraussetzungen

  • .NET 8.0 SDK oder höher

    • Um das .NET SDK zu installieren, gehen Sie zu dotnet.microsoft.com und folgen den Anweisungen für Ihr Betriebssystem.
    • Um die Version zu überprüfen, geben Sie in einem Terminalfenster Folgendes ein: dotnet --version.

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

Initialisieren Sie das Projekt und installieren Sie das SDK

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

  1. Öffnen Sie ein Terminal und erstellen Sie einen neuen Ordner

    mkdir echo
cd echo

  2. Das .NET-Projekt initialisieren

    dotnet new web

  3. Installieren von Agents SDK

    dotnet add package Microsoft.Agents.Hosting.AspNetCore

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

    code .

Importieren der erforderlichen Bibliotheken

Ersetzen Sie in Program.cs den vorhandenen Inhalt, und fügen Sie die folgenden using-Anweisungen 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 Sie den EchoAgent als AgentApplication

Fügen Sie in Program.cs nach den using-Anweisungen den folgenden Code ein, um die EchoAgent-Klasse zu erstellen, die von AgentApplication abgeleitet ist, und implementieren Sie Routen zur Reaktion auf Ereignisse:

  • Unterhaltungsupdate
  • Jede andere Aktivität
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);
   }
}

Richten Sie den Webserver ein und registrieren Sie die Agentanwendung

Fügen Sie in Program.cs nach den using-Anweisungen den folgenden Code hinzu, um den Webhost zu konfigurieren, den Agent 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();

Stellen Sie den Webserver so ein, dass er auf localhost:3978 lauscht

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

Ausführen des Agents im anonymen Modus

Führen Sie in Ihrem Terminal diesen Befehl aus:

dotnet run

Das Terminal sollte in etwa Folgendes ausgeben:

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

Testen des Agents lokal

  1. Von einem anderen Terminal aus (damit der Agent weiterläuft) installiere den Microsoft 365 Agents Playground mit folgendem Befehl:

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

    Anmerkung

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

    Das Terminal sollte in etwa Folgendes ausgeben:

    added 1 package, and audited 130 packages in 1s

19 packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities

  2. Starten Sie das Testtool, um mit Ihrem Agenten zu interagieren, mit folgendem Befehl:

    teamsapptester

    Das Terminal sollte in etwa Folgendes ausgeben:

    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 zu Ihrem Agenten her.

Ihr Agent im Agents-Playground

Geben Sie im Texteingabefeld eine beliebige Nachricht ein und senden Sie sie ab, um die Echo-Antwort zu erhalten.

Nächste Schritte,

Der Agents Playground steht Ihnen standardmäßig zur Verfügung, wenn Sie bereits das Microsoft 365-Agents-Toolkit verwenden. Sie können eine der folgenden Anleitungen verwenden, wenn Sie mit dem Toolkit beginnen möchten:

  • Last updated on