Démarrage rapide : Créer et tester un assistant de base

Ce démarrage rapide vous guide dans la création d’un assistant de moteur personnalisé qui répond par le message que vous lui envoyez.

Configuration requise

  • Python 3.9 ou version ultérieure.

    • Pour installer Python, rendez-vous sur https://www.python.org/downloads/, puis suivez les instructions correspondant à votre système d’exploitation.
    • Pour vérifier la version, tapez dans une fenêtre de terminal python --version.

  • Un éditeur de code de votre choix. Ces instructions utilisent Visual Studio Code.

    Si vous utilisez Visual Studio Code, installez l’extension Python

Initialiser le projet et installer le kit de développement logiciel (SDK)

Créez un projet Python et installez les dépendances requises.

  1. Ouvrez un terminal et créez un dossier

    mkdir echo
cd echo

  2. Ouvrez le dossier dans Visual Studio Code en utilisant cette commande :

    code .

  3. Créez un environnement virtuel avec la méthode de votre choix et activez-le soit dans Visual Studio Code, soit dans un terminal.

    Lorsque vous utilisez Visual Studio Code, vous pouvez suivre ces étapes avec l’extension Python installée.

    1. Appuyez sur F1, saisissez Python: Create environment et appuyez sur Entrée.

      1. Sélectionnez Venv pour créer un environnement virtuel .venv dans l’espace de travail actuel.

      2. Sélectionnez une installation Python pour créer l’environnement virtuel.

        La valeur peut ressembler à ce qui suit :

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

  4. Installer le kit de développement logiciel (SDK) Agents

    Utilisez pip pour installer le package microsoft-agents-hosting-aiohttp avec cette commande :

    pip install microsoft-agents-hosting-aiohttp

Créer l’application serveur et importer les bibliothèques nécessaires

  1. Créez un fichier appelé start_server.py, copiez le code suivant, puis collez-le dans :

    # 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

    Ce code définit une start_server fonction que nous utiliserons dans le fichier suivant.

  2. Dans le même répertoire, créez un fichier nommé app.py avec le code suivant.

    # 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

Créez une instance de l’assistant en tant qu’AgentApplication

Dans app.py, ajoutez le code suivant pour créer AGENT_APP en tant qu’instance de AgentApplication, et implémentez trois routes pour répondre à trois événements :

  • Mise à jour de la conversation
  • le message /help
  • toute autre activité
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}")

Démarrez le serveur web pour écouter sur localhost:3978

À la fin de app.py, démarrez le serveur web en utilisant start_server.

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

Exécutez l’assistant localement en mode anonyme

Dans votre terminal, exécutez la commande suivante :

python app.py

Le terminal doit renvoyer ce qui suit :

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

Tester l’assistant localement

  1. Depuis un autre terminal (pour maintenir l’assistant en marche), installez le terrain de jeu Microsoft 365 Agents avec cette commande :

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

    Note

    Cette commande utilise npm car le terrain de jeu Microsoft 365 Agents n’est pas disponible avec pip.

    Le terminal devrait renvoyer quelque chose comme :

    added 1 package, and audited 130 packages in 1s

19 packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities

  2. Exécutez l’outil de test pour interagir avec votre assistant en utilisant cette commande :

    teamsapptester

    Le terminal devrait renvoyer quelque chose comme :

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

La commande teamsapptester ouvre votre navigateur par défaut et se connecte à votre assistant.

Votre assistant dans le terrain de jeu des assistants

Vous pouvez maintenant envoyer n’importe quel message pour voir la réponse echo, ou envoyer le message /help afin de voir comment ce message est acheminé vers le gestionnaire _help.

Ce démarrage rapide vous guide dans la création d’un assistant de moteur personnalisé qui répond par le message que vous lui envoyez.

Configuration requise

  • Node.js v22 ou plus récent

    • Pour installer Node.js, allez sur nodejs.org et suivez les instructions pour votre système d’exploitation.
    • Pour vérifier la version, tapez dans une fenêtre de terminal node --version.

  • Un éditeur de code de votre choix. Ces instructions utilisent Visual Studio Code.

Initialiser le projet et installer le kit de développement logiciel (SDK)

Utilisez npm pour initialiser un projet Node.js en créant un fichier package.json et en installant les dépendances nécessaires

  1. Ouvrez un terminal et créez un dossier

    mkdir echo
cd echo

  2. Initialisez le projet Node.js

    npm init -y

  3. Installer le kit de développement logiciel (SDK) Agents

    npm install @microsoft/agents-hosting-express

  4. Ouvrez le dossier dans Visual Studio Code en utilisant la commande suivante :

    code .

Importer les bibliothèques nécessaires

Créez le fichier index.mjs et importez les paquets NPM suivants dans votre code d’application :

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

Implémentez l’EchoAgent en tant qu’AgentApplication

Dans index.mjs, ajoutez le code suivant pour créer le EchoAgent en étendant le AgentApplication, et implémentez trois routes pour répondre à trois événements :

  • Mise à jour de la conversation
  • le message /help
  • toute autre activité
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)
  }
}

Démarrez le serveur web pour écouter sur localhost:3978

À la fin du index.mjs démarrage du serveur web avec startServer selon l’expression à l’aide de MemoryStorage en tant que stockage pour l’état de session.

startServer(new EchoAgent(new MemoryStorage()))

Exécutez l’assistant localement en mode anonyme

Dans votre terminal, exécutez la commande suivante :

node index.mjs

Le terminal devrait afficher ceci :

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

Tester l’assistant localement

  1. Depuis un autre terminal (pour maintenir l’assistant en marche), installez le terrain de jeu Microsoft 365 Agents avec cette commande :

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

    Le terminal devrait renvoyer quelque chose comme :

    added 1 package, and audited 130 packages in 1s

19 packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities

  2. Exécutez l’outil de test pour interagir avec votre assistant en utilisant cette commande :

    node_modules/.bin/teamsapptester

    Le terminal devrait renvoyer quelque chose comme :

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

La commande teamsapptester ouvre votre navigateur par défaut et se connecte à votre assistant.

Votre assistant dans le terrain de jeu des assistants

Vous pouvez maintenant envoyer n’importe quel message pour voir la réponse echo, ou envoyer le message /help afin de voir comment ce message est acheminé vers le gestionnaire _help.

Ce démarrage rapide vous guide dans la création d’un assistant de moteur personnalisé qui répond par le message que vous lui envoyez.

Configuration requise

  • SDK .NET 8.0 ou version ultérieure

    • Pour installer le SDK .NET, rendez-vous sur dotnet.microsoft.com et suivez les instructions pour votre système d’exploitation.
    • Pour vérifier la version, tapez dans une fenêtre de terminal dotnet --version.

  • Un éditeur de code de votre choix. Ces instructions utilisent Visual Studio Code.

Initialiser le projet et installer le kit de développement logiciel (SDK)

Utilisez dotnet pour créer un projet web et installer les dépendances requises.

  1. Ouvrez un terminal et créez un dossier

    mkdir echo
cd echo

  2. Initialisez le projet .NET

    dotnet new web

  3. Installer le kit de développement logiciel (SDK) Agents

    dotnet add package Microsoft.Agents.Hosting.AspNetCore

  4. Ouvrez le dossier dans Visual Studio Code en utilisant cette commande :

    code .

Importer les bibliothèques nécessaires

Dans Program.cs, remplacez le contenu existant et ajoutez les instructions suivantes using pour importer les paquets SDK dans votre code application :

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

Implémentez l’EchoAgent en tant qu’AgentApplication

Dans Program.cs, après les déclarations using, ajoutez le code suivant pour créer le EchoAgent qui étend AgentApplication, et implémentez des routes pour répondre aux événements :

  • Mise à jour de la conversation
  • Toute autre activité
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);
   }
}

Configurez le serveur web et enregistrez l’application assistant

Dans Program.cs, après les déclarations using, ajoutez le code suivant pour configurer le serveur web, enregistrer l’assistant et associer le point de terminaison /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();

Configurez le serveur web pour écouter sur localhost:3978

Dans launchSettings.json, mettez à jour applicationURL en http://localhost:3978 afin que l’application écoute sur le bon port.

Exécutez l’assistant localement en mode anonyme

Dans votre terminal, exécutez la commande suivante :

dotnet run

Le terminal devrait renvoyer quelque chose comme :

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

Tester l’assistant localement

  1. Depuis un autre terminal (pour maintenir l’assistant en marche), installez le terrain de jeu Microsoft 365 Agents avec la commande suivante :

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

    Note

    Cette commande utilise npm car le terrain de jeu Microsoft 365 Agents est distribué sous forme de package npm.

    Le terminal devrait renvoyer quelque chose comme :

    added 1 package, and audited 130 packages in 1s

19 packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities

  2. Exécutez l’outil de test pour interagir avec votre assistant en utilisant cette commande :

    teamsapptester

    Le terminal devrait renvoyer quelque chose comme :

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

La commande teamsapptester ouvre votre navigateur par défaut et se connecte à votre assistant.

Votre assistant dans le terrain de jeu des assistants

Dans le champ de saisie, saisissez et envoyez tout message pour voir la réponse echo.

Étapes suivantes

Le terrain de jeu Agents est disponible par défaut si vous utilisez déjà la boîte à outils Microsoft 365 Agents. Vous pouvez utiliser l’un des guides suivants pour commencer à utiliser la boîte à outils :

  • Last updated on