Hurtigstart: Opprette og teste en grunnleggende agent

Denne hurtiginnføringen veileder deg gjennom oppretting av en egendefinert motoragent som svarer tilbake med meldingen du sender til den.

Forutsetning

• Python 3.9 eller nyere.

  • Hvis du vil installere Python, går du til https://www.python.org/downloads/og følger instruksjonene for operativsystemet.
  • Hvis du vil bekrefte versjonen, skriver du inn en terminalvindutype python --versioni en terminalvindu.

• Et koderedigeringsprogram du ønsker. Disse instruksjonene bruker Visual Studio Code.

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

Initialiser prosjektet og installer SDK

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

1. Åpne en terminal og opprett en ny mappe

   mkdir echo
   cd echo
   

2. Åpne mappen ved hjelp av Visual Studio Code ved hjelp av denne kommandoen:

   code .
   

3. Opprett 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 F1, skriv inn Python: Create environmentog trykk ENTER.

      1. Velg Venv for å opprette et .venv virtuelt miljø i gjeldende arbeidsområde.

      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 en Agents SDK

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

   pip install microsoft-agents-hosting-aiohttp
   

Opprett serverprogrammet, og importer de nødvendige bibliotekene

1. Opprett en fil med navnet 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. Opprett en fil med app.py følgende kode i samme katalog.

   # 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 instans av agenten som AgentApplication

Legg app.pytil følgende kode for å opprette AGENT_APP som en forekomst av AgentApplication, og implementer tre ruter for å svare på tre hendelser:

• Samtaleoppdatering
• meldingen /help
• alle andre aktiviteter

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 webserveren for å lytte i localhost:3978

På slutten av app.py, start webserveren ved å bruke start_server.

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

Kjør agenten lokalt i anonym modus

Kjør denne kommandoen fra terminalen:

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
   

   Note

   Denne kommandoen bruker npm fordi Microsoft 365 Agents Playground ikke er tilgjengelig ved hjelp av pip.

   Terminalen skal returnere noe sånt som:

   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 ved hjelp av denne kommandoen:

   teamsapptester
   

   Terminalen skal returnere noe sånt som:

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

Kommandoen teamsapptester åpner standardnettleseren og kobler til agenten.

Nå kan du sende en melding for å se ekkosvaret, eller sende meldingen /help for å se hvordan meldingen rutes til behandleren _help .

Neste trinn

Klargjør Azure Bot-ressurser som skal brukes med Agents SDK

Denne hurtiginnføringen veileder deg gjennom oppretting av en egendefinert motoragent som bare svarer med det du sender til den.

Forutsetning

• Node.js v22 eller nyere

  • Hvis du vil installere Node.js går du til nodejs.org og følger instruksjonene for operativsystemet.
  • Hvis du vil bekrefte versjonen, skriver du inn en terminalvindutype node --versioni en terminalvindu.

• Et koderedigeringsprogram du ønsker. Disse instruksjonene bruker Visual Studio Code.

Initialiser prosjektet og installer SDK

Brukes npm til å initialisere et node.js prosjekt ved å opprette en package.json og installere de nødvendige avhengighetene

1. Åpne en terminal og opprett en ny mappe

   mkdir echo
   cd echo
   

2. Initialiser node.js-prosjektet

   npm init -y
   

3. Installer en Agents SDK

   npm install @microsoft/agents-hosting-express
   

4. Åpne mappen ved hjelp av Visual Studio Code ved hjelp av denne kommandoen:

   code .
   

Importer de nødvendige bibliotekene

Opprett filen index.mjs , og importer følgende NPM-pakker til programkoden:

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

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

Implementere EchoAgent som en AgentApplication

I index.mjslegger du til følgende kode for å opprette EchoAgent utvidelsen av AgentApplication, og implementerer tre ruter for å svare på tre hendelser:

• Samtaleoppdatering
• meldingen /help
• alle andre aktiviteter

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 webserveren for å lytte i localhost:3978

Start webserveren ved slutten av index.mjs ved hjelp av startServer basert på Express, ved bruk av MemoryStorage som turn state storage.

startServer(new EchoAgent(new MemoryStorage()))

Kjør agenten lokalt i anonym modus

Kjør denne kommandoen fra terminalen:

node index.mjs

Terminalen skal returnere dette:

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 skal returnere noe sånt som:

   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 ved hjelp av denne kommandoen:

   node_modules/.bin/teamsapptester
   

   Terminalen skal returnere noe sånt som:

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

Kommandoen teamsapptester åpner standardnettleseren og kobler til agenten.

Nå kan du sende en melding for å se ekkosvaret, eller sende meldingen /help for å se hvordan meldingen rutes til behandleren _help .

Neste trinn

Klargjør Azure Bot-ressurser som skal brukes med Agents SDK

Denne quickstarten viser deg hvordan du laster ned og kjører QuickStart/Empty Agent-eksempelet fra GitHub.

Det finnes to hovedmåter å komme i gang med Microsoft 365 Agents SDK på:

• Klone og kjør eksempelet på QuickStart/Empty Agent-agenten som er tilgjengelig på GitHub

• Bruk Verktøysett for Microsoft 365 Agents. Agents Toolkit har to innebygde maler for Visual Studio og Visual Studio Code som bruker Microsoft 365 Agents SDK for å starte med en QuickStart/Empty Agent og en væragent som bruker Azure Foundry eller OpenAI Services med enten Semantic Kernel eller LangChain.

Forutsetning

Du trenger et par ting før du kommer i gang. Disse trinnene bruker quickstart/empty agent-eksemplet på .NET-hurtigstart, men du kan også bruke et hvilket som helst SDK-eksempel for agenter.

• .NET 8.0 SDK
• Visual Studio - eller Visual Studio-kode
• Kunnskap om ASP.NET kjerne og asynkron programmering i C#
• quickstart Last ned eksemplet fra GitHub

Åpne løsningen

1. Åpne løsningsfilen QuickStart.csproj i Visual Studio.

2. Kjør prosjektet.

På dette tidspunktet kjører agenten din lokalt ved hjelp av port 3978.

Test din agent lokalt

1. Installer Agents Playground hvis du ikke allerede har gjort det.

   winget install agentsplayground
   

2. Start agenten i Visual Studio eller Visual Studio Code

3. Start Teams-appens tester. Ved en ledetekst: agentsplayground

   • Verktøyet åpner en nettleser som viser Testverktøy for Teams App, klar til å sende meldinger til agenten din.

4. Din løpende agent på port 3978 skal koble automatisk til agentlekeplassen i nettleseren, og du bør kunne samhandle med agenten din som kjører lokalt

Hvordan fungerer agenten?

Med Agents SDK bygges en agent ved hjelp av AgentApplication - og AgentApplicationOptions-klasser . Dette er innebygd i Program.cs filen i eksemplet.

Bygg agenten din

Du kan se i eksemplet at når agenten bygges AgentApplicationOptions , lastes og den egendefinerte agentklassen MyAgent.cs som arver fra AgentApplication

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

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

Deretter lastes lagringsplassen inn som standard ved hjelp av MemoryStorage-klassen. Dette gjør at kontekst kan spores på tvers av svinger når du bruker TurnState , men bør byttes ut i produksjon for mer vedvarende lagring, for eksempel BlobsStorage eller CosmosDbPartitionedStorage.

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

Resten av agentprogrammet bruker standard .NET-vertsmønstre, og legger til ruter for å godta meldinger på et bestemt endepunkt. Disse rutene bruker IAgent-grensesnittet til å godta agentaktiviteten, og gir utviklere AgentApplication objektet til å arbeide med aktivitetsnyttelasten som ble sendt til den fra kanalen/klienten. Finn ut mer om aktiviteter og arbeid med aktiviteter

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

Legge til ny egendefinert logikk i en metode

Utviklere legger til egendefinert logikk i MyAgent.cs klassen som implementerer AgentApplication. Denne klassen bruker AgentApplicationOptions til å konfigurere bestemte innstillinger fra konfigurasjonen og Program.cs registrerer hendelseslyttere fra Agents SDK, som er tilgjengelig i AgentApplication klassen som refererer til den respektive egendefinerte metoden når disse hendelsene utløses fra klienten.

I eksemplet nedenfor utløser WelcomeMessageAsync metoden, og OnActivity utløser metoden OnMessageAsync.

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

Disse hendelsene rutes via endepunktet som er konfigurert i deg, MyProgram.cs og det finnes mange hendelser du kan bruke. Den vanligste er OnActivity. Hvis du vil lære mer om hendelsene som SDK implementerer, kan du se mer om hvordan du arbeider med aktiviteter og spesifikasjonen for aktivitetsprotokollen.

Når metoden utløses, for eksempel OnMessageAsync for å avslutte svingen, kan du velge i den egendefinerte logikken å svare for å sende en melding tilbake til klienten ved hjelp av metodene som er tilgjengelige på og forekomsten av TurnContext-klassen som skal være en parameter i metoden som vist i følgende eksempel:

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

Tips

Se gjennom de andre TurnContext-metodene som er tilgjengelige for å gå tilbake til klienten.

Nå vet du det grunnleggende, sjekk ut de neste trinnene og arbeid for å legge til egendefinert behandlingslogikk i agenten din og sende tilbake forskjellige hendelser.

Neste trinn

• Finn ut mer om aktiviteter og arbeid med aktiviteter
• Se gjennom AgentApplication-hendelsene du kan svare på fra klienten
• Se gjennom TurnContext-hendelsene du kan sende tilbake til klienten
• Klargjør Azure Bot-ressurser som skal brukes 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 én av følgende veiledninger hvis du vil komme i gang med verktøysettet:

• Opprett .NET-agenter i Visual Studio ved hjelp av Verktøysett for Microsoft 365 Agents
• Opprett JavaScript-agenter i Visual Studio Code med Microsoft 365 Agents Toolkit