Szybki start: tworzenie i testowanie agenta podstawowego

Ten szybki start przeprowadzi przez proces tworzenia agenta niestandardowego aparatu, który odpowiada dokładnie tym samym komunikatem, który do niego wysyłasz.

Wymagania wstępne

• Python 3.9 lub nowszy.

  • Aby zainstalować obsługę języka Python, przejdź do https://www.python.org/downloads/ i postępuj zgodnie z instrukcjami dotyczącymi swojego systemu operacyjnego.
  • Aby sprawdzić wersję, w oknie terminalu wpisz python --version.

• Dowolny edytor kodu. Te instrukcje korzystają z programu Visual Studio Code.

  Jeśli używasz Visual Studio Code, zainstaluj rozszerzenie Python

Zainicjalizuj projekt i zainstaluj zestaw SDK

Utwórz projekt w języku Python i zainstaluj wymagane zależności.

1. Otwórz terminal i utwórz nowy folder

   mkdir echo
   cd echo
   

2. Otwórz folder w Visual Studio Code, używając tego polecenia:

   code .
   

3. Stwórz wirtualne środowisko dowolną metodą i aktywuj je w Visual Studio Code lub w terminalu.

   Podczas korzystania z Visual Studio Code możesz skorzystać z tych kroków, jeśli zainstalowano rozszerzenie Python.

   1. Naciśnij F1, wpisz Python: Create environment a następnie naciśnij klawisz Enter.

      1. Wybierz Venv, aby utworzyć .venv środowisko wirtualne w bieżącym obszarze roboczym.

      2. Wybierz instalację języka Python, aby utworzyć środowisko wirtualne.

         Wartość może wyglądać następująco:

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

4. Instalowanie zestawu SDK agentów

   Użyj pip, aby zainstalować pakiet microsoft-agents-hosting-aiohttp za pomocą tego polecenia:

   pip install microsoft-agents-hosting-aiohttp
   

Utwórz aplikację serwerową i zaimportuj wymagane biblioteki

1. Utwórz plik o nazwie start_server.py, skopiuj poniższy kodu i wklej go w:

   # 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
   

   Ten kod definiuje funkcję start_server, której użyjemy w następnym pliku.

2. W tym samym katalogu utwórz plik o nazwie app.py z następującym kodem.

   # 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
   

Utwórz wystąpienie agenta jako AgentApplication

W pliku app.py dodaj następujący kod, aby utworzyć AGENT_APP jako instancję AgentApplication i zaimplementuj trzy trasy, aby odpowiadać na trzy zdarzenia:

• Aktualizacja konwersacji
• komunikat /help
• dowolne inne działanie

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

Uruchom serwer internetowy, aby nasłuchiwać na hoście lokalnym:3978

Na końcu kodu app.py uruchom serwer web, używając start_server.

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

Uruchamianie agenta lokalnie w trybie anonimowym

Z terminala wykonaj następujące polecenie:

python app.py

Terminal powinien zwrócić następującą treść:

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

Testowanie agenta lokalnie

1. Z innego terminala (aby utrzymać działanie agenta) zainstaluj środowisko testowe agentów usługi Microsoft 365 za pomocą następującego polecenia:

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

   Notatka

   To polecenie używa npm, ponieważ środowisko testowe agentów usługi Microsoft 365 nie jest dostępne przez pip.

   Terminal powinien zwrócić wynik podobny do:

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

2. Uruchom narzędzie testowe, aby przetestować agenta za pomocą tego polecenia:

   teamsapptester
   

   Terminal powinien zwrócić wynik podobny do:

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

Polecenie teamsapptester otwiera domyślną przeglądarkę i łączy się z agentem.

Teraz możesz wysłać dowolny komunikat, aby zobaczyć odpowiedź echo lub wysłać komunikat /help, aby zobaczyć, jak ten komunikat jest kierowany do _help programu obsługi.

Ten szybki start przeprowadzi przez proces tworzenia agenta niestandardowego aparatu, który odpowiada dokładnie tym samym komunikatem, który do niego wysyłasz.

Wymagania wstępne

• Node.js v22 lub nowszy

  • Aby zainstalować Node.js przejdź do nodejs.org i postępuj zgodnie z instrukcjami dotyczącymi systemu operacyjnego.
  • Aby sprawdzić wersję, w oknie terminalu wpisz node --version.

• Dowolny edytor kodu. Te instrukcje korzystają z programu Visual Studio Code.

Zainicjalizuj projekt i zainstaluj zestaw SDK

Użyj npm, aby zainicjować projekt Node.js przez utworzenie pliku package.json i instalację wymaganych zależności

1. Otwórz terminal i utwórz nowy folder

   mkdir echo
   cd echo
   

2. Zainicjalizuj projekt Node.js

   npm init -y
   

3. Instalowanie zestawu SDK agentów

   npm install @microsoft/agents-hosting-express
   

4. Otwórz folder w Visual Studio Code, korzystając z tego polecenia:

   code .
   

Importowanie wymaganych bibliotek

Utwórz plik index.mjs i zaimportuj następujące pakiety NPM do kodu swojej aplikacji:

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

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

Implementacja EchoAgent jako AgentApplikacation

W index.mjs dodaj następujący kod, aby utworzyć EchoAgent, rozszerzając AgentApplication i zaimplementuj trzy trasy, aby odpowiadać na trzy zdarzenia:

• Aktualizacja konwersacji
• komunikat /help
• dowolne inne działanie

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

Uruchom serwer internetowy, aby nasłuchiwać na hoście lokalnym:3978

Na końcu index.mjs uruchom serwer internetowy za pomocą startServer w oparciu o Express, używając MemoryStorage jako schowka stanu dla kolejki.

startServer(new EchoAgent(new MemoryStorage()))

Uruchamianie agenta lokalnie w trybie anonimowym

Z terminala wykonaj następujące polecenie:

node index.mjs

Terminal powinien wyświetlić:

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

Testowanie agenta lokalnie

1. Z innego terminala (aby utrzymać działanie agenta) zainstaluj środowisko testowe agentów usługi Microsoft 365 za pomocą następującego polecenia:

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

   Terminal powinien zwrócić wynik podobny do:

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

2. Uruchom narzędzie testowe, aby przetestować agenta za pomocą tego polecenia:

   node_modules/.bin/teamsapptester
   

   Terminal powinien zwrócić wynik podobny do:

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

Polecenie teamsapptester otwiera domyślną przeglądarkę i łączy się z agentem.

Teraz możesz wysłać dowolny komunikat, aby zobaczyć odpowiedź echo lub wysłać komunikat /help, aby zobaczyć, jak ten komunikat jest kierowany do _help programu obsługi.

Ten szybki start przeprowadzi przez proces tworzenia agenta niestandardowego aparatu, który odpowiada dokładnie tym samym komunikatem, który do niego wysyłasz.

Wymagania wstępne

• .NET 8.0 SDK lub nowszy

  • Aby zainstalować zestaw SDK .NET, przejdź do dotnet.microsoft.com i postępuj zgodnie z instrukcjami dotyczącymi swojego systemu operacyjnego.
  • Aby sprawdzić wersję, w oknie terminalu wpisz dotnet --version.

• Dowolny edytor kodu. Te instrukcje korzystają z programu Visual Studio Code.

Zainicjalizuj projekt i zainstaluj zestaw SDK

Użyj dotnet do stworzenia nowego projektu aplikacji internetowej i zainstaluj wymagane zależności.

1. Otwórz terminal i utwórz nowy folder

   mkdir echo
   cd echo
   

2. Zainicjalizuj projekt .NET

   dotnet new web
   

3. Instalowanie zestawu SDK agentów

   dotnet add package Microsoft.Agents.Hosting.AspNetCore
   

4. Otwórz folder w Visual Studio Code, używając tego polecenia:

   code .
   

Importowanie wymaganych bibliotek

W Program.cs, zastąp istniejącą zawartość i dodaj następujące using instrukcje importujące pakiety SDK do kodu aplikacji:

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

Implementacja EchoAgent jako AgentApplikacation

W Program.cs pliku, po instrukcjach using, dodaj następujący kod, aby utworzyć EchoAgent rozszerzając AgentApplication i zaimplementuj ścieżki, aby odpowiadać na zdarzenia:

• Aktualizacja konwersacji
• Dowolne inne działanie

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

Skonfiguruj serwer WWW i zarejestruj aplikację agenta

W Program.cspliku po instrukcjach using dodaj następujący kod, aby skonfigurować hosta internetowego, zarejestrować agenta i zamapować /api/messages punkt końcowy:

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

Uruchom serwer internetowy, aby nasłuchiwać na hoście lokalnym: 3978

W launchSettings.json zaktualizuj applicationURL do http://localhost:3978, aby aplikacja nasłuchiwała na właściwym porcie.

Uruchamianie agenta lokalnie w trybie anonimowym

Z terminala wykonaj następujące polecenie:

dotnet run

Terminal powinien zwrócić wynik podobny do:

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

Testowanie agenta lokalnie

1. Z innego terminala (aby utrzymać działanie agenta) zainstaluj środowisko testowe agentów usługi Microsoft 365 za pomocą następującego polecenia:

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

   Notatka

   To polecenie używa npm, ponieważ środowisko testowe agentów usługi Microsoft 365 jest dystrybuowany jako pakiet npm.

   Terminal powinien zwrócić wynik podobny do:

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

2. Uruchom narzędzie testowe, aby przetestować agenta za pomocą tego polecenia:

   teamsapptester
   

   Terminal powinien zwrócić wynik podobny do:

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

Polecenie teamsapptester otwiera domyślną przeglądarkę i łączy się z agentem.

W danych wejściowych tekstowych wprowadź i wyślij dowolną wiadomość, aby zobaczyć odpowiedź echo.

Następne kroki

• Sprawdź przykłady zestawu SDK agentów na GitHub
• Dowiedz się więcej o obiektach Activities i pracy z nimi
• Przejrzyj zdarzenia AgentApplication, na które klient może odpowiedzieć
• Przejrzyj zdarzenia TurnContext, które możesz odesłać klientowi
• Inicjowanie obsługi bota platformy Azure do użycia z zestawem SDK agentów
• Konfigurowanie agenta .NET do używania protokołu OAuth

Środowisko testowe agentów jest domyślnie dostępne, jeśli używasz już zestawu narzędzi Microsoft 365 Agents Toolkit. Możesz skorzystać z jednego z poniższych przewodników, jeśli chcesz rozpocząć pracę z zestawem narzędzi.

• Tworzenie agentów .NET w programie Visual Studio przy użyciu zestawu narzędzi agentów usługi Microsoft 365
• Tworzenie agentów języka JavaScript w programie Visual Studio Code przy użyciu zestawu narzędzi agentów usługi Microsoft 365