Snelstart: Een basisagent maken en testen

In deze quickstart wordt u begeleid bij het maken van een aangepaste engine-agent die simpelweg antwoord geeft met elk bericht dat u ernaar verzendt.

Vereisten

  • Python 3.9 of nieuwer.

    • Om Python te installeren, ga naar https://www.python.org/downloads/ en volg de instructies voor uw besturingssysteem.
    • Om de versie te controleren, typt u python --version in een terminalvenster.

  • Een code-editor naar keuze. Deze instructies gebruiken Visual Studio Code.

    Als u Visual Studio Code gebruikt, installeer dan de Python-extensie

Initialiseer het project en installeer de SDK

Maak een Python-project en installeer de benodigde afhankelijkheden.

  1. Open een terminal en maak een nieuwe map

    mkdir echo
cd echo

  2. Open de map met Visual Studio Code met dit commando:

    code .

  3. Maak een virtuele omgeving met de methode van uw keuze en activeer deze via Visual Studio Code of in een terminal.

    Wanneer u Visual Studio Code gebruikt, kunt u deze stappen uitvoeren met de Python-extensie geïnstalleerd.

    1. Druk op F1, typ Python: Create environment en druk op Enter.

      1. Selecteer Venv om een ​​.venv virtuele omgeving in de huidige werkruimte te creëren.

      2. Selecteer een Python-installatie om de virtuele omgeving te creëren.

        De waarde kan er als volgt uitzien:

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

  4. Installeer de Agents SDK

    Gebruik pip om het microsoft-agents-hosting-aiohttp pakket te installeren met deze opdracht:

    pip install microsoft-agents-hosting-aiohttp

Maak de servertoepassing en importeer de vereiste bibliotheken

  1. Maak een bestand met de naam start_server.py, kopieer de volgende code en plak deze erin:

    # 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

    Deze code definieert een start_server functie die we in het volgende bestand zullen gebruiken.

  2. Maak in dezelfde map een bestand met de naam app.py met de volgende 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

Maak een instantie van de agent aan als een AgentApplication

Voeg in app.py de volgende code toe om de AGENT_APP aan te maken als een instantie van de AgentApplication en implementeer drie routes om te reageren op drie gebeurtenissen:

  • Gespreksupdate
  • het bericht /help
  • elke andere activiteit
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}")

Start de webserver om te luisteren op localhost:3978

Aan het einde van app.py, start u de webserver met behulp van start_server.

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

De agent lokaal uitvoeren in de anonieme modus

Voer vanuit uw terminal de volgende opdracht uit:

python app.py

De terminal zou het volgende moeten weergeven:

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

Test de agent lokaal

  1. Installeer vanuit een andere terminal (om de agent actief te houden) de Microsoft 365 Agents Playground met deze opdracht:

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

    Notitie

    Deze opdracht gebruikt npm omdat de Microsoft 365 Agents Playground niet beschikbaar is via pip.

    De terminal zou iets dergelijks moeten weergeven:

    added 1 package, and audited 130 packages in 1s

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

found 0 vulnerabilities

  2. Voer de testtool uit om met uw agent te communiceren met behulp van deze opdracht:

    teamsapptester

    De terminal zou iets dergelijks moeten weergeven:

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

Met de opdracht teamsapptester wordt uw standaardbrowser geopend en wordt verbinding gemaakt met uw agent.

Uw agent in de agent-playground

Nu kunt u elk bericht verzenden om het echo-antwoord te zien, of het bericht /help verzenden om te zien hoe dat bericht naar de _help-handler wordt gerouteerd.

In deze quickstart wordt u begeleid bij het maken van een aangepaste engine-agent die simpelweg antwoord geeft met elk bericht dat u ernaar verzendt.

Vereisten

  • Node.js v22 of nieuwer

    • Om Node.js te installeren, gaat u naar nodejs.org en volgt u de instructies voor uw besturingssysteem.
    • Om de versie te controleren, typt u node --version in een terminalvenster.

  • Een code-editor naar keuze. Deze instructies gebruiken Visual Studio Code.

Initialiseer het project en installeer de SDK

Gebruik npm om een ​​Node.js-project te initialiseren door een package.json-bestand aan te maken en de benodigde afhankelijkheden te installeren

  1. Open een terminal en maak een nieuwe map

    mkdir echo
cd echo

  2. Initialiseer het Node.js-project

    npm init -y

  3. Installeer de Agents SDK

    npm install @microsoft/agents-hosting-express

  4. Open de map met Visual Studio Code met behulp van deze opdracht:

    code .

De vereiste bibliotheken importeren

Maak het bestand index.mjs aan en importeer de volgende NPM-pakketten in uw applicatiecode:

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

Implementeer de EchoAgent als een AgentApplication

Voeg in index.mjs de volgende code toe om de EchoAgent te creëren die de AgentApplication uitbreidt, en implementeer drie routes om te reageren op drie gebeurtenissen:

  • Gespreksupdate
  • het bericht /help
  • elke andere activiteit
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)
  }
}

Start de webserver om te luisteren op localhost:3978

Aan het einde van index.mjs start de webserver met behulp van startServer gebaseerd op express en gebruik MemoryStorage als opslag voor de toestand van de beurt.

startServer(new EchoAgent(new MemoryStorage()))

De agent lokaal uitvoeren in de anonieme modus

Voer vanuit uw terminal de volgende opdracht uit:

node index.mjs

De terminal zou dit moeten retourneren:

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

Test de agent lokaal

  1. Installeer vanuit een andere terminal (om de agent actief te houden) de Microsoft 365 Agents Playground met deze opdracht:

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

    De terminal zou iets dergelijks moeten weergeven:

    added 1 package, and audited 130 packages in 1s

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

found 0 vulnerabilities

  2. Voer de testtool uit om met uw agent te communiceren met behulp van deze opdracht:

    node_modules/.bin/teamsapptester

    De terminal zou iets dergelijks moeten weergeven:

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

Met de opdracht teamsapptester wordt uw standaardbrowser geopend en wordt verbinding gemaakt met uw agent.

Uw agent in de agent-playground

Nu kunt u elk bericht verzenden om het echo-antwoord te zien, of het bericht /help verzenden om te zien hoe dat bericht naar de _help-handler wordt gerouteerd.

In deze quickstart wordt u begeleid bij het maken van een aangepaste engine-agent die simpelweg antwoord geeft met elk bericht dat u ernaar verzendt.

Vereisten

  • .NET 8.0 SDK of nieuwer

    • Om de .NET SDK te installeren, ga naar dotnet.microsoft.com en volg de instructies voor uw besturingssysteem.
    • Om de versie te controleren, typt u dotnet --version in een terminalvenster.

  • Een code-editor naar keuze. Deze instructies gebruiken Visual Studio Code.

Initialiseer het project en installeer de SDK

Gebruik dotnet om een ​​nieuw webproject te maken en de benodigde afhankelijkheden te installeren.

  1. Open een terminal en maak een nieuwe map

    mkdir echo
cd echo

  2. Initialiseer het .NET-project

    dotnet new web

  3. Installeer de Agents SDK

    dotnet add package Microsoft.Agents.Hosting.AspNetCore

  4. Open de map met Visual Studio Code met dit commando:

    code .

De vereiste bibliotheken importeren

Vervang in Program.cs de bestaande inhoud en voeg de volgende using instructies toe om de SDK-pakketten in uw applicatiecode te importeren:

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

Implementeer de EchoAgent als een AgentApplication

Voeg in Program.cs, na de using instructies, de volgende code toe om de EchoAgent te creëren die AgentApplication uitbreidt, en implementeer routes om op gebeurtenissen te reageren:

  • Gespreksupdate
  • Overige activiteiten
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);
   }
}

De webserver instellen en de agenttoepassing registreren

Voeg in Program.cs, na de using instructies, de volgende code toe om de webhost te configureren, de agent te registreren en het /api/messages eindpunt te koppelen:

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

Stel de webserver in om te luisteren op localhost:3978

Werk in launchSettings.json de applicationURL bij naar http://localhost:3978 zodat de app op de juiste poort luistert.

De agent lokaal uitvoeren in de anonieme modus

Voer vanuit uw terminal de volgende opdracht uit:

dotnet run

De terminal zou iets dergelijks moeten weergeven:

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

Test de agent lokaal

  1. Installeer vanuit een andere terminal (om de agent actief te houden) de Microsoft 365 Agents Playground met de volgende opdracht:

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

    Notitie

    Deze opdracht gebruikt npm omdat de Microsoft 365 Agents Playground als npm-pakket wordt gedistribueerd.

    De terminal zou iets dergelijks moeten weergeven:

    added 1 package, and audited 130 packages in 1s

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

found 0 vulnerabilities

  2. Voer de testtool uit om met uw agent te communiceren met behulp van deze opdracht:

    teamsapptester

    De terminal zou iets dergelijks moeten weergeven:

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

Met de opdracht teamsapptester wordt uw standaardbrowser geopend en wordt verbinding gemaakt met uw agent.

Uw agent in de agent-playground

Voer in het tekstinvoerveld een bericht in en verzend het om het echo-antwoord te zien.

Volgende stappen

De Agents Playground is standaard beschikbaar als u de Microsoft 365 Agents Toolkit al gebruikt. U kunt een van de volgende handleidingen gebruiken om aan de slag te gaan met de toolkit:

  • Last updated on