Udostępnij przez

Szybki start: tworzenie i testowanie podstawowego agenta

Ten przewodnik szybkiego startu przeprowadzi Cię przez proces tworzenia niestandardowego agenta silnika, który odpowiada, używając dowolnego wysyłanego komunikatu.

Wymagania wstępne

Inicjowanie projektu i instalowanie zestawu 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 przy użyciu programu Visual Studio Code, używając następującego polecenia:

    code .

  3. Utwórz środowisko wirtualne przy użyciu wybranej metody i aktywuj je za pomocą programu Visual Studio Code lub w terminalu.

    W przypadku korzystania z programu Visual Studio Code możesz użyć tych kroków z zainstalowanym rozszerzeniem języka Python .

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

      1. Wybierz Venv, żeby 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. Zainstaluj zestaw SDK agentów

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

    pip install microsoft-agents-hosting-aiohttp

Tworzenie aplikacji serwera i importowanie wymaganych bibliotek

  1. Utwórz plik o nazwie start_server.py, skopiuj następujący kod i wklej go:

    # 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 start_server funkcję, która zostanie użyta 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 AgentAplication

W app.py dodaj następujący kod, aby utworzyć AGENT_APP jako instancję AgentApplication, i zaimplementuj trzy ścieżki, aby reagować na trzy zdarzenia:

  • Aktualizacja konwersacji
  • komunikat /help
  • wszelkie inne działania
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 WWW do nasłuchu na hoście lokalnym na porcie 3978

Na końcu app.py uruchom serwer WWW przy użyciu start_server.

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

Uruchamianie agenta lokalnie w trybie anonimowym

W terminalu uruchom następujące polecenie:

python app.py

Terminal powinien zwrócić następujące informacje:

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

Przetestuj agenta lokalnie

  1. Z innego terminala (aby agent nadal działał) zainstaluj Microsoft 365 Agents Playground za pomocą następującego polecenia:

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

    Uwaga / Notatka

    To polecenie używa narzędzia npm, ponieważ Microsoft 365 Agents Playground nie jest dostępny przy użyciu pip.

    Terminal powinien zwrócić następujący kod:

    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 wchodzić w interakcję z agentem przy użyciu tego polecenia:

    teamsapptester

    Terminal powinien zwrócić następujący kod:

    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 nawiązuje połączenie z agentem.

Twój agent na placu zabaw agentów

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

Dalsze kroki

Aprowizuj zasoby usługi Azure Bot do użycia z zestawem SDK agentów

Ten przewodnik szybkiego startu przeprowadzi Cię przez proces tworzenia niestandardowego agenta silnika, który odpowiada tym, co do niego wyślesz.

Wymagania wstępne

  • Node.js w wersji 22 lub nowszej

    • 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.

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

Inicjowanie projektu i instalowanie zestawu SDK

Użyj npm do zainicjowania projektu node.js, tworząc plik package.json i instalując wymagane zależności

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

    mkdir echo
cd echo

  2. Inicjowanie projektu node.js

    npm init -y

  3. Zainstaluj zestaw SDK agentów

    npm install @microsoft/agents-hosting-express

  4. Otwórz folder przy użyciu programu Visual Studio Code, używając następującego polecenia:

    code .

Importowanie wymaganych bibliotek

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

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

Implementacja EchoAgent jako AgentAplikacation

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

  • Aktualizacja konwersacji
  • komunikat /help
  • wszelkie inne działania
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 WWW do nasłuchu na hoście lokalnym na porcie 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

W terminalu uruchom następujące polecenie:

node index.mjs

Terminal powinien zwrócić następujący wynik:

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

Przetestuj agenta lokalnie

  1. Z innego terminala (aby agent nadal działał) zainstaluj Microsoft 365 Agents Playground za pomocą następującego polecenia:

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

    Terminal powinien zwrócić następujący kod:

    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 wchodzić w interakcję z agentem przy użyciu tego polecenia:

    node_modules/.bin/teamsapptester

    Terminal powinien zwrócić następujący kod:

    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 nawiązuje połączenie z agentem.

Twój agent na placu zabaw agentów

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

Dalsze kroki

Aprowizuj zasoby usługi Azure Bot do użycia z zestawem SDK agentów

Ten szybki start pokazuje, jak pobrać i uruchomić próbkę QuickStart/Empty Agent z GitHuba.

Istnieją dwa główne sposoby rozpoczęcia pracy z zestawem SDK agentów platformy Microsoft 365:

  • Sklonuj i uruchom przykładowego agenta QuickStart/Empty Agent dostępnego na GitHub

  • Użyj zestawu narzędzi Microsoft 365 Agents Toolkit. Zestaw narzędzi Agents Toolkit zawiera dwa wbudowane szablony dla programów Visual Studio i Visual Studio Code, które wykorzystują Microsoft 365 Agents SDK do rozpoczęcia pracy z agentem typu QuickStart/Empty oraz agentem pogodowym. Drugi z nich korzysta z usług Azure Foundry lub OpenAI oraz wykorzystuje Semantic Kernel lub LangChain.

Wymagania wstępne

Zanim zaczniesz pracę, potrzebujesz kilku rzeczy. Te kroki wykorzystują przykładową aplikację QuickStart/Empty Agent w szybkim przewodniku .NET, ale można również użyć dowolnego przykładu z zestawu SDK dla agentów.

Otwieranie rozwiązania

  1. Otwórz plik QuickStart.csproj rozwiązania w programie Visual Studio.

  2. Uruchamianie projektu.

Na tym etapie agent działa lokalnie przy użyciu portu 3978.

Przetestuj agenta lokalnie

  1. Zainstaluj Agents Playground, jeśli jeszcze nie został zainstalowany.

    winget install agentsplayground

  2. Uruchamianie agenta w programie Visual Studio lub Visual Studio Code

  3. Uruchom testera aplikacji Teams. W wierszu polecenia: agentsplayground

    • Narzędzie otwiera przeglądarkę internetową, w której wyświetlane jest narzędzie Teams App Test Tool, gotowe do wysyłania wiadomości do Twojego agenta.

  4. Uruchomiony agent na porcie 3978 powinien automatycznie łączyć się z konsolą testową agenta w przeglądarce, a Ty powinieneś mieć możliwość wchodzenia w interakcję z agentem uruchomionym lokalnie.

Jak działa agent?

Za pomocą zestawu SDK agentów agent jest kompilowany przy użyciu klas AgentApplication i AgentApplicationOptions . Jest to wbudowane w Program.cs plik przykładu.

Utwórz własnego agenta

W przykładzie widać, że gdy agent jest budowany, AgentApplicationOptions jest ładowany, a niestandardowa klasa agenta MyAgent.cs dziedziczy z AgentApplication.

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

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

Następnie magazyn jest ładowany domyślnie przy użyciu klasy MemoryStorage. Dzięki temu kontekst może być śledzony w różnych etapach podczas korzystania z funkcji TurnState, jednak należy je zastąpić w środowisku produkcyjnym bardziej trwałą pamięcią, taką jak BlobsStorage lub CosmosDbPartitionedStorage.

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

Pozostała część aplikacji agenta używa standardowych wzorców hostingu platformy .NET i dodaje trasy do akceptowania komunikatów w określonym punkcie końcowym. Ścieżki te używają interfejsu IAgent do akceptowania aktywności agenta i udostępniają deweloperom AgentApplication obiekt do pracy z ładunkiem Activity, który jest przekazywany z kanału/klienta. Dowiedz się więcej o działaniach (Activities) i użyciu Działań

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

Dodawanie nowej logiki niestandardowej w metodzie

Deweloperzy dodają logikę niestandardową MyAgent.cs w klasie, która implementuje AgentApplicationelement . Ta klasa używa AgentApplicationOptions do skonfigurowania dowolnych określonych ustawień konfiguracyjnych oraz Program.cs, aby zarejestrować odbiorniki zdarzeń z SDK Agentów, dostępne w AgentApplication, która odnosi się do odpowiedniej niestandardowej metody, gdy te zdarzenia zostaną wywołane przez klienta.

W poniższym przykładzie metoda OnConversationUpdate wyzwala metodę WelcomeMessageAsync , a metoda OnActivity wyzwala metodę OnMessageAsync.

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

Te zdarzenia są kierowane za pośrednictwem punktu końcowego skonfigurowanego w twoim MyProgram.cs i istnieje wiele zdarzeń, z których można korzystać. Najczęstszym elementem jest OnActivity. Aby dowiedzieć się więcej o zdarzeniach implementowanych przez zestaw SDK, zapoznaj się z informacjami na temat pracy z działaniami i specyfikacją protokołu działania.

Po wyzwoleniu metody, na przykład OnMessageAsync w celu zakończenia kolei, możesz zdecydować w Twojej niestandardowej logice odpowiedzieć, wysyłając komunikat z powrotem do klienta, używając metod dostępnych na instancji obiektu klasy TurnContext, która powinna być parametrem w Twojej metodzie, jak pokazano w poniższym przykładzie:

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

Wskazówka

Przejrzyj inne metody TurnContext dostępne, aby powrócić do klienta.

Teraz znasz podstawy, zapoznaj się z kolejnymi krokami i wykonaj kroki, aby dodać niestandardową logikę obsługi do agenta i wysłać z powrotem różne zdarzenia.

Dalsze kroki

Środowisko testowe agentów jest domyślnie dostępne, jeśli używasz już zestawu narzędzi Microsoft 365 Agents Toolkit. Jeśli chcesz rozpocząć pracę z zestawem narzędzi, możesz użyć jednego z następujących przewodników:

  • Last updated on