Hurtigstart: Opprett og test en grunnleggende agent

Denne hurtigstarten veileder deg gjennom å lage en egendefinert motoragent som svarer med den meldingen du sender til den.

Forutsetning

• Python 3.9 eller nyere.

  • For å installere Python går du til https://www.python.org/downloads/ og følger instruksjonene for operativsystemet ditt.
  • For å verifisere versjonen skriver du inn python --version i et terminalvindu.

• En koderedigeringsprogrammet etter eget valg. Disse instruksjonene bruker Visual Studio Code.

  Hvis du bruker Visual Studio Code, installerer du Python-utvidelsen

Initialiser prosjektet og installer SDK-en

Opprett et Python-prosjekt og installer de nødvendige avhengighetene.

1. Åpne en terminal og lag en ny mappe

   mkdir echo
   cd echo
   

2. Åpne mappen med Visual Studio Code ved å bruke denne kommandoen:

   code .
   

3. Lag et virtuelt miljø med metoden du ønsker, og aktiver det enten via Visual Studio Code eller i en terminal.

   Når du bruker Visual Studio Code, kan du bruke disse trinnene med Python-utvidelsen installert.

   1. Trykk på F1, angi Python: Create environment, og trykk på Enter.

      1. Velg Venv for å opprette et .venv virtuelt miljø i det nåværende arbeidsområdet.

      2. Velg en Python-installasjon for å opprette det virtuelle miljøet.

         Verdien kan se slik ut:

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

4. Installer SDK-en for agenter

   Bruk pip til å installere microsoft-agents-hosting-aiohttp-pakken med denne kommandoen:

   pip install microsoft-agents-hosting-aiohttp
   

Opprett serverappen og importer de nødvendige bibliotekene

1. Opprett en fil kalt start_server.py, kopier følgende kode og lim den inn i:

   # 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
   

   Denne koden definerer en start_server- funksjon vi skal bruke i neste fil.

2. I samme katalog oppretter du en fil med navnet app.py og legger inn følgende kode.

   # 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
   

Opprett en forekomst av agenten som en AgentApplication

I app.py legger du til følgende kode for å opprette AGENT_APP som en forekomst av AgentApplication, og implementer tre ruter for å svare på tre hendelser:

• Samtaleoppdatering
• meldingen /help
• enhver annen aktivitet

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 nettserveren for å lytte på localhost:3978

Etter at app.py er ferdig, starter nettserveren med start_server.

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

Kjør agenten lokalt i anonym modus

I terminalen skriver du inn denne kommandoen:

python app.py

Terminalen skal returnere følgende:

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

Test agenten lokalt

1. Fra en annen terminal (for å holde agenten i gang) installerer du Microsoft 365 Agents Playground med denne kommandoen:

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

   Notat

   Denne kommandoen bruker npm fordi Microsoft 365 Agents Playground ikke er tilgjengelig med pip.

   Terminalen vil gi et resultat som ligner på:

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. Kjør testverktøyet for å samhandle med agenten din ved å bruke denne kommandoen:

   teamsapptester
   

   Terminalen vil gi et resultat som ligner på:

   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-kommandoen åpner standardnettleseren og kobler til agenten.

Nå kan du sende en hvilken som helst melding for å se ekkosvaret eller sende meldingen /help for å se hvordan den rutes til _help-behandlingsprogrammet.

Denne hurtigstarten veileder deg gjennom å lage en egendefinert motoragent som svarer med den meldingen du sender til den.

Forutsetning

• Node.js v22 eller nyere

  • For å installere Node.js går du til nodejs.org og følger instruksjonene for operativsystemet ditt.
  • For å verifisere versjonen skriver du inn node --version i et terminalvindu.

• En koderedigeringsprogrammet etter eget valg. Disse instruksjonene bruker Visual Studio Code.

Initialiser prosjektet og installer SDK-en

Bruk npm til å initialisere et Node.js-prosjekt ved å opprette en package.json og installere nødvendige avhengigheter

1. Åpne en terminal og lag en ny mappe

   mkdir echo
   cd echo
   

2. Initialiser Node.js-prosjektet

   npm init -y
   

3. Installer SDK-en for agenter

   npm install @microsoft/agents-hosting-express
   

4. Åpne mappen i Visual Studio Code med denne kommandoen:

   code .
   

Importer de nødvendige bibliotekene

Opprett filen index.mjs og importer følgende NPM-pakker i appkoden din:

• @microsoft/agents-hosting
• @microsoft/agents-hosting-express

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

Implementer EchoAgent som AgentApplication

I index.mjs legger du til følgende kode for å opprette EchoAgent som utvider AgentApplication, og implementer tre ruter for å svare på tre hendelser:

• Samtaleoppdatering
• meldingen /help
• enhver annen aktivitet

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 nettserveren for å lytte på localhost:3978

På slutten av index.mjs starter du nettserveren ved å bruke startServer, basert på express og med MemoryStorage som lagring av omgangstilstand.

startServer(new EchoAgent(new MemoryStorage()))

Kjør agenten lokalt i anonym modus

I terminalen skriver du inn denne kommandoen:

node index.mjs

Terminalen skal vise følgende:

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

Test agenten lokalt

1. Fra en annen terminal (for å holde agenten i gang) installerer du Microsoft 365 Agents Playground med denne kommandoen:

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

   Terminalen vil gi et resultat som ligner på:

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. Kjør testverktøyet for å samhandle med agenten din ved å bruke denne kommandoen:

   node_modules/.bin/teamsapptester
   

   Terminalen vil gi et resultat som ligner på:

   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-kommandoen åpner standardnettleseren og kobler til agenten.

Nå kan du sende en hvilken som helst melding for å se ekkosvaret eller sende meldingen /help for å se hvordan den rutes til _help-behandlingsprogrammet.

Denne hurtigstarten veileder deg gjennom å lage en egendefinert motoragent som svarer med den meldingen du sender til den.

Forutsetning

• .NET 8.0 SDK eller nyere

  • For å installere .NET SDK går du til dotnet.microsoft.com og følger instruksjonene for operativsystemet ditt.
  • For å verifisere versjonen skriver du inn dotnet --version i et terminalvindu.

• En koderedigeringsprogrammet etter eget valg. Disse instruksjonene bruker Visual Studio Code.

Initialiser prosjektet og installer SDK-en

Bruk dotnet for å opprette et nytt nettprosjekt og installere de nødvendige avhengighetene.

1. Åpne en terminal og lag en ny mappe

   mkdir echo
   cd echo
   

2. Initialiser .NET-prosjektet

   dotnet new web
   

3. Installer SDK-en for agenter

   dotnet add package Microsoft.Agents.Hosting.AspNetCore
   

4. Åpne mappen med Visual Studio Code ved å bruke denne kommandoen:

   code .
   

Importer de nødvendige bibliotekene

I Program.cs erstatter du det eksisterende innholdet og legger til følgende using-setninger for å importere SDK-pakkene i appkoden din:

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

Implementer EchoAgent som AgentApplication

I Program.cs, etter using-setningene, legger du til følgende kode for å opprette EchoAgent som utvider AgentApplication, og implementer tre ruter for å svare på tre hendelser:

• Samtaleoppdatering
• Alle andre aktiviteter

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

Sett opp nettserveren og registrer agentappen

I Program.cs, etter using-setningene, legger du til følgende kode for å konfigurere nettserveren, registrere agenten og mappen /api/messages-endepunktet:

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

Sett nettserveren til å lytte på localhost:3978

I launchSettings.json oppdaterer du applicationURL til http://localhost:3978 slik at appen lytter på riktig port.

Kjør agenten lokalt i anonym modus

I terminalen skriver du inn denne kommandoen:

dotnet run

Terminalen vil gi et resultat som ligner på:

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

Test agenten lokalt

1. Fra en annen terminal (for å holde agenten i gang) installerer du Microsoft 365 Agents Playground med følgende kommando:

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

   Notat

   Denne kommandoen bruker npm fordi Microsoft 365 Agents Playground rulles ut som en npm-pakke.

   Terminalen vil gi et resultat som ligner på:

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. Kjør testverktøyet for å samhandle med agenten din ved å bruke denne kommandoen:

   teamsapptester
   

   Terminalen vil gi et resultat som ligner på:

   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-kommandoen åpner standardnettleseren og kobler til agenten.

Skriv inn og send en hvilken som helst melding i tekstfeltet for å se ekkosvaret.

Neste trinn

• Sjekk ut eksempler på Agents SDK på GitHub
• Lær mer om aktiviteter og hvordan du arbeider med aktiviteter
• Gå gjennom AgentApplication-hendelsene du kan svare på fra klienten
• Gå gjennom TurnContext-hendelsene du kan sende tilbake til klienten
• Klargjør Azure Bot-ressurser for bruk med Agents SDK
• Konfigurer .NET-agenten til å bruke OAuth

Agents Playground er tilgjengelig som standard hvis du allerede bruker Microsoft 365 Agents Toolkit. Du kan bruke en av følgende veiledninger hvis du vil komme i gang med verktøykassen:

• Opprett .NET-agenter i Visual Studio med verktøysettet for Microsoft 365-agenter
• Opprett JavaScript-agenter i Visual Studio Code med verktøysettet for Microsoft 365-agenter