Delen via

Quickstart: Een basisagent maken en testen

In deze snelle startgids wordt u begeleid bij het maken van een aangepaste engineagent die antwoordt met hetzelfde bericht dat u ernaar verzendt.

Vereiste voorwaarden

  • Python 3.9 of hoger.

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

  • Een code-editor van uw keuze. In deze instructies wordt Visual Studio Code gebruikt.

    Als u Visual Studio Code gebruikt, installeert u de Python-extensie

Het project initialiseren en de SDK installeren

Maak een Python-project en installeer de vereiste afhankelijkheden.

  1. Een terminal openen en een nieuwe map maken

    mkdir echo
cd echo

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

    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 gebruiken om de Python-extensie te installeren.

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

      1. Selecteer Venv om een .venv virtuele omgeving te maken in de huidige werkruimte.

      2. Selecteer een Python-installatie om de virtuele omgeving te maken.

        De waarde kan er als volgt uitzien:

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

  4. De Agents SDK installeren

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

    pip install microsoft-agents-hosting-aiohttp

De servertoepassing maken en de vereiste bibliotheken importeren

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

    # 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 gaan 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

Een exemplaar van de agent maken als AgentApplication

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

  • Gespreksupdate
  • het bericht /help
  • andere activiteiten
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 in 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 de terminal deze opdracht uit:

python app.py

De terminal moet het volgende retourneren:

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

De agent lokaal testen

  1. Installeer vanaf 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

    Opmerking

    Deze opdracht maakt gebruik van npm omdat de Microsoft 365 Agents Playground niet beschikbaar is met pip.

    De terminal moet ongeveer als volgt retourneren:

    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 het testprogramma uit om met uw agent te communiceren met behulp van deze opdracht:

    teamsapptester

    De terminal moet ongeveer als volgt retourneren:

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

De teamsapptester opdracht opent uw standaardbrowser en maakt verbinding met uw agent.

Uw agent in de agent-playground

U kunt nu elk bericht verzenden om het echoantwoord te zien of het bericht /help verzenden om te zien hoe dat bericht naar de _help handler wordt doorgestuurd.

In deze snelle startgids wordt u begeleid bij het maken van een aangepaste engineagent die antwoordt met hetzelfde bericht dat u ernaar verzendt.

Vereiste voorwaarden

  • Node.js v22 of hoger

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

  • Een code-editor van uw keuze. In deze instructies wordt Visual Studio Code gebruikt.

Het project initialiseren en de SDK installeren

Gebruik npm dit om een node.js project te initialiseren door een package.json te maken en de vereiste afhankelijkheden te installeren

  1. Een terminal openen en een nieuwe map maken

    mkdir echo
cd echo

  2. Het node.js-project initialiseren

    npm init -y

  3. De Agents SDK installeren

    npm install @microsoft/agents-hosting-express

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

    code .

De vereiste bibliotheken importeren

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

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

De EchoAgent implementeren als agentapplication

Voeg index.mjsde volgende code toe om de EchoAgent uitbreiding van AgentApplication te maken en implementeer drie routes om te reageren op drie gebeurtenissen:

  • Gespreksupdate
  • het bericht /help
  • andere activiteiten
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 in 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 de terminal deze opdracht uit:

node index.mjs

De terminal moet dit retourneren:

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

De agent lokaal testen

  1. Installeer vanaf 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 moet ongeveer als volgt retourneren:

    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 het testprogramma uit om met uw agent te communiceren met behulp van deze opdracht:

    node_modules/.bin/teamsapptester

    De terminal moet ongeveer als volgt retourneren:

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

De teamsapptester opdracht opent uw standaardbrowser en maakt verbinding met uw agent.

Uw agent in de agent-playground

U kunt nu elk bericht verzenden om het echoantwoord te zien of het bericht /help verzenden om te zien hoe dat bericht naar de _help handler wordt doorgestuurd.

In deze snelle startgids wordt u begeleid bij het maken van een aangepaste engineagent die antwoordt met hetzelfde bericht dat u ernaar verzendt.

Vereiste voorwaarden

  • .NET 8.0 SDK of hoger

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

  • Een code-editor van uw keuze. In deze instructies wordt Visual Studio Code gebruikt.

Het project initialiseren en de SDK installeren

Gebruik dotnet dit om een nieuw webproject te maken en de vereiste afhankelijkheden te installeren.

  1. Een terminal openen en een nieuwe map maken

    mkdir echo
cd echo

  2. Het .NET-project initialiseren

    dotnet new web

  3. De Agents SDK installeren

    dotnet add package Microsoft.Agents.Hosting.AspNetCore

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

    code .

De vereiste bibliotheken importeren

Vervang Program.csde bestaande inhoud en voeg de volgende using instructies toe om de SDK-pakketten in uw toepassingscode 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;

De EchoAgent implementeren als agentapplication

Voeg Program.csna de using instructies de volgende code toe om de EchoAgent uitbreidende AgentApplication te maken en implementeer routes om te reageren op gebeurtenissen:

  • Gespreksupdate
  • Andere 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 Program.csna de using instructies de volgende code toe om de webhost te configureren, de agent te registreren en het /api/messages eindpunt toe te wijzen:

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 in localhost:3978

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

De agent lokaal uitvoeren in de anonieme modus

Voer vanuit de terminal deze opdracht uit:

dotnet run

De terminal moet ongeveer als volgt retourneren:

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

De agent lokaal testen

  1. Installeer vanaf 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

    Opmerking

    Deze opdracht maakt gebruik van npm omdat de Microsoft 365 Agents Playground wordt gedistribueerd als een npm-pakket.

    De terminal moet ongeveer als volgt retourneren:

    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 het testprogramma uit om met uw agent te communiceren met behulp van deze opdracht:

    teamsapptester

    De terminal moet ongeveer als volgt retourneren:

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

De teamsapptester opdracht opent uw standaardbrowser en maakt verbinding met uw agent.

Uw agent in de agent-playground

Typ en verzend een bericht in de tekstinvoer om het echoantwoord 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 als u aan de slag wilt met de toolkit:

  • Last updated on