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.

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.

Étapes suivantes

Provisionner des ressources Azure Bot à utiliser avec le Kit de développement logiciel (SDK) Agents

Ce guide de démarrage rapide vous guide tout au long de la création d’un agent de moteur personnalisé qui répond simplement avec ce 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 :

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

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

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.

Étapes suivantes

Provisionner des ressources Azure Bot à utiliser avec le Kit de développement logiciel (SDK) Agents

Ce quickstart vous montre comment télécharger et exécuter l’exemple QuickStart/Empty Agent depuis GitHub.

Il existe deux façons principales de bien démarrer avec le Kit de développement logiciel (SDK) Microsoft 365 Agents :

• Cloner et exécuter l’exemple de l'agent de démarrage rapide/agent vide disponible sur GitHub

• Utilisez le Kit de ressources Microsoft 365 Agents. Le Kit d'outils Agents comprend deux modèles intégrés pour Visual Studio et Visual Studio Code utilisant le kit de développement logiciel (SDK) Microsoft 365 Agents. Ces modèles permettent de commencer avec un agent QuickStart/vide ou un agent météorologique utilisant Azure Foundry ou les services OpenAI avec le noyau sémantique ou LangChain.

Prerequisites

Vous avez besoin de quelques choses avant de commencer. Ces étapes utilisent l’exemple Démarrage rapide/Agent vide dans le guide de démarrage rapide .NET, mais vous pouvez également utiliser n’importe quel exemple de Kit de développement logiciel (SDK) Agents.

• SDK .NET 8.0
• Visual Studio ou Visual Studio Code
• Connaissances d’ASP.NET Core et de la programmation asynchrone en C#
• Télécharger l’exemple quickstart à partir de GitHub

Ouvrir la solution

1. Ouvrez le fichier QuickStart.csproj solution dans Visual Studio.

2. Exécutez le projet.

À ce stade, votre assistant s’exécute localement à l’aide du port 3978.

Tester votre agent localement

1. Installez Agents Playground si vous ne l’avez pas déjà fait.

   winget install agentsplayground
   

2. Démarrer l’agent dans Visual Studio ou Visual Studio Code

3. Démarrez le testeur d’application Teams. À l’invite de commandes : agentsplayground

   • L’outil ouvre un navigateur web affichant l’outil de test d’application Teams, prêt à envoyer des messages à votre agent.

4. Votre agent en cours d’exécution sur le port 3978 doit se connecter automatiquement au terrain de jeu de l’agent dans votre navigateur et vous devez être en mesure d’interagir avec votre agent en cours d’exécution localement

Comment fonctionne l’agent ?

Avec le Kit de développement logiciel (SDK) Agents, un agent est créé à l’aide de classes AgentApplication et AgentApplicationOptions . Ceci est généré dans le Program.cs fichier de l’exemple.

Créer votre assistant

Vous pouvez voir dans l'exemple que, tandis que l'agent est en cours de construction, AgentApplicationOptions est chargé et que votre classe d'agent personnalisée MyAgent.cs hérite de AgentApplication.

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

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

Ensuite, le stockage est chargé par défaut à l’aide de la classe MemoryStorage. Cela permet de suivre le contexte à travers les interactions lors de l’utilisation de TurnState, mais doit être remplacé en production par un stockage plus persistant tel que BlobsStorage ou CosmosDbPartitionedStorage.

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

Le reste de l’application agent utilise des modèles d’hébergement .NET standard et ajoute des itinéraires pour accepter des messages à un point de terminaison spécifique. Ces itinéraires utilisent l’interface IAgent pour accepter l’activité de l’agent et fournissent aux développeurs l’objet pour travailler avec le payload AgentApplication qui lui a été transmis à partir du canal/client. En savoir plus sur les activités et l’utilisation des activités

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

Ajouter une nouvelle logique personnalisée dans une méthode

Les développeurs ajoutent une logique personnalisée dans la MyAgent.cs classe qui implémente AgentApplication. Cette classe utilise AgentApplicationOptions pour configurer les paramètres spécifiques de votre configuration et Program.cs pour enregistrer les écouteurs d’événements à partir du Kit de développement logiciel (SDK) Agents. Ceux-ci sont disponibles dans la classe AgentApplication, qui fait référence à votre méthode personnalisée respective lorsque ces événements sont déclenchés par le client.

Dans l’exemple suivant, OnConversationUpdate déclenche la WelcomeMessageAsync méthode et OnActivity déclenche la méthode OnMessageAsync.

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

Ces événements sont routés via le point de terminaison configuré dans votre MyProgram.cs et il existe de nombreux événements que vous pouvez utiliser. Le plus courant est OnActivity. Pour en savoir plus sur les événements que le SDK implémente, consultez plus d’informations sur l’utilisation des activités et la spécification du protocole d’activité.

Une fois votre méthode déclenchée, par exemple OnMessageAsync pour terminer le tour, vous pouvez choisir dans votre logique personnalisée de répondre pour renvoyer un message au client à l’aide des méthodes disponibles sur et de l’instance de la classe TurnContext qui doit être un paramètre dans votre méthode, comme illustré dans l’exemple suivant :

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

Vous connaissez maintenant les principes de base, consultez les étapes suivantes et travaillez pour ajouter une logique de gestionnaire personnalisée à votre agent et renvoyer différents événements.

Étapes suivantes

• En savoir plus sur les activités et l’utilisation des activités
• Passez en revue les événements AgentApplication auxquels vous pouvez répondre à partir du client
• Passez en revue les événements TurnContext que vous pouvez renvoyer au client
• Provisionner des ressources Azure Bot à utiliser avec le Kit de développement logiciel (SDK) Agents
• Configurer votre agent .NET pour utiliser OAuth

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 :

• Créer des agents .NET dans Visual Studio à l’aide du Kit de ressources Microsoft 365 Agents
• Créer des agents JavaScript dans Visual Studio Code avec microsoft 365 Agents Toolkit