Partager via

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

Ce guide de démarrage rapide vous guide tout au long de la création d’un agent de moteur personnalisé qui répond avec le message que vous lui envoyez.

Prerequisites

  • Python 3.9 ou version ultérieure.

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

  • É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. Ouvrir un terminal et créer un dossier

    mkdir echo
cd echo

  2. Ouvrez le dossier à l’aide de Visual Studio Code à l’aide de cette commande :

    code .

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

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

    1. Appuyez sur F1, tapez Python: Create environment, puis appuyez sur Entrée.

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

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

        La valeur peut ressembler à ceci :

        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 requises

  1. Créez un fichier nommé start_server.py, copiez le code suivant et collez-le :

    # 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 allons utiliser 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éer une instance de l’agent en tant qu’AgentApplication

Dans app.py, ajoutez le code suivant pour créer l’instance AGENT_APP en tant qu’instance du AgentApplication, et implémentez trois itinéraires 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 dans localhost :3978

À la fin de app.py, démarrez le serveur web à l’aide de start_server.

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

Exécuter l’agent localement en mode anonyme

À partir de votre terminal, exécutez cette commande :

python app.py

Le terminal doit retourner les éléments suivants :

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

Tester l’agent localement

  1. À partir d’un autre terminal (pour maintenir l’agent en cours d’exécution) installez l’aire de jeu des agents Microsoft 365 avec cette commande :

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

    Note

    Cette commande utilise npm, car Microsoft 365 Agents Playground n’est pas disponible à l’aide de pip.

    Le terminal doit retourner quelque chose comme suit :

    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 agent à l’aide de cette commande :

    teamsapptester

    Le terminal doit retourner quelque chose comme suit :

    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 teamsapptester commande ouvre votre navigateur par défaut et se connecte à votre agent.

Votre assistant dans le terrain de jeu des assistants

Vous pouvez maintenant envoyer n’importe quel message pour afficher la réponse d’écho ou envoyer le message /help pour voir comment ce message est acheminé vers le _help gestionnaire.

Ce guide de démarrage rapide vous guide tout au long de la création d’un agent de moteur personnalisé qui répond avec le message que vous lui envoyez.

Prerequisites

  • Node.js v22 ou version ultérieure

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

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

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

Permet npm d’initialiser un projet node.js en créant un package.json et en installant les dépendances requises

  1. Ouvrir un terminal et créer un dossier

    mkdir echo
cd echo

  2. Initialiser 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 à l’aide de Visual Studio Code à l’aide de la commande suivante :

    code .

Importez les bibliothèques nécessaires

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

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

Implémenter EchoAgent en tant qu’AgentApplication

Dans index.mjs, ajoutez le code suivant pour créer l’extension EchoAgent de l’Application Agent et implémentez trois itinéraires 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 dans 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écuter l’agent localement en mode anonyme

À partir de votre terminal, exécutez cette commande :

node index.mjs

Le terminal doit retourner ceci :

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

Tester l’agent localement

  1. À partir d’un autre terminal (pour maintenir l’agent en cours d’exécution) installez l’aire de jeu des agents Microsoft 365 avec cette commande :

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

    Le terminal doit retourner quelque chose comme suit :

    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 agent à l’aide de cette commande :

    node_modules/.bin/teamsapptester

    Le terminal doit retourner quelque chose comme suit :

    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 teamsapptester commande ouvre votre navigateur par défaut et se connecte à votre agent.

Votre assistant dans le terrain de jeu des assistants

Vous pouvez maintenant envoyer n’importe quel message pour afficher la réponse d’écho ou envoyer le message /help pour voir comment ce message est acheminé vers le _help gestionnaire.

Ce guide de démarrage rapide vous guide tout au long de la création d’un agent de moteur personnalisé qui répond avec le message que vous lui envoyez.

Prerequisites

  • Sdk .NET 8.0 ou version ultérieure

    • Pour installer le Kit de développement logiciel (SDK) .NET, accédez à dotnet.microsoft.com et suivez les instructions de votre système d’exploitation.
    • Pour vérifier la version, tapez dotnet --version dans une fenêtre de terminal.

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

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

Permet dotnet de créer un projet web et d’installer les dépendances requises.

  1. Ouvrir un terminal et créer un dossier

    mkdir echo
cd echo

  2. Initialiser 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 à l’aide de Visual Studio Code à l’aide de cette commande :

    code .

Importez les bibliothèques nécessaires

Dans Program.cs, remplacez le contenu existant et ajoutez les instructions suivantes using pour importer les packages du Kit de développement logiciel (SDK) dans votre code d’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émenter EchoAgent en tant qu’AgentApplication

Dans Program.cs, après les using instructions, ajoutez le code suivant pour créer l’extension EchoAgentAgentApplication et implémentez des itinéraires 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);
   }
}

Configurer le serveur web et inscrire l’application agent

Dans Program.cs, après les using instructions, ajoutez le code suivant pour configurer l’hôte web, inscrire l’agent et mapper le /api/messages point de terminaison :

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

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

Dans launchSettings.json, mettez à jour applicationURL en http://localhost:3978 pour que l'application écoute sur le port approprié.

Exécuter l’agent localement en mode anonyme

À partir de votre terminal, exécutez cette commande :

dotnet run

Le terminal doit retourner quelque chose comme suit :

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

Tester l’agent localement

  1. À partir d’un autre terminal (pour maintenir l’agent en cours d’exécution) installez Le terrain de jeu des agents Microsoft 365 avec la commande suivante :

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

    Note

    Cette commande utilise npm, car Microsoft 365 Agents Playground est distribué en tant que package npm.

    Le terminal doit retourner quelque chose comme suit :

    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 agent à l’aide de cette commande :

    teamsapptester

    Le terminal doit retourner quelque chose comme suit :

    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 teamsapptester commande ouvre votre navigateur par défaut et se connecte à votre agent.

Votre assistant dans le terrain de jeu des assistants

Dans l’entrée de texte, entrez et envoyez n’importe quel message pour afficher la réponse d’écho.

Étapes suivantes

Le terrain de jeu d’agents est disponible par défaut si vous utilisez déjà microsoft 365 Agents Toolkit. Vous pouvez utiliser l’un des guides suivants si vous souhaitez commencer à utiliser le kit de ressources :

  • Last updated on