Hurtig start: Opret og test en basisagent

Denne hurtige introduktion hjælper dig med at oprette en brugerdefineret programagent , der svarer tilbage med den meddelelse, du sender til den.

Forudsætninger

• Python 3.9 eller nyere.

  • Hvis du vil installere Python, skal du gå til https://www.python.org/downloads/og følge vejledningen til operativsystemet.
  • Du kan kontrollere versionen ved at skrive python --versioni et terminalvindue.

• En kodeeditor efter eget valg. I denne vejledning bruges Visual Studio Code.

  Hvis du bruger Visual Studio Code, skal du installere Python-udvidelsen

Initialiser projektet, og installér SDK'et

Opret et Python-projekt, og installér de påkrævede afhængigheder.

1. Åbn en terminal, og opret en ny mappe

   mkdir echo
   cd echo
   

2. Åbn mappen ved hjælp af Visual Studio Code ved hjælp af denne kommando:

   code .
   

3. Opret et virtuelt miljø med den valgte metode, og aktivér det enten via Visual Studio Code eller i en terminal.

   Når du bruger Visual Studio Code, kan du bruge disse trin, når Python-udvidelsen er installeret.

   1. Tryk på F1, skriv Python: Create environment, og tryk på Enter.

      1. Vælg Venv for at oprette et .venv virtuelt miljø i det aktuelle arbejdsområde.

      2. Vælg en Python-installation for at oprette det virtuelle miljø.

         Værdien kan se sådan ud:

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

4. Installér Agents SDK

   Brug pip til at installere pakken microsoft-agents-hosting-aiohttp med denne kommando:

   pip install microsoft-agents-hosting-aiohttp
   

Opret serverprogrammet, og importér de påkrævede biblioteker

1. Opret en fil med navnet start_server.py, kopiér følgende kode, og indsæt den 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 kode definerer en start_server funktion, vi skal bruge i den næste fil.

2. Opret en fil med følgende app.py kode i den samme mappe.

   # 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
   

Opret en forekomst af agenten som en AgentApplication

I app.pyskal du tilføje følgende kode for at oprette AGENT_APP som en forekomst af AgentApplicationog implementere tre ruter for at reagere på tre hændelser:

• Opdatering af samtale
• meddelelsen /help
• enhver anden 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 webserveren for at lytte i localhost:3978

I slutningen af app.pyskal du starte webserveren ved hjælp af start_server.

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

Kør agenten lokalt i anonym tilstand

Kør denne kommando 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 anden terminal (for at holde agenten kørende) skal du installere Microsoft 365 Agents Playground med denne kommando:

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

   Notat

   Denne kommando bruger npm, fordi Microsoft 365 Agents Playground ikke er tilgængelig ved hjælp af pip.

   Terminalen skal returnere noget i stil med:

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

2. Kør testværktøjet for at interagere med agenten ved hjælp af denne kommando:

   teamsapptester
   

   Terminalen skal returnere noget i stil med:

   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 åbner standardbrowseren og opretter forbindelse til din agent.

Nu kan du sende en hvilken som helst meddelelse for at se ekkosvaret eller sende meddelelsen /help for at se, hvordan meddelelsen distribueres til handleren _help .

Denne hurtige introduktion hjælper dig med at oprette en brugerdefineret programagent , der svarer tilbage med den meddelelse, du sender til den.

Forudsætninger

• Node.js v22 eller nyere

  • Hvis du vil installere Node.js skal du gå til nodejs.org og følge vejledningen til operativsystemet.
  • Du kan kontrollere versionen ved at skrive node --versioni et terminalvindue.

• En kodeeditor efter eget valg. I denne vejledning bruges Visual Studio Code.

Initialiser projektet, og installér SDK'et

Bruges npm til at initialisere et node.js projekt ved at oprette en package.json og installere de påkrævede afhængigheder

1. Åbn en terminal, og opret en ny mappe

   mkdir echo
   cd echo
   

2. Initialiser det node.js projekt

   npm init -y
   

3. Installér Agents SDK

   npm install @microsoft/agents-hosting-express
   

4. Åbn mappen ved hjælp af Visual Studio Code ved hjælp af denne kommando:

   code .
   

Importér de påkrævede biblioteker

Opret filen index.mjs , og importér følgende NPM-pakker i programkoden:

• @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 en AgentApplication

I index.mjsskal du tilføje følgende kode for at oprette udvidelsen af EchoAgentAgentApplication og implementere tre ruter for at reagere på tre hændelser:

• Opdatering af samtale
• meddelelsen /help
• enhver anden 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 webserveren for at lytte i localhost:3978

Ved slutningen af index.mjs startes webserveren ved hjælp af startServer baseret på Express ved brug af MemoryStorage som lagring for tilstandsændringer.

startServer(new EchoAgent(new MemoryStorage()))

Kør agenten lokalt i anonym tilstand

Kør denne kommando fra terminalen:

node index.mjs

Terminalen skal returnere følgende:

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

Test agenten lokalt

1. Fra en anden terminal (for at holde agenten kørende) skal du installere Microsoft 365 Agents Playground med denne kommando:

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

   Terminalen skal returnere noget i stil med:

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

2. Kør testværktøjet for at interagere med agenten ved hjælp af denne kommando:

   node_modules/.bin/teamsapptester
   

   Terminalen skal returnere noget i stil med:

   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 åbner standardbrowseren og opretter forbindelse til din agent.

Nu kan du sende en hvilken som helst meddelelse for at se ekkosvaret eller sende meddelelsen /help for at se, hvordan meddelelsen distribueres til handleren _help .

Denne hurtige introduktion hjælper dig med at oprette en brugerdefineret programagent , der svarer tilbage med den meddelelse, du sender til den.

Forudsætninger

• .NET 8.0 SDK eller nyere

  • Hvis du vil installere .NET SDK, skal du gå til dotnet.microsoft.com og følge vejledningen til operativsystemet.
  • Du kan kontrollere versionen ved at skrive dotnet --versioni et terminalvindue.

• En kodeeditor efter eget valg. I denne vejledning bruges Visual Studio Code.

Initialiser projektet, og installér SDK'et

Bruges dotnet til at oprette et nyt webprojekt og installere de påkrævede afhængigheder.

1. Åbn en terminal, og opret en ny mappe

   mkdir echo
   cd echo
   

2. Initialiser .NET-projektet

   dotnet new web
   

3. Installér Agents SDK

   dotnet add package Microsoft.Agents.Hosting.AspNetCore
   

4. Åbn mappen ved hjælp af Visual Studio Code ved hjælp af denne kommando:

   code .
   

Importér de påkrævede biblioteker

I Program.csskal du erstatte det eksisterende indhold og tilføje følgende using sætninger for at importere SDK-pakkerne i programkoden:

// 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 en AgentApplication

I Program.csskal du tilføje følgende kode efter sætningerne using for at oprette den EchoAgent udvidede AgentApplication og implementere ruter for at reagere på hændelser:

• Opdatering af samtale
• Enhver anden aktivitet

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

Konfigurer webserveren, og registrer agentprogrammet

I Program.csskal du tilføje følgende kode efter sætningerne using for at konfigurere webværten, registrere agenten og tilknytte slutpunktet /api/messages :

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

Indstil webserveren til at lytte i localhost:3978

I launchSettings.jsonskal du applicationURL opdatere til http://localhost:3978 , så appen lytter på den korrekte port.

Kør agenten lokalt i anonym tilstand

Kør denne kommando fra terminalen:

dotnet run

Terminalen skal returnere noget i stil med:

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

Test agenten lokalt

1. Fra en anden terminal (for at holde agenten kørende) skal du installere Microsoft 365 Agents Playground med følgende kommando:

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

   Notat

   Denne kommando bruger npm, fordi Microsoft 365 Agents Playground distribueres som en npm-pakke.

   Terminalen skal returnere noget i stil med:

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

2. Kør testværktøjet for at interagere med agenten ved hjælp af denne kommando:

   teamsapptester
   

   Terminalen skal returnere noget i stil med:

   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 åbner standardbrowseren og opretter forbindelse til din agent.

I tekstinputtet skal du angive og sende en meddelelse for at se ekkosvaret.

Næste trin

• Se Eksempler på Agents SDK på GitHub
• Få mere at vide om aktiviteter og arbejde med aktiviteter
• Gennemse de AgentApplication-hændelser, du kan svare på fra klienten
• Gennemse De TurnContext-hændelser, du kan sende tilbage til klienten
• Klargør Azure Bot-ressourcer, der skal bruges sammen med Agents SDK
• Konfigurer .NET Agent til at bruge OAuth

Agents Playground er som standard tilgængelig, hvis du allerede bruger Microsoft 365 Agents Toolkit. Du kan bruge en af følgende vejledninger, hvis du vil i gang med værktøjskassen:

• Opret .NET-agenter i Visual Studio ved hjælp af Microsoft 365 Agents Toolkit
• Opret JavaScript-agenter i Visual Studio Code med Microsoft 365 Agents Toolkit