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 agentti-esiintymä agenttisovelluksena

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.

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 .

Seuraavat vaiheet

Azure Bot -resurssien valmisteleminen käytettäväksi Agents SDK:n kanssa

Tämä pikaopas opastaa sinua luomaan mukautetun moduuliagentin , joka vain vastaa siihen lähettämiesi ohjeiden mukaisesti.

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:

• @microsoft/agenttien isännöinti
• @microsoft/agents-hosting-express

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

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 .

Seuraavat vaiheet

Azure Bot -resurssien valmisteleminen käytettäväksi Agents SDK:n kanssa

Tämä pikakäynnistys näyttää, miten lataat ja suoritat QuickStart/Empty Agent -näytteen GitHubista.

Microsoft 365 -agenttien SDK:n käytön voi aloittaa kahdella tavalla:

• Kloonaa ja suorita QuickStart-/Empty Agent -malli, joka on käytettävissä GitHubissa

• Käytä Microsoft 365 Agents Toolkitiä. Agents Toolkit sisältää kaksi sisäistä mallia Visual Studiolle ja Visual Studio Codelle, jotka käyttävät Microsoft 365 Agent SDK:ta quickstart-/empty-agentista sekä sääagentista, joka käyttää Azure Foundrya tai OpenAI-palveluita joko semanttisen ydin- tai LangChain-mallin kanssa.

Edellytykset

Tarvitset pari juttua ennen aloittamista. Näissä ohjeissa käytetään QuickStart/Empty Agent -näytettä .NET-pikaoppaassa, mutta voit myös käyttää agenttien SDK-otosta.

• .NET 8.0 SDK
• Visual Studio tai Visual Studio Code
• ASP.NET Coren ja asynkronisen ohjelmoinnin tunteminen C#:ssä
• Mallin lataaminen quickstart GitHubista

Avaa ratkaisu

1. Avaa ratkaisutiedosto QuickStart.csproj Visual Studiossa.

2. Suorita projekti.

Tässä vaiheessa agenttisi toimii paikallisesti käyttäen porttia 3978.

Testaa agenttisi paikallisesti

1. Asenna Agents Playground , jos et ole vielä tehnyt niin.

   winget install agentsplayground
   

2. Käynnistä agentti Visual Studiossa tai Visual Studio Codessa

3. Käynnistä Teams-sovelluksen testaaja. Komentokehotteessa: agentsplayground

   • Työkalu avaa verkkoselaimen, jossa on Teams-sovelluksen testityökalu valmiina lähettämään viestejä agentillesi.

4. Satamassa 3978 olevan agenttisi tulisi muodostaa automaattisesti yhteys selaimesi agentin leikkikenttään, ja sinun pitäisi pystyä olemaan vuorovaikutuksessa paikallisen agentin kanssa.

Miten agentti toimii?

Agenttien SDK:ssa agentti luodaan käyttäen AgentApplication - ja AgentApplicationOptions-luokkia . Tämä sisältyy Program.cs mallin tiedostoon.

Agentin koostaminen

Näet mallista, että kun agenttia luodaan, se ladataan AgentApplicationOptions ja mukautettu agenttiluokkasi MyAgent.cs , joka perii kohteesta AgentApplication

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

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

Sen jälkeen tallennustila ladataan oletusarvoisesti Käyttämällä MemoryStorage-luokkaa. Tämä mahdollistaa kontekstin seurannan vuorotellen TurnState-toimintoa käytettäessä, mutta se tulisi poistaa käytöstä tuotannossa, jos tallennustila on pysyvämpi, kuten BlobsStorage tai CosmosDbPartitionedStorage.

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

Muut agenttisovellukset käyttävät vakiomuotoista .NET-isännöintimallia ja lisäävät reittejä hyväksyäkseen sanomia tietyssä päätepisteessä. Nämä reitit käyttävät IAgent-käyttöliittymää agentin toiminnan hyväksymiseen ja antavat kehittäjille AgentApplication objektin, jolla he voivat käsitellä sille kanavasta/asiakkaalta siirrettyjä aktiivisuustietoja . Lue lisätietoja aktiviteeteista ja toimintojen käsittelemisestä

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

Lisää uusi mukautettu logiikka menetelmään

Kehittäjät lisäävät mukautetun MyAgent.cs logiikan luokkaan, jossa toteutetaan AgentApplication. Tämä luokka käyttää AgentApplicationOptions -parametria määrittämään minkä tahansa määritetyn asetuksen sekä Program.cs rekisteröimään Agents SDK:n tapahtuman kuuntelutoiminnot, jotka ovat käytettävissä AgentApplication luokassa, joka viittaa vastaavaan mukautettuun menetelmään, kun nämä tapahtumat käynnistetään asiakkaalta.

Seuraavassa esimerkissä OnConversationUpdate käynnistää -menetelmän WelcomeMessageAsync ja OnActivity käynnistää menetelmän OnMessageAsync.

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

Nämä tapahtumat reititetään kohteessa MyProgram.cs määritetyn päätepisteen kautta, ja käytettävissäsi on useita tapahtumia. Yleisin on OnActivity. Lisätietoja SDK:n toteuttamista tapahtumista on artikkelissa Toimintojen käsitteleminen ja Aktiviteetin protokollamääritys.

Kun menetelmä on käynnistetty, esimerkiksi OnMessageAsync lopettaa käännöksen, voit valita mukautetusta logiikasta vastauksen viestiin lähettämiseksi takaisin asiakkaalle käyttämällä TurnContext-luokan käytettävissä olevia menetelmiä ja esiintymää, joiden pitäisi olla parametri menetelmässäsi, kuten seuraavassa esimerkissä esitetään:

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

Vihje

Tarkista muut käytettävissä olevat TurnContext-menetelmät , jotta voit palata asiakkaaseen.

Nyt tiedät perusteet, tutustu seuraaviin vaiheisiin ja työstä mukautetun käsittelijän logiikan lisäämiseksi agentillesi ja eri tapahtumien lähettämiseksi takaisin.

Seuraavat vaiheet

• Lue lisätietoja aktiviteeteista ja toimintojen käsittelemisestä
• Tarkista AgentApplication-tapahtumat, joihin voit vastata asiakasohjelmasta
• Tarkista turncontext-tapahtumat, jotka voit lähettää takaisin asiakkaalle
• Azure Bot -resurssien valmisteleminen käytettäväksi Agents SDK:n kanssa
• .NET-agentin määrittäminen käyttämään OAuth-todennusta

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:

• Luo .NET-agentteja Visual Studiossa Microsoft 365 -agenttien Toolkitin avulla
• JavaScript-agenttien luominen Visual Studio Codessa Microsoft 365 -agenttien Toolkitin avulla