Pika-aloitus: Perusagentin luominen ja testaaminen

Tämä pika-aloitus auttaa luomaan mukautetun moduuliagentin, joka vastaa mihin tahansa sille lähetettyyn viestiin.

Edellytykset

  • Python 3.9 tai uudempi.

    • Asenna Python siirtymällä osoitteeseen https://www.python.org/downloads/ ja noudattamalla käyttöjärjestelmäkohtaisia ohjeita.
    • Tarkista versio kirjoittamalla python --version pääteikkunaan.

  • Valittu koodieditori. Näissä ohjeissa on käytössä Visual Studio Code.

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

Projektin aloittaminen 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 käyttämällä tätä komentoa Visual Studio Codessa:

    code .

  3. Luo virtuaaliympäristö valitulla menetelmällä ja aktivoi se joko Visual Studio Codessa tai päätteessä.

    Jos käytössä on Visual Studio Codea, voit käyttää seuraavia ohjeita Python-laajennus asennettuna.

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

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

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

        Arvo saattaa olla seuraavankaltainen:

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

  4. Agenttien SDK:n asennus

    pip mahdollistaa microsoft-agents-hosting-aiohttp-paketin asentamisen seuraavalla komennolla:

    pip install microsoft-agents-hosting-aiohttp

Palvelinsovelluksen luominen ja tarvittavien kirjastojen tuominen

  1. Luo start_server.py-tiedosto, 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äärittelee seuraavassa tiedostossa käytettävän start_server-funktion.

  2. Luo samaan hakemistoon app.py-niminen tiedosto ja seuraava koodi.

    # 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

Agenttiesiintymän luonti AgentApplication-luokkana

Lisää seuraava koodi app.py-tiedostoon ja luo AGENT_APPAgentApplication-esiintymänä. Toteuta lisäksi kolme reittiä, jotka vastaavat kolmeen tapahtumaan:

  • Keskustelun päivitys
  • Viesti /help
  • Mikä tahansa muu aktiviteetti
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}")

Verkkopalvelimen käynnistäminen kuuntelemaan osoitetta localhost:3978

Kun app.py päättyy, käynnistä verkkopalvelin komennolla start_server.

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

Agentin suorittaminen paikallisesti anonyymitilassa

Suorita tämä komento päätteessä:

python app.py

Päätteen pitäisi palauttaa seuraava:

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

Agentin testaaminen paikallisesti

  1. Asenna Microsoft 365:n agenttien testausalusta toisesta päätteestä (jotta agentti pysyy käynnissä) seuraavalla komennolla:

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

    Muistiinpano

    Tässä komennossa on käytössä npm, koska Microsoft 365:n agenttien testausalustan käyttö ei ole mahdollista pip-paketin asennusohjelmaa käytettäessä.

    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 ja käytä agenttia 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\"}"}}

teamsapptester-komento avaa oletusselaimen ja yhdistää agenttiin.

Agentti agenttien testausalustassa

Voit nyt nähdä kaikuvastauksen lähettämällä jonkin viestin, ja lähettämällä viestin /help näet, miten viesti reititetään _help-käsittelijään.

Tämä pika-aloitus auttaa luomaan mukautetun moduuliagentin, joka vastaa mihin tahansa sille lähetettyyn viestiin.

Edellytykset

  • Node.js v22 tai uudempi

    • Asenna Node.js siirtymällä osoitteeseen nodejs.org ja noudattamalla käyttöjärjestelmäkohtaisia ohjeita.
    • Tarkista versio kirjoittamalla node --version pääteikkunaan.

  • Valittu koodieditori. Näissä ohjeissa on käytössä Visual Studio Code.

Projektin aloittaminen ja SDK:n asentaminen

Ota käyttöön npm ja aloita node.js-projekti luomalla package.json ja asentamalla tarvittavat riippuvuudet

  1. Avaa pääte ja luo uusi kansio

    mkdir echo
cd echo

  2. Node.js-projektin aloittaminen

    npm init -y

  3. Agenttien SDK:n asennus

    npm install @microsoft/agents-hosting-express

  4. Avaa kansio Visual Studio Codessa tällä komennolla:

    code .

Tarvittavien kirjastojen tuominen

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

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

EchoAgent-toteutus AgentApplication-luokkana

Luo EchoAgent lisäämällä seuraava koodi index.mjs-tiedostoon laajentamaan AgentApplication, ja toteuta kolme reittiä vastaamaan kolmeen tapahtumaan:

  • Keskustelun päivitys
  • Viesti /help
  • Mikä tahansa muu aktiviteetti
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)
  }
}

Verkkopalvelimen käynnistäminen kuuntelemaan osoitetta localhost:3978

Kun index.mjs päättyy, käynnistä verkkopalvelin komennolla startServer expressin perusteella ja käyttämällä MemoryStorage-ratkaisua vuorotilan tallennuksena.

startServer(new EchoAgent(new MemoryStorage()))

Agentin suorittaminen paikallisesti anonyymitilassa

Suorita tämä komento päätteessä:

node index.mjs

Päätteen tulisi palauttaa seuraava:

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

Agentin testaaminen paikallisesti

  1. Asenna Microsoft 365:n agenttien testausalusta toisesta päätteestä (jotta agentti pysyy käynnissä) seuraavalla 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 ja käytä agenttia 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\"}"}}

teamsapptester-komento avaa oletusselaimen ja yhdistää agenttiin.

Agentti agenttien testausalustassa

Voit nyt nähdä kaikuvastauksen lähettämällä jonkin viestin, ja lähettämällä viestin /help näet, miten viesti reititetään _help-käsittelijään.

Tämä pika-aloitus auttaa luomaan mukautetun moduuliagentin, joka vastaa mihin tahansa sille lähetettyyn viestiin.

Edellytykset

  • .NET 8.0 SDK tai uudempi

    • Asenna .NET SDK siirtymällä osoitteeseen dotnet.microsoft.com ja noudattamalla käyttöjärjestelmäkohtaisia ohjeita.
    • Tarkista versio kirjoittamalla dotnet --version pääteikkunaan.

  • Valittu koodieditori. Näissä ohjeissa on käytössä Visual Studio Code.

Projektin aloittaminen ja SDK:n asentaminen

Luo uusi verkkoprojekti dotnet-komennolla ja asenna tarvittavat riippuvuudet.

  1. Avaa pääte ja luo uusi kansio

    mkdir echo
cd echo

  2. .NET-projektin aloittaminen

    dotnet new web

  3. Agenttien SDK:n asennus

    dotnet add package Microsoft.Agents.Hosting.AspNetCore

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

    code .

Tarvittavien kirjastojen tuominen

Korvaa nykyinen sisältö Program.cs-tiedostossa ja tuo SDK-paketit sovelluskoodiin lisäämällä seuraavat using-lausekkeet:

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

EchoAgent-toteutus AgentApplication-luokkana

Luo EchoAgent lisäämällä seuraava koodi Program.cs-tiedostoon using-lausekkeiden jälkeen laajentamaan AgentApplication, ja toteuta kolme reittiä vastaamaan kolmeen tapahtumaan:

  • Keskustelun päivitys
  • Kaikki muu aktiviteetti
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);
   }
}

Verkkopalvelimen määrittäminen ja agenttisovelluksen rekisteröinti

Lisää seuraava koodi Program.cs-tiedostoon using-lausekkeiden jälkeen määrittämään verkkoisäntä, rekisteröimään agentti ja yhdistämään /api/messages-päätepiste:

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

Verkkopalvelimen määrittäminen kuuntelemaan osoitteessa localhost:3978

Päivitä launchSettings.json-tiedostossa applicationURL-arvon tilalle http://localhost:3978, jotta sovellus kuuntelee oikeaa porttia.

Agentin suorittaminen paikallisesti anonyymitilassa

Suorita tämä komento päätteessä:

dotnet run

Päätteen tulisi palauttaa jotain seuraavankaltaista:

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

Agentin testaaminen paikallisesti

  1. Asenna Microsoft 365:n agenttien testausalusta toisesta päätteestä (jotta agentti pysyy käynnissä) seuraavalla komennolla:

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

    Muistiinpano

    Tässä komennossa on käytössä npm, koska Microsoft 365:n agenttien testausalusta 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 ja käytä agenttia 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\"}"}}

teamsapptester-komento avaa oletusselaimen ja yhdistää agenttiin.

Agentti agenttien testausalustassa

Näet kaikuvastauksen kirjoittamalla minkä tahansa viestin tekstikenttään ja lähettämällä sen.

Seuraavat vaiheet

Agenttien testausalusta on oletusarvoisesti käytettävissä, jos Microsoft 365 Agents Toolkit on jo käytössä. Seuraavat oppaat auttavat, jos aloittaa työkalujen käytön:

  • Last updated on