Rychlý start: Vytvoření a testování základního agenta

Tato úvodní příručka vás provede vytvořením vlastního agenta enginu, který odpoví libovolnou zprávou, kterou mu pošlete.

Požadavky

• Python 3.9 nebo novější

  • Pokud chcete nainstalovat Python, přejděte na https://www.python.org/downloads/stránku a postupujte podle pokynů pro váš operační systém.
  • Chcete-li ověřit verzi, zadejte python --versionv okně terminálu .

• Editor kódu podle vašeho výběru. Tyto pokyny používají Visual Studio Code.

  Pokud používáte Visual Studio Code, nainstalujte rozšíření Pythonu.

Inicializace projektu a instalace sady SDK

Vytvořte projekt Pythonu a nainstalujte požadované závislosti.

1. Otevření terminálu a vytvoření nové složky

   mkdir echo
   cd echo
   

2. Pomocí tohoto příkazu otevřete složku pomocí editoru Visual Studio Code:

   code .
   

3. Vytvořte virtuální prostředí pomocí metody podle vašeho výběru a aktivujte ho prostřednictvím editoru Visual Studio Code nebo v terminálu.

   Při použití editoru Visual Studio Code můžete použít tyto kroky s nainstalovaným rozšířením Pythonu .

   1. Stiskněte klávesu F1, zadejte Python: Create environmenta stiskněte Enter.

      1. Vyberte Venv a vytvořte .venv virtuální prostředí v aktuálním pracovním prostoru.

      2. Vyberte instalaci Pythonu a vytvořte virtuální prostředí.

         Hodnota může vypadat takto:

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

4. Instalace sady Agents SDK

   Pomocí nástroje pip nainstalujte balíček microsoft-agents-hosting-aiohttp pomocí tohoto příkazu:

   pip install microsoft-agents-hosting-aiohttp
   

Vytvoření serverové aplikace a import požadovaných knihoven

1. Vytvořte soubor s názvem start_server.py, zkopírujte následující kód a vložte ho do:

   # 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
   

   Tento kód definuje start_server funkci, která použijeme v dalším souboru.

2. Ve stejném adresáři vytvořte soubor s názvem app.py s následujícím kódem.

   # 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
   

Vytvoření instance agenta jako AgentApplication

Do app.pypole přidejte následující kód, který vytvoří AGENT_APP jako instanci objektu AgentApplicationa implementuje tři trasy pro reakci na tři události:

• Aktualizace konverzace
• zpráva /help
• jakákoli jiná aktivita

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

Spuštění webového serveru pro naslouchání v localhost:3978

Na konci app.py, spusťte webový server pomocí start_server.

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

Místní spuštění agenta v anonymním režimu

V terminálu spusťte tento příkaz:

python app.py

Terminál by měl vrátit následující:

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

Otestujte agenta lokálně

1. Z jiného terminálu (aby byl agent spuštěný) nainstalujte Microsoft 365 Agents Playground tímto příkazem:

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

   Poznámka:

   Tento příkaz používá npm, protože Microsoft 365 Agents Playground není k dispozici pomocí pip.

   Terminál by měl vrátit něco podobného:

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

2. Pomocí tohoto příkazu spusťte testovací nástroj pro interakci s vaším agentem:

   teamsapptester
   

   Terminál by měl vrátit něco podobného:

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

Příkaz teamsapptester otevře výchozí prohlížeč a připojí se k vašemu agentu.

Teď můžete odeslat libovolnou zprávu, abyste viděli odezvu echo, nebo odeslat zprávu /help, abyste viděli, jak se tato zpráva směruje do obslužné rutiny _help.

Tato úvodní příručka vás provede vytvořením vlastního agenta enginu, který odpoví libovolnou zprávou, kterou mu pošlete.

Požadavky

• Node.js v22 nebo novější

  • Pokud chcete nainstalovat Node.js přejděte na nodejs.org a postupujte podle pokynů pro váš operační systém.
  • Chcete-li ověřit verzi, zadejte node --versionv okně terminálu .

• Editor kódu podle vašeho výběru. Tyto pokyny používají Visual Studio Code.

Inicializace projektu a instalace sady SDK

Slouží npm k inicializaci projektu node.js vytvořením package.json a instalací požadovaných závislostí.

1. Otevření terminálu a vytvoření nové složky

   mkdir echo
   cd echo
   

2. Inicializace projektu node.js

   npm init -y
   

3. Instalace sady Agents SDK

   npm install @microsoft/agents-hosting-express
   

4. Pomocí tohoto příkazu otevřete složku pomocí editoru Visual Studio Code:

   code .
   

Import potřebných knihoven

Vytvořte soubor index.mjs a naimportujte do kódu aplikace následující balíčky NPM:

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

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

Implementovat EchoAgent jako AgentApplication

Do index.mjspole přidejte následující kód pro vytvoření EchoAgent rozšíření AgentApplication a implementujte tři trasy pro reakci na tři události:

• Aktualizace konverzace
• zpráva /help
• jakákoli jiná aktivita

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

Spuštění webového serveru pro naslouchání v localhost:3978

Na konci index.mjs spusťte webový server pomocí startServer na základě expresu s použitím MemoryStorage jako úložiště stavu přepnutí.

startServer(new EchoAgent(new MemoryStorage()))

Místní spuštění agenta v anonymním režimu

V terminálu spusťte tento příkaz:

node index.mjs

Terminál by měl vrátit toto:

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

Otestujte agenta lokálně

1. Z jiného terminálu (aby byl agent spuštěný) nainstalujte Microsoft 365 Agents Playground tímto příkazem:

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

   Terminál by měl vrátit něco podobného:

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

2. Pomocí tohoto příkazu spusťte testovací nástroj pro interakci s vaším agentem:

   node_modules/.bin/teamsapptester
   

   Terminál by měl vrátit něco podobného:

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

Příkaz teamsapptester otevře výchozí prohlížeč a připojí se k vašemu agentu.

Teď můžete odeslat libovolnou zprávu, abyste viděli odezvu echo, nebo odeslat zprávu /help, abyste viděli, jak se tato zpráva směruje do obslužné rutiny _help.

Tato úvodní příručka vás provede vytvořením vlastního agenta enginu, který odpoví libovolnou zprávou, kterou mu pošlete.

Požadavky

• SDK .NET 8.0 nebo novější

  • Pokud chcete nainstalovat sadu .NET SDK, přejděte na dotnet.microsoft.com a postupujte podle pokynů pro váš operační systém.
  • Chcete-li ověřit verzi, zadejte dotnet --versionv okně terminálu .

• Editor kódu podle vašeho výběru. Tyto pokyny používají Visual Studio Code.

Inicializace projektu a instalace sady SDK

Slouží dotnet k vytvoření nového webového projektu a instalaci požadovaných závislostí.

1. Otevření terminálu a vytvoření nové složky

   mkdir echo
   cd echo
   

2. Inicializace projektu .NET

   dotnet new web
   

3. Instalace sady Agents SDK

   dotnet add package Microsoft.Agents.Hosting.AspNetCore
   

4. Pomocí tohoto příkazu otevřete složku pomocí editoru Visual Studio Code:

   code .
   

Import potřebných knihoven

Nahraďte Program.csexistující obsah a přidejte následující using příkazy pro import balíčků SDK do kódu aplikace:

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

Implementovat EchoAgent jako AgentApplication

V Program.cs, po using příkazech přidejte následující kód pro vytvoření EchoAgent rozšiřujícího AgentApplication a implementování tras pro reakci na události:

• Aktualizace konverzace
• Jakákoli jiná aktivita

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

Nastavení webového serveru a registrace aplikace agenta

Program.cs Za usingpříkazy přidejte následující kód, který nakonfiguruje webového hostitele, zaregistruje agenta a namapuje /api/messages koncový bod:

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

Nastavte webový server tak, aby naslouchal na localhost: 3978

V launchSettings.json aktualizujte applicationURL na http://localhost:3978, aby aplikace naslouchala na správném portu.

Místní spuštění agenta v anonymním režimu

V terminálu spusťte tento příkaz:

dotnet run

Terminál by měl vrátit něco podobného:

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

Otestujte agenta lokálně

1. Z jiného terminálu (aby byl agent spuštěný) nainstalujte Microsoft 365 Agents Playground pomocí následujícího příkazu:

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

   Poznámka:

   Tento příkaz používá npm, protože Microsoft 365 Agents Playground je distribuován jako balíček npm.

   Terminál by měl vrátit něco podobného:

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

2. Pomocí tohoto příkazu spusťte testovací nástroj pro interakci s vaším agentem:

   teamsapptester
   

   Terminál by měl vrátit něco podobného:

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

Příkaz teamsapptester otevře výchozí prohlížeč a připojí se k vašemu agentu.

Do textového zadání zadejte a odešlete zprávu, abyste viděli odpověď typu echo.

Další kroky

• Projděte si ukázky sady Agents SDK na GitHubu.
• Další informace o aktivitách a práci s aktivitami
• Projděte si události AgentApplication, na které můžete odpovědět z klienta.
• Zkontrolujte události TurnContext, které můžete odeslat zpět klientovi.
• Zřízení prostředků Azure Bot pro použití se sadou Agents SDK
• Konfigurace agenta .NET pro použití OAuth

Pokud už používáte sadu Microsoft 365 Agents Toolkit, je dětské hřiště agentů k dispozici ve výchozím nastavení. Pokud chcete začít se sadou nástrojů, můžete použít jeden z následujících průvodců:

• Vytváření agentů .NET v sadě Visual Studio pomocí sady nástrojů Microsoft 365 Agents Toolkit
• Vytváření agentů JavaScriptu v editoru Visual Studio Code pomocí sady nástrojů Microsoft 365 Agents Toolkit