Snabbstart: Skapa och testa en grundläggande agent

Denna snabbstart guidar dig genom att skapa en anpassad motoragent som svarar med det meddelande du skickar till den.

Krav

  • Python 3.9 eller nyare.

    • För att installera Python, gå till https://www.python.org/downloads/ och följ instruktionerna för ditt operativsystem.
    • För att kontrollera versionen, skriv python --version i terminalfönstret.

  • En valfri kodeditor. Dessa instruktioner använder Visual Studio Code.

    Om du använder Visual Studio Code, installera Python-tillägget

Initiera projektet och installera SDK:n

Skapa ett Python-projekt och installera de nödvändiga beroenden.

  1. Öppna en terminal och skapa en ny mapp

    mkdir echo
cd echo

  2. Öppna mappen i Visual Studio Code med följande kommando:

    code .

  3. Skapa en virtuell miljö med den metod du väljer och aktivera den antingen via Visual Studio Code eller i en terminal.

    När du använder Visual Studio Code kan du använda dessa steg med Python-tillägget installerat.

    1. Tryck på F1, skriv in Python: Create environment och tryck på Retur.

      1. Välj Venv för att skapa en .venv virtuell miljö i den aktuella arbetsytan.

      2. Välj en Python-installation för att skapa en virtuell miljö.

        Värdet kan se ut så här:

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

  4. Installera SDK för agenter

    Använd pip för att installera paketet microsoft-agents-hosting-aiohttp med detta kommando:

    pip install microsoft-agents-hosting-aiohttp

Skapa serverapplikationen och importera de nödvändiga biblioteken

  1. Skapa en fil som du kallar start_server.py, kopiera följande kod och klistra in 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

    Den här koden definierar en start_server funktion som vi kommer att använda i nästa fil.

  2. I samma katalog skapar du en fil med namnet app.py, med följande kod.

    # 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

Skapa en instans av agenten som en AgentApplication

I app.py, lägg till följande kod för att skapa AGENT_APP som en instans av AgentApplication, och implementera tre rutter för att svara på tre händelser:

  • Konversationsuppdatering
  • meddelandet /help
  • valfri annan 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}")

Starta webbservern så att den lyssnar på localhost:3978

I slutet av app.py, starta webbservern med start_server.

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

Kör agenten lokalt i anonymt läge

Från din terminal, kör detta kommando:

python app.py

Terminalen ska returnera följande:

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

Testa agenten lokalt

  1. Från en annan terminal (för att hålla agenten igång) installera Microsoft 365 Agents Playground med detta kommando:

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

    Kommentar

    Detta kommando använder npm eftersom Microsoft 365 Agents Playground inte är tillgänglig med pip.

    Terminalen bör returnera något 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 testverktyget för att interagera med din agent med detta kommando:

    teamsapptester

    Terminalen bör returnera något 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\"}"}}

Kommandot teamsapptester öppnar din standardwebbläsare och ansluter till din agent.

Agenten i agentens testplats

Nu kan du skicka vilket meddelande som helst för att se ekosvaret, eller skicka meddelandet /help för att se hur det meddelandet dirigeras till hanteraren _help.

Denna snabbstart guidar dig genom att skapa en anpassad motoragent som svarar med det meddelande du skickar till den.

Krav

  • Node.js v22 eller nyare

    • För att installera Node.js, gå till nodejs.org, och följ instruktionerna för ditt operativsystem.
    • För att kontrollera versionen, skriv node --version i terminalfönstret.

  • En valfri kodeditor. Dessa instruktioner använder Visual Studio Code.

Initiera projektet och installera SDK:n

Använd npm för att initiera ett Node.js-projekt genom att skapa en package.json och installera nödvändiga beroenden

  1. Öppna en terminal och skapa en ny mapp

    mkdir echo
cd echo

  2. Initiera Node.js-projektet

    npm init -y

  3. Installera SDK för agenter

    npm install @microsoft/agents-hosting-express

  4. Öppna mappen med Visual Studio Code med följande kommando:

    code .

Importera nödvändiga bibliotek

Skapa filen index.mjs och importera följande NPM-paket i din applikationskod:

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

Implementera EchoAgent som klassen AgentApplication

I index.mjs, lägg till följande kod för att skapa EchoAgent som en instans av AgentApplication, och implementera tre rutter för att svara på tre händelser:

  • Konversationsuppdatering
  • meddelandet /help
  • valfri annan 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)
  }
}

Starta webbservern så att den lyssnar på localhost:3978

I slutet av index.mjs starta webbservern med startServer, som bygger på express och använder MemoryStorage för att lagra turens tillstånd.

startServer(new EchoAgent(new MemoryStorage()))

Kör agenten lokalt i anonymt läge

Från din terminal, kör detta kommando:

node index.mjs

Terminalen bör returnera detta:

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

Testa agenten lokalt

  1. Från en annan terminal (för att hålla agenten igång) installera Microsoft 365 Agents Playground med detta kommando:

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

    Terminalen bör returnera något 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 testverktyget för att interagera med din agent med detta kommando:

    node_modules/.bin/teamsapptester

    Terminalen bör returnera något 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\"}"}}

Kommandot teamsapptester öppnar din standardwebbläsare och ansluter till din agent.

Agenten i agentens testplats

Nu kan du skicka vilket meddelande som helst för att se ekosvaret, eller skicka meddelandet /help för att se hur det meddelandet dirigeras till hanteraren _help.

Denna snabbstart guidar dig genom att skapa en anpassad motoragent som svarar med det meddelande du skickar till den.

Krav

  • .NET 8.0 SDK eller nyare

    • För att installera .NET SDK:n, gå till dotnet.microsoft.com och följ instruktionerna för ditt operativsystem.
    • För att kontrollera versionen, skriv dotnet --version i terminalfönstret.

  • En valfri kodeditor. Dessa instruktioner använder Visual Studio Code.

Initiera projektet och installera SDK:n

Använd dotnet för att skapa ett nytt webbprojekt och installera de nödvändiga beroendena.

  1. Öppna en terminal och skapa en ny mapp

    mkdir echo
cd echo

  2. Initiera .NET-projektet

    dotnet new web

  3. Installera SDK för agenter

    dotnet add package Microsoft.Agents.Hosting.AspNetCore

  4. Öppna mappen i Visual Studio Code med följande kommando:

    code .

Importera nödvändiga bibliotek

I Program.cs, ersätt det befintliga innehållet och lägg till följande using satser för att importera SDK-paketen i din applikationskod:

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

Implementera EchoAgent som klassen AgentApplication

I Program.cs, efter satserna using, lägg till följande kod för att skapa EchoAgent som utökar AgentApplication och implementera rutter för att svara på händelser:

  • Konversationsuppdatering
  • Valfri annan 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);
   }
}

Konfigurera webbservern och registrera agentapplikationen

I Program.cs, efter using-satserna, lägg till följande kod för att konfigurera webbservern, registrera agenten och mappa /api/messages-slutpunkten:

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

Ställ in webbservern att lyssna på localhost:3978

I launchSettings.json, uppdatera applicationURL till http://localhost:3978 så att appen lyssnar på rätt port.

Kör agenten lokalt i anonymt läge

Från din terminal, kör detta kommando:

dotnet run

Terminalen bör returnera något i stil med:

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

Testa agenten lokalt

  1. Från en annan terminal (för att hålla agenten igång) installera Microsoft 365 Agents Playground med följande kommando:

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

    Kommentar

    Detta kommando använder npm eftersom Microsoft 365 Agents Playground distribueras som ett npm-paket.

    Terminalen bör returnera något 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 testverktyget för att interagera med din agent med detta kommando:

    teamsapptester

    Terminalen bör returnera något 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\"}"}}

Kommandot teamsapptester öppnar din standardwebbläsare och ansluter till din agent.

Agenten i agentens testplats

I textinmatningen, skriv in och skicka ett meddelande för att se echo-svaret.

Nästa steg

Agents Playground finns tillgänglig som standard om du redan använder Microsoft 365 Agents Toolkit. Du kan använda en av följande guider om du vill komma igång med verktygslådan:

  • Last updated on