Jaa

Pikaopas: Perusagentin luominen ja testaaminen

Tässä pikaoppaassa kerrotaan, miten voit luoda mukautetun moduulin agentin , joka vastaa sinulle mistä tahansa viestistä.

Edellytykset

  • Python 3.9 tai uudempi.

    • Asenna Python siirtymällä kohtaan https://www.python.org/downloads/ja noudattamalla käyttöjärjestelmäsi ohjeita.
    • Voit tarkistaa version pääteikkunan tyypillä python --version.

  • Valitsemasi koodieditori. Näissä ohjeissa käytetään Visual Studio Codea.

    Jos käytät Visual Studio Codea, asenna Python-laajennus

Projektin alustaminen ja SDK:n asentaminen

Luo Python-projekti ja asenna tarvittavat riippuvuudet.

  1. Avaa pääte ja luo uusi kansio

    mkdir echo
cd echo

  2. Avaa kansio Visual Studio Coden avulla käyttämällä tätä komentoa:

    code .

  3. Luo virtuaaliympäristö valitsemallasi menetelmällä ja aktivoi se joko Visual Studio Coden tai päätteen kautta.

    Kun käytät Visual Studio Codea, voit käyttää näitä vaiheita asennetun Python-laajennuksen kanssa.

    1. Paina F1-näppäintä, kirjoita Python: Create environmentja paina Enter-näppäintä.

      1. Luo virtuaaliympäristö nykyiseen työtilaan valitsemalla .venv.

      2. Luo virtuaaliympäristö valitsemalla Python-asennus.

        Arvo saattaa näyttää tältä:

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

  4. Agenttien SDK:n asentaminen

    Asenna pipin avulla microsoft-agents-hosting-aiohttp-paketti , jossa on tämä komento:

    pip install microsoft-agents-hosting-aiohttp

Luo palvelinsovellus ja tuo vaaditut kirjastot

  1. Luo tiedosto nimeltä start_server.py, kopioi seuraava koodi ja liitä se:

    # 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

    Tämä koodi määrittää funktion, jota start_server käytämme seuraavassa tiedostossa.

  2. Luo samassa hakemistossa tiedosto, jonka nimi app.py on käyttäen seuraavaa koodia.

    # 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

Luo agentin ilmentymä AgentApplicationina

Lisää kohteeseen app.pyseuraava koodi , joka luo kohteen AGENT_APP -esiintymänä AgentApplication, ja toteuta kolme reittiä , jotta voit vastata kolmeen tapahtumaan:

  • Keskustelun päivitys
  • viesti /help
  • muuta toimintaa
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}")

Käynnistä verkkopalvelin kuuntelemaan sivua localhost:3978

Käynnistä verkkopalvelin -toiminnon app.pylopussa :n avulla start_server.

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

Suorita agentti paikallisesti anonyymitilassa

Suorita päätteestä tämä komento:

python app.py

Päätteen tulisi palauttaa seuraavat:

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

Testaa agentti paikallisesti

  1. Asenna toisesta päätteestä (jotta agentti käynnissä) Microsoft 365 Agents Playgroundin tällä komennolla:

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

    Note

    Tämä komento käyttää npm:ää, koska Microsoft 365 Agent Playground ei ole käytettävissä pip-funktion kautta.

    Päätteen tulisi palauttaa jotain seuraavankaltaista:

    added 1 package, and audited 130 packages in 1s

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

found 0 vulnerabilities

  2. Suorita testityökalu, jotta voit käsitellä agenttiasi tällä komennolla:

    teamsapptester

    Päätteen tulisi palauttaa jotain seuraavankaltaista:

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

Komento teamsapptester avaa oletusselaimen ja muodostaa yhteyden agenttiisi.

Agenttisi agenttien leikkikentällä.

Nyt voit lähettää minkä tahansa viestin, jotta näet vastauksen, tai lähettää viestin /help nähdäksesi, miten tämä viesti on reititetään käsittelijälle _help .

Tässä pikaoppaassa kerrotaan, miten voit luoda mukautetun moduulin agentin , joka vastaa sinulle mistä tahansa viestistä.

Edellytykset

  • Node.js v22 tai uudempi versio

    • Asenna Node.js siirtymällä nodejs.org ja noudattamalla käyttöjärjestelmäsi ohjeita.
    • Voit tarkistaa version pääteikkunan tyypillä node --version.

  • Valitsemasi koodieditori. Näissä ohjeissa käytetään Visual Studio Codea.

Projektin alustaminen ja SDK:n asentaminen

Käytä npm tätä node.js projektien alustamiseen luomalla package.json ja asentamalla vaaditut riippuvuudet

  1. Avaa pääte ja luo uusi kansio

    mkdir echo
cd echo

  2. node.js projektin alustaminen

    npm init -y

  3. Agenttien SDK:n asentaminen

    npm install @microsoft/agents-hosting-express

  4. Avaa kansio Visual Studio Coden avulla käyttämällä tätä komentoa:

    code .

Tarvittavien kirjastojen tuominen

Luo tiedosto index.mjs ja tuo seuraavat NPM-paketit sovelluskoodiisi:

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

Toteuta EchoAgent agenttisovelluksena

Lisää kohteeseen index.mjsseuraava koodi, joka luo EchoAgentAgentApplication-laajennusta laajentavan koodin, ja toteuta kolme reittiä, joilla voidaan vastata kolmeen tapahtumaan:

  • Keskustelun päivitys
  • viesti /help
  • muuta toimintaa
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)
  }
}

Käynnistä verkkopalvelin kuuntelemaan sivua localhost:3978

Käynnistä verkkopalvelin index.mjs lopussa, käyttäen startServer, joka toimii expressin pohjana, ja käyttää MemoryStorage:a tilan tallennustilana.

startServer(new EchoAgent(new MemoryStorage()))

Suorita agentti paikallisesti anonyymitilassa

Suorita päätteestä tämä komento:

node index.mjs

Päätteen tulisi palauttaa seuraava:

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

Testaa agentti paikallisesti

  1. Asenna toisesta päätteestä (jotta agentti käynnissä) Microsoft 365 Agents Playgroundin tällä komennolla:

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

    Päätteen tulisi palauttaa jotain seuraavankaltaista:

    added 1 package, and audited 130 packages in 1s

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

found 0 vulnerabilities

  2. Suorita testityökalu, jotta voit käsitellä agenttiasi tällä komennolla:

    node_modules/.bin/teamsapptester

    Päätteen tulisi palauttaa jotain seuraavankaltaista:

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

Komento teamsapptester avaa oletusselaimen ja muodostaa yhteyden agenttiisi.

Agenttisi agenttien leikkikentällä.

Nyt voit lähettää minkä tahansa viestin, jotta näet vastauksen, tai lähettää viestin /help nähdäksesi, miten tämä viesti on reititetään käsittelijälle _help .

Tässä pikaoppaassa kerrotaan, miten voit luoda mukautetun moduulin agentin , joka vastaa sinulle mistä tahansa viestistä.

Edellytykset

  • .NET 8.0 SDK tai uudempi

    • Jos haluat asentaa .NET SDK:n, siirry kohtaan dotnet.microsoft.com ja noudata käyttöjärjestelmäsi ohjeita.
    • Voit tarkistaa version pääteikkunan tyypillä dotnet --version.

  • Valitsemasi koodieditori. Näissä ohjeissa käytetään Visual Studio Codea.

Projektin alustaminen ja SDK:n asentaminen

Tämän avulla dotnet voit luoda uuden verkkoprojektin ja asentaa vaaditut riippuvuudet.

  1. Avaa pääte ja luo uusi kansio

    mkdir echo
cd echo

  2. Alusta .NET-projekti

    dotnet new web

  3. Agenttien SDK:n asentaminen

    dotnet add package Microsoft.Agents.Hosting.AspNetCore

  4. Avaa kansio Visual Studio Coden avulla käyttämällä tätä komentoa:

    code .

Tarvittavien kirjastojen tuominen

Korvaa kohteessa Program.csolemassa oleva sisältö ja lisää seuraavat using lausekkeet SDK-pakettien tuomiseksi sovelluskoodiisi:

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

Toteuta EchoAgent agenttisovelluksena

Program.csLisää kohteeseen -lausekkeiden jälkeen using seuraava koodi, joka luo EchoAgent-luokan, joka laajentaa AgentApplication-sovellusta, ja toteuta reittejä tapahtumiin vastaamiseksi:

  • Keskustelun päivitys
  • Mikä tahansa muu toiminta
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);
   }
}

Määritä verkkopalvelin ja rekisteröi agenttisovellus

Program.cs Lisää seuraava koodi using -lausekkeiden jälkeen verkkoisännän konfiguroimiseksi, agentin rekisteröimiseksi ja päätepisteen /api/messages liittämiseksi:

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

Määritä verkkopalvelin kuuntelemaan kohteessa localhost:3978

Päivitä launchSettings.jsonkohteessa kohteeseen applicationURLhttp://localhost:3978 niin, että sovellus kuuntelee oikeaa porttia.

Suorita agentti paikallisesti anonyymi-tilassa

Suorita päätteestä tämä komento:

dotnet run

Päätteen tulisi palauttaa jotain seuraavankaltaista:

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

Testaa agentti paikallisesti

  1. Asenna Microsoft 365 Agents Playground toisesta päätteestä (jotta agentti pysyy toiminnassa) seuraavalla komennolla:

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

    Note

    Tämä komento käyttää npm:ää, koska Microsoft 365 Agents Playground jaetaan npm-pakettina.

    Päätteen tulisi palauttaa jotain seuraavankaltaista:

    added 1 package, and audited 130 packages in 1s

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

found 0 vulnerabilities

  2. Suorita testityökalu, jotta voit käsitellä agenttiasi tällä komennolla:

    teamsapptester

    Päätteen tulisi palauttaa jotain seuraavankaltaista:

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

Komento teamsapptester avaa oletusselaimen ja muodostaa yhteyden agenttiisi.

Agenttisi agenttien leikkikentällä.

Kirjoita tekstisyötettä ja lähetä mikä tahansa viesti, jotta näet kaikuvastauksen.

Seuraavat vaiheet

Agents Playground on oletusarvoisesti käytettävissä, jos käytät jo Microsoft 365 -agenttien työkalupakettia. Voit käyttää jotakin seuraavista oppaista, jos haluat aloittaa työkalupaketin käytön:

  • Last updated on