Quickstart: Een basisagent maken en testen

In deze snelle startgids wordt u begeleid bij het maken van een aangepaste engineagent die antwoordt met hetzelfde bericht dat u ernaar verzendt.

Vereiste voorwaarden

• Python 3.9 of hoger.

  • Als u Python wilt installeren, gaat u naar https://www.python.org/downloads/en volgt u de instructies voor uw besturingssysteem.
  • Om de versie te controleren, typt u in een terminalvenster python --version.

• Een code-editor van uw keuze. In deze instructies wordt Visual Studio Code gebruikt.

  Als u Visual Studio Code gebruikt, installeert u de Python-extensie

Het project initialiseren en de SDK installeren

Maak een Python-project en installeer de vereiste afhankelijkheden.

1. Een terminal openen en een nieuwe map maken

   mkdir echo
   cd echo
   

2. Open de map met Visual Studio Code met behulp van deze opdracht:

   code .
   

3. Maak een virtuele omgeving met de methode van uw keuze en activeer deze via Visual Studio Code of in een terminal.

   Wanneer u Visual Studio Code gebruikt, kunt u deze stappen gebruiken om de Python-extensie te installeren.

   1. Druk op F1, typ Python: Create environmenten druk op Enter.

      1. Selecteer Venv om een .venv virtuele omgeving te maken in de huidige werkruimte.

      2. Selecteer een Python-installatie om de virtuele omgeving te maken.

         De waarde kan er als volgt uitzien:

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

4. De Agents SDK installeren

   Gebruik pip om het microsoft-agents-hosting-aiohttp-pakket te installeren met deze opdracht:

   pip install microsoft-agents-hosting-aiohttp
   

De servertoepassing maken en de vereiste bibliotheken importeren

1. Maak een bestand met de naam start_server.py, kopieer de volgende code en plak het in:

   # 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
   

   Deze code definieert een start_server functie die we in het volgende bestand gaan gebruiken.

2. Maak in dezelfde map een bestand met de naam app.py met de volgende code.

   # 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
   

Een exemplaar van de Agent creëren als AgentApplication

Voeg in app.py de volgende code toe om de AGENT_APP als een instantie van de AgentApplication te maken en implementeer drie routes om te reageren op drie events.

• Gespreksupdate
• het bericht /help
• andere activiteiten

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

Start de webserver om te luisteren in localhost:3978

Aan het einde van app.py, start u de webserver met behulp van start_server.

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

De agent lokaal uitvoeren in de anonieme modus

Voer vanuit de terminal deze opdracht uit:

python app.py

De terminal moet het volgende retourneren:

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

De agent lokaal testen

1. Installeer vanaf een andere terminal (om de agent actief te houden) de Microsoft 365 Agents Playground met deze opdracht:

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

   Opmerking

   Deze opdracht maakt gebruik van npm omdat de Microsoft 365 Agents Playground niet beschikbaar is met pip.

   De terminal moet ongeveer als volgt retourneren:

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

2. Voer het testprogramma uit om met uw agent te communiceren met behulp van deze opdracht:

   teamsapptester
   

   De terminal moet ongeveer als volgt retourneren:

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

De teamsapptester opdracht opent uw standaardbrowser en maakt verbinding met uw agent.

U kunt nu elk bericht verzenden om het echoantwoord te zien of het bericht /help verzenden om te zien hoe dat bericht naar de _help handler wordt doorgestuurd.

Volgende stappen

Azure Bot-resources inrichten voor gebruik met Agents SDK

In deze quickstart wordt u begeleid bij het maken van een aangepaste engine-agent die simpelweg antwoord geeft met alles wat u ernaar verzendt.

Vereiste voorwaarden

• Node.js v22 of hoger

  • Als u Node.js wilt installeren, gaat u naar nodejs.org en volgt u de instructies voor uw besturingssysteem.
  • Om de versie te controleren, typt u in een terminalvenster node --version.

• Een code-editor van uw keuze. In deze instructies wordt Visual Studio Code gebruikt.

Het project initialiseren en de SDK installeren

Gebruik npm dit om een node.js project te initialiseren door een package.json te maken en de vereiste afhankelijkheden te installeren

1. Een terminal openen en een nieuwe map maken

   mkdir echo
   cd echo
   

2. Het node.js-project initialiseren

   npm init -y
   

3. De Agents SDK installeren

   npm install @microsoft/agents-hosting-express
   

4. Open de map met Visual Studio Code met behulp van de volgende opdracht:

   code .
   

De vereiste bibliotheken importeren

Maak het bestand index.mjs en importeer de volgende NPM-pakketten in uw toepassingscode:

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

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

De EchoAgent implementeren als agentapplication

Voeg index.mjsde volgende code toe om de EchoAgent uitbreiding van AgentApplication te maken en implementeer drie routes om te reageren op drie gebeurtenissen:

• Gespreksupdate
• het bericht /help
• andere activiteiten

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

Start de webserver om te luisteren in localhost:3978

Aan het einde van index.mjs start de webserver met behulp van startServer gebaseerd op express en gebruik MemoryStorage als opslag voor de toestand van de beurt.

startServer(new EchoAgent(new MemoryStorage()))

De agent lokaal uitvoeren in de anonieme modus

Voer vanuit de terminal deze opdracht uit:

node index.mjs

De terminal moet dit retourneren:

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

De agent lokaal testen

1. Installeer vanaf een andere terminal (om de agent actief te houden) de Microsoft 365 Agents Playground met deze opdracht:

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

   De terminal moet ongeveer als volgt retourneren:

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

2. Voer het testprogramma uit om met uw agent te communiceren met behulp van deze opdracht:

   node_modules/.bin/teamsapptester
   

   De terminal moet ongeveer als volgt retourneren:

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

De teamsapptester opdracht opent uw standaardbrowser en maakt verbinding met uw agent.

U kunt nu elk bericht verzenden om het echoantwoord te zien of het bericht /help verzenden om te zien hoe dat bericht naar de _help handler wordt doorgestuurd.

Volgende stappen

Azure Bot-resources inrichten voor gebruik met Agents SDK

Deze quickstart laat zien hoe je het QuickStart/Empty Agent-voorbeeld van GitHub downloadt en uitvoert.

Er zijn twee belangrijke manieren om aan de slag te gaan met de Microsoft 365 Agents SDK:

• Kloon en voer het voorbeeld van de QuickStart/Empty Agent-agent uit die beschikbaar is op GitHub

• Gebruik de Microsoft 365 Agents Toolkit. De Agents Toolkit heeft twee ingebouwde sjablonen voor Visual Studio en Visual Studio Code die de Microsoft 365 Agents SDK gebruiken om te beginnen met een quickstart/lege agent en een weeragent die gebruikmaakt van Azure Foundry- of OpenAI-services met Semantische kernel of LangChain.

Vereiste voorwaarden

U hebt een paar dingen nodig voordat u aan de slag gaat. In deze stappen wordt het QuickStart/Empty-Agent voorbeeld van .NET quickstart gebruikt, maar u kunt ook elk Agents SDK-voorbeeld gebruiken.

• .NET 8.0 SDK
• Visual Studio of Visual Studio Code
• Kennis van ASP.NET Core en asynchroon programmeren in C#
• quickstart Het voorbeeld downloaden van GitHub

De oplossing openen

1. Open het oplossingsbestand QuickStart.csproj in Visual Studio.

2. Voer het project uit.

Op dit moment wordt uw agent lokaal uitgevoerd met poort 3978.

Uw agent lokaal testen

1. Installeer de Agents Playground als u dat nog niet hebt gedaan.

   winget install agentsplayground
   

2. De agent starten in Visual Studio of Visual Studio Code

3. Start de Teams-app-tester. Achter een opdrachtprompt: agentsplayground

   • Het hulpprogramma opent een webbrowser met het testprogramma voor Teams-apps, dat klaar is om berichten naar uw agent te verzenden.

4. Uw actieve agent op poort 3978 moet automatisch verbinding maken met de agentspeelplaats in uw browser en u moet kunnen communiceren met uw agent die lokaal wordt uitgevoerd

Hoe werkt de agent?

Met de Agents SDK wordt een agent gebouwd met behulp van de klassen AgentApplication en AgentApplicationOptions . Dit is ingebouwd in het Program.cs bestand van het voorbeeld.

Uw agent bouwen

U kunt in het voorbeeld zien dat, wanneer de agent wordt gebouwd, AgentApplicationOptions wordt geladen en uw aangepaste agentklasse MyAgent.cs, die erft van AgentApplication.

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

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

Vervolgens wordt de opslag standaard geladen met behulp van de MemoryStorage-klasse. Hierdoor kan de context worden bijgehouden tijdens het gebruik van TurnState. In productie moet echter worden overgeschakeld naar persistentere opslag, zoals BlobsStorage of CosmosDbPartitionedStorage.

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

De rest van de agenttoepassing maakt gebruik van standaard .NET-hostingpatronen en voegt routes toe om berichten op een specifiek eindpunt te accepteren. Deze routes gebruiken de IAgent-interface om de agentactiviteit te accepteren en biedt ontwikkelaars het AgentApplication object om te werken met de nettolading Activiteit die vanuit het kanaal/de client is doorgegeven. Meer informatie over de activiteiten en het werken met activiteiten

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

Nieuwe aangepaste logica toevoegen in een methode

Ontwikkelaars voegen aangepaste logica toe in de MyAgent.cs klasse die AgentApplication implementeert. Deze klasse gebruikt de AgentApplicationOptions om specifieke instellingen van uw configuratie aan te passen en registreert Program.cs als gebeurtenislisteners van de Agents SDK. Deze listeners zijn beschikbaar in de AgentApplication klasse en verwijzen naar uw eigen aangepaste methode wanneer die gebeurtenissen door de client worden geactiveerd.

In het volgende voorbeeld activeert OnConversationUpdate de WelcomeMessageAsync methode en activeert OnActivity de methode OnMessageAsync.

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

Deze gebeurtenissen worden gerouteerd via het eindpunt dat is geconfigureerd in uw MyProgram.cs en er zijn talloze gebeurtenissen die u kunt gebruiken. De meest voorkomende is OnActivity. Zie voor meer informatie over de gebeurtenissen die de SDK implementeert, meer informatie over het werken met activiteiten en de specificatie van het activiteitsprotocol.

Zodra uw methode is geactiveerd, bijvoorbeeld OnMessageAsync om de draai te beëindigen, kunt u in uw aangepaste logica kiezen om te reageren op het terugsturen van een bericht naar de client met behulp van de methoden die beschikbaar zijn voor en het exemplaar van de TurnContext-klasse die een parameter in uw methode moet zijn, zoals wordt weergegeven in het volgende voorbeeld:

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

Aanbeveling

Bekijk de andere TurnContext-methoden die beschikbaar zijn om terug te keren naar de client.

Nu u de basisprincipes kent, bekijkt u de volgende stappen en werkt u aan het toevoegen van aangepaste handlerlogica aan uw agent en het terugsturen van verschillende gebeurtenissen.

Volgende stappen

• Meer informatie over de activiteiten en het werken met activiteiten
• Controleer de AgentApplication-gebeurtenissen waarop u kunt reageren vanaf de client
• Controleer de TurnContext-gebeurtenissen die u naar de client kunt sturen
• Azure Bot-resources inrichten voor gebruik met Agents SDK
• Uw .NET-agent configureren voor het gebruik van OAuth

De Agents Playground is standaard beschikbaar als u de Microsoft 365 Agents Toolkit al gebruikt. U kunt een van de volgende handleidingen gebruiken als u aan de slag wilt met de toolkit:

• .NET-agents maken in Visual Studio met behulp van de Microsoft 365 Agents Toolkit
• JavaScript-agents maken in Visual Studio Code met de Microsoft 365 Agents Toolkit