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 einer Instanz des Agents als AgentApplication

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.

Starten Sie am Ende des Webservers app.pymit start_server.

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

Lokales Ausführen des Agents im anonymen Modus

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.

Nächste Schritte

Bereitstellen von Azure Bot-Ressourcen für die Verwendung mit agents SDK

Diese Schnellstartanleitung führt Sie durch das Erstellen eines benutzerdefinierten Modul-Agents , der nur mit dem, was Sie an das Modul senden, antwortet.

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

Lokales Ausführen des Agents im anonymen Modus

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.

Nächste Schritte

Bereitstellen von Azure Bot-Ressourcen für die Verwendung mit agents SDK

Dieser Quickstart zeigt Ihnen, wie Sie das QuickStart/Empty Agent-Beispiel von GitHub herunterladen und ausführen können.

Es gibt zwei Hauptmöglichkeiten für die ersten Schritte mit dem Microsoft 365 Agents SDK:

• Klonen und Ausführen des QuickStart/Empty Agent-Agent-Beispiels, das auf GitHub verfügbar ist

• Verwenden Sie das Microsoft 365 Agents Toolkit. Das Agents Toolkit verfügt über zwei integrierte Vorlagen für Visual Studio und Visual Studio Code, die das Microsoft 365 Agents SDK verwenden, um mit einem Schnellstart/leeren Agent und einem Wetter-Agent zu beginnen, der Azure Foundry- oder OpenAI-Dienste mit semantischem Kernel oder LangChain verwendet.

Voraussetzungen

Sie benötigen einige Dinge, bevor Sie beginnen. Diese Schritte verwenden das Schnellstart-/Leere Agent-Beispiel in .NET-Schnellstart, aber Sie können auch ein beliebiges Agents SDK-Beispiel verwenden.

• .NET 8.0 SDK
• Visual Studio oder Visual Studio Code
• Kenntnisse über ASP.Net Core und asynchrone Programmierung in C#
• Herunterladen des Beispiels quickstart von GitHub

Öffnen der Lösung

1. Öffnen Sie die Projektmappendatei QuickStart.csproj in Visual Studio.

2. Führen Sie das Projekt aus.

An diesem Punkt wird Ihr Agent lokal mit Port 3978 ausgeführt.

Testen Sie Ihren Agenten lokal

1. Installiere den Agents Playground, falls du das noch nicht getan hast.

   winget install agentsplayground
   

2. Starten Sie den Agenten in Visual Studio oder Visual Studio Code

3. Starten Sie den Teams-App-Tester. An einer Eingabeaufforderung: agentsplayground

   • Das Tool öffnet einen Webbrowser mit dem Teams-App-Testtool, das zum Senden von Nachrichten an Ihren Agent bereit ist.

4. Ihr ausgeführter Agent auf Port 3978 sollte sich automatisch mit dem Agent-Playground in Ihrem Browser verbinden, und Sie sollten in der Lage sein, mit Ihrem Agent zu interagieren, der lokal ausgeführt wird

Wie funktioniert der Agent?

Mit dem Agents SDK wird ein Agent mithilfe von AgentApplication - und AgentApplicationOptions-Klassen erstellt. Dies ist in der Program.cs Datei des Beispiels integriert.

Agent erstellen

Sie können im Beispiel sehen, dass beim Erstellen des Agents AgentApplicationOptions geladen wird und Ihre benutzerdefinierte Agentenklasse MyAgent.cs von AgentApplication erbt.

// Add AgentApplicationOptions from appsettings section "AgentApplication".
builder.AddAgentApplicationOptions();

// Add the AgentApplication, which contains the logic for responding to
// user messages.
builder.AddAgent<MyAgent>();

Anschließend wird der Speicher standardmäßig mit der MemoryStorage-Klasse geladen. Dadurch kann der Kontext über verschiedene Schritte hinweg nachverfolgt werden, wenn TurnState verwendet wird. In der Produktion sollte jedoch auf eine dauerhaftere Speicherung wie BlobsStorage oder CosmosDbPartitionedStorage umgestellt werden.

builder.Services.AddSingleton<IStorage, MemoryStorage>();

Der Rest der Agentanwendung verwendet standardmäßige .NET-Hostingmuster und fügt Routen hinzu, um Nachrichten an einem bestimmten Endpunkt zu akzeptieren. Diese Routen verwenden die IAgent-Schnittstelle, um die Agentaktivität zu akzeptieren, und stellt Entwicklern das AgentApplication Objekt bereit, um mit der Aktivitätsnutzlast zu arbeiten, die vom Kanal/Client an sie übergeben wurde. Erfahren Sie mehr über die Aktivitäten und das Arbeiten mit Aktivitäten

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

Hinzufügen einer neuen benutzerdefinierten Logik in einer Methode

Entwickler fügen benutzerdefinierte Logik in der Klasse hinzu, die MyAgent.cs, das AgentApplication implementiert. Diese Klasse verwendet AgentApplicationOptions, um spezifische Einstellungen aus Ihrer Konfiguration zu konfigurieren, und Program.cs registriert Ereignislistener aus dem Agents SDK, die in der AgentApplication Klasse verfügbar sind, welche Ihre jeweilige benutzerdefinierte Methode aufruft, wenn solche Ereignisse vom Client ausgelöst werden.

Im folgenden Beispiel löst OnConversationUpdate die WelcomeMessageAsync Methode aus, und OnActivity löst die Methode OnMessageAsyncaus.

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

Diese Ereignisse werden über den in Ihrem MyProgram.cs Endpunkt konfigurierten Endpunkt weitergeleitet, und es gibt zahlreiche Ereignisse, die Sie verwenden können. Die häufigste ist OnActivity. Weitere Informationen zu den Ereignissen, die das SDK implementiert, finden Sie unter " Arbeiten mit Aktivitäten " und der Spezifikation des Activity-Protokolls.

Nachdem Ihre Methode ausgelöst wurde, z.OnMessageAsync B. um den Zug zu beenden, können Sie in Ihrer benutzerdefinierten Logik auswählen, ob Sie eine Nachricht zurück an den Client senden möchten, indem Sie die Methoden verwenden, die für eine Instanz der TurnContext-Klasse verfügbar sind, die als Parameter in Ihrer Methode enthalten sein sollte, wie im folgenden Beispiel gezeigt:

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

Jetzt kennen Sie die Grundlagen, sehen Sie sich die nächsten Schritte an, und arbeiten Sie daran, Ihrem Agent benutzerdefinierte Handlerlogik hinzuzufügen und verschiedene Ereignisse zurückzusenden.

Nächste Schritte

• 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