Delen via

Agenten testen met behulp van de Microsoft Agent 365 SDK

Belangrijk

U moet deelnemen aan het preview-programma Frontier om vroegtijdige toegang te krijgen tot Microsoft Agent 365. Frontier verbindt u rechtstreeks met de nieuwste AI-innovaties van Microsoft. Op Frontier-previews zijn de bestaande preview-voorwaarden van uw klantovereenkomsten van toepassing. Omdat deze functies nog in ontwikkeling zijn, kunnen de beschikbaarheid en mogelijkheden hiervan na verloop van tijd veranderen.

Test uw agent lokaal met Agents Playground voordat u de implementatie uitvoert. In deze handleiding wordt beschreven hoe u uw ontwikkelomgeving instelt, de verificatie configureert en de functionaliteit van uw agent valideert met het testhulpprogramma Agents Playground.

Zodra uw agent lokaal werkt, kunt u deze implementeren en publiceren om te testen in Microsoft 365-toepassingen zoals Teams.

Vereisten

Voordat u begint met het testen van uw agent, moet u controleren of de volgende vereisten zijn geïnstalleerd:

Algemene vereisten

Taalspecifieke vereisten

Testomgeving voor agenten configureren

In deze sectie worden omgevingsvariabelen ingesteld, uw ontwikkelomgeving geverifieerd en wordt uw Agent 365-agent voorbereid op testen.

Het instellen van de testomgeving van uw agent volgt een sequentiële werkstroom:

  1. Uw omgeving configureren - Uw omgevingsconfiguratiebestand maken of bijwerken

  2. LLM-configuratie - API-sleutels ophalen en OpenAI- of Azure OpenAI-instellingen configureren

  3. Verificatie configureren - Agentische verificatie instellen

  4. Naslaginformatie over omgevingsvariabelen - Vereiste omgevingsvariabelen configureren:

    1. Verificatievariabelen
    2. Configuratie van MCP-eindpunt
    3. Waarneembaarheidsvariabelen
    4. Configuratie van agenttoepassingsserver

Nadat u deze stappen hebt voltooid, kunt u beginnen met het testen van uw agent in Agents Playground.

Step 1: Configureer uw omgeving

Uw configuratiebestand instellen:

cp .env.template .env

Notitie

Raadpleeg de voorbeelden van de Microsoft Agent 365 SDK om configuratiesjablonen met de vereiste velden te vinden.

Stap 2: LLM-configuratie

Configureer OpenAI- of Azure OpenAI-instellingen voor lokaal testen. Voeg uw API-sleutels en service-eindpunten toe, die zijn verkregen uit de vereisten voor uw configuratiebestand, samen met eventuele modelparameters.

Toevoegen aan uw .env-bestand:

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

Python LLM-omgevingsvariabelen

Variabele Omschrijving Vereist Voorbeeld
OPENAI_API_KEY API-sleutel voor OpenAI-service Voor OpenAI sk-proj-...
AZURE_OPENAI_API_KEY API-sleutel voor Azure OpenAI-service Voor Azure OpenAI a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT Azure OpenAI-service-eindpunt-URL Voor Azure OpenAI https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Implementatienaam in Azure OpenAI Voor Azure OpenAI gpt-4
AZURE_OPENAI_API_VERSION API-versie voor Azure OpenAI Voor Azure OpenAI 2024-02-15-preview

Stap 3: Verificatiewaarden configureren voor de verificatie van de agentidentiteit

Gebruik de A365 CLI-opdracht a365 config display om de blauwdrukreferenties van uw agent op te halen.

a365 config display -g

Met deze opdracht wordt de blauwdrukconfiguratie van de agent weergegeven. Kopieer de volgende waarden:

Value Omschrijving
agentBlueprintId De client-id van uw agent
agentBlueprintClientSecret Het clientgeheim van uw agent
tenantId Uw Microsoft Entra-tenant-id

Gebruik deze waarden om agentische verificatie in uw agent te configureren:

Voeg de volgende instellingen toe aan uw .env-bestand, waarbij u de waarden van de tijdelijke aanduiding vervangt door uw werkelijke referenties:

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
Variabele Omschrijving Vereist Voorbeeld
USE_AGENTIC_AUTH Agentische verificatiemodus inschakelen Ja true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID Client-id van agentblauwdruk van a365 config display -g Ja 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Clientgeheim van agentblauwdruk van a365 config display -g Ja abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID Microsoft Entra-tenant-ID van a365 config display -g Ja adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

Notitie

Voor .NET moet u er ook voor zorgen dat USE_AGENTIC_AUTH=true is ingesteld op launchSettings.json (zie Stap 4: Referentie voor omgevingsvariabelen)

Stap 4: Verwijzing naar omgevingsvariabelen

Voltooi de installatie van uw omgeving door de volgende vereiste omgevingsvariabelen te configureren:

Verificatievariabelen

Configureer de verificatieverwerkingsinstellingen, die vereist zijn om agentische verificatie goed te laten werken.

Toevoegen aan uw .env-bestand:

# Agentic Authentication Settings
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE=AgenticUserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES=https://graph.microsoft.com/.default
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME=service_connection

# Connection Mapping
CONNECTIONSMAP_0_SERVICEURL=*
CONNECTIONSMAP_0_CONNECTION=SERVICE_CONNECTION
Variabele Omschrijving Vereist
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Verificatieverwerkingstype Ja
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Verificatiebereiken voor Microsoft Graph Ja
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Alternatieve naam van blauwdrukverbinding Ja
CONNECTIONSMAP_0_SERVICEURL Service-URL-patroon voor verbindingstoewijzing Ja
CONNECTIONSMAP_0_CONNECTION Verbindingsnaam voor toewijzing Ja

Configuratie van MCP-eindpunt

De MCP-eindpuntconfiguratie (Model Context Protocol) is vereist om te specificeren met welk Agent 365-platformeindpunt uw agent verbinding moet maken. Wanneer u het hulpprogrammamanifest genereert dat de hulpprogrammaservers voor uw agent definieert, moet u het MCP-platformeindpunt opgeven. Dit eindpunt bepaalt met welke omgeving (preproductie, test of productie) de MCP-hulpprogrammaservers verbinding maken met Microsoft 365-integratiemogelijkheden.

Toevoegen aan uw .env-bestand:

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
Variabele Omschrijving Vereist Standaardinstelling Voorbeeld
MCP_PLATFORM_ENDPOINT URL van MCP-platformeindpunt (preproductie, test of productie) Nee Productie-eindpunt

Belangrijk: als MCP_PLATFORM_ENDPOINT niet is opgegeven, wordt het standaard ingesteld op het productie-eindpunt.

Waarneembaarheidsvariabelen

Configureer deze vereiste variabelen om logboekregistratie en gedistribueerde tracering voor uw agent in te schakelen. Meer informatie over waarneembaarheidsfuncties en aanbevolen procedures

Notitie

De waarneembaarheidsconfiguratie is hetzelfde in alle talen.

Variabele Omschrijving Standaardinstelling Voorbeeld
ENABLE_A365_OBSERVABILITY Waarneembaarheid in-/uitschakelen false true
ENABLE_A365_OBSERVABILITY_EXPORTER Traceringen exporteren naar de waarneembaarheidsservice false true
OBSERVABILITY_SERVICE_NAME Servicenaam voor tracering Naam agent my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE Servicenaamruimte agent365-samples my-company-agents

Configuratie van agenttoepassingsserver

Configureer de poort waarop de agenttoepassingsserver wordt uitgevoerd. Dit is optioneel en is van toepassing op Python- en JavaScript-agents.

Toevoegen aan uw .env-bestand:

# Server Configuration
PORT=3978
Variabele Omschrijving Vereist Standaardinstelling Voorbeeld
PORT Poortnummer waar de agentserver wordt uitgevoerd Nee 3978 3978

Afhankelijkheden installeren en de agenttoepassingsserver starten

Zodra uw omgeving is geconfigureerd, moet u de vereiste afhankelijkheden installeren en de agenttoepassingsserver lokaal starten om te testen.

Afhankelijkheden installeren

uv pip install -e .

Met deze opdracht worden de pakketafhankelijkheden gelezen, die zijn gedefinieerd en pyproject.toml geïnstalleerd vanuit PyPI. Wanneer u een volledig nieuwe agenttoepassing maakt, moet u een pyproject.toml bestand maken om uw afhankelijkheden te definiëren. Voorbeeldagenten uit de opslagplaats met voorbeelden hebben deze pakketten al gedefinieerd. U kunt ze toevoegen of bijwerken indien nodig.

De agenttoepassingsserver starten

python <main.py>

Vervang <main.py> door de naam van uw belangrijkste Python-bestand, dat het toegangspunt voor uw agenttoepassing bevat (bijvoorbeeld start_with_generic_host.py, app.py of main.py).

Of gebruik uv:

uv run python <main.py>

Uw agentserver moet nu worden uitgevoerd en klaar zijn voor het ontvangen van aanvragen van Agents Playground- of Microsoft 365-toepassingen.

Agent testen in Agents Playground

Agents Playground is een lokaal testprogramma, waarmee de Microsoft 365-omgeving wordt gesimuleerd zonder dat hiervoor een volledige tenant hoeft te worden ingesteld. Het is de snelste manier om de logica en hulpprogramma-aanroepen van uw agent te valideren. Zie Testen with Agents Playground voor meer informatie.

Open een nieuwe terminal (PowerShell in Windows) en start Agents Playground:

agentsplayground

Hiermee opent u een webbrowser met de interface Agents Playground. Het hulpprogramma geeft een chatinterface weer waarin u berichten naar uw agent kunt verzenden.

Basistest

Controleer eerst of uw agent juist is geconfigureerd. Een bericht verzenden naar de agent:

What can you do?

De agent moet reageren met de instructies waarmee deze is geconfigureerd, op basis van de systeemprompt en mogelijkheden van uw agent. Dit bevestigt dat:

  • Uw agent wordt correct uitgevoerd
  • De agent kan berichten verwerken en erop reageren
  • De communicatie tussen Agents Playground en uw agent werkt

Aanroepen van testhulpprogramma's

Nadat u uw MCP-hulpprogrammaservers hebt geconfigureerd in toolingManifest.json (zie Hulpprogramma's voor installatie-instructies), testhulpprogramma-aanroepen met voorbeelden zoals deze:

Controleer eerst welke hulpprogramma's beschikbaar zijn:

List all tools I have access to

Test vervolgens specifieke hulpprogramma-aanroepen:

Hulpprogramma's voor e-mail

Send email to your-email@example.com with subject "Test" and message "Hello from my agent"

Verwacht antwoord: de agent verzendt een e-mail met behulp van de Mail MCP-server en bevestigt dat het bericht is verzonden.

Hulpmiddelen voor agenda's

List my calendar events for today

Verwacht antwoord: de agent haalt uw agendagebeurtenissen voor de huidige dag op en geeft deze weer.

SharePoint-hulpprogramma's

List all SharePoint sites I have access to

Verwacht antwoord: de agent voert query's uit op SharePoint en retourneert een lijst met sites waar u toegang toe hebt.

U kunt de aanroepen van het hulpprogramma bekijken in:

  • Het chatvenster - bekijk het antwoord van de agent en eventuele hulpprogramma-aanroepen
  • Het deelvenster Logboek - gedetailleerde activiteitsgegevens bekijken, waaronder hulpprogrammaparameters en antwoorden

Testen met meldingsactiviteiten

Tijdens lokale ontwikkeling kunt u meldingsscenario's testen, door aangepaste activiteiten in Agents Playground te simuleren. Hiermee kunt u de verwerking van meldingen van uw agent controleren voordat u deze implementeert in productie.

Voordat u meldingsactiviteiten test, moet u het volgende doen:

Voor meldingen is zowel de juiste configuratie van hulpprogramma's als het instellen van meldingen vereist om correct te kunnen werken. U kunt scenario's zoals e-mailmeldingen of Word-opmerkingen testen met behulp van de functie voor aangepaste activiteiten.

Aangepaste activiteiten verzenden:

  1. Start uw agent en Agents Playground
  2. Navigeer in Agents Playground naar Een activiteit simuleren>Aangepaste activiteit
  3. Kopieer de conversationId uit de activiteit (de gespreks-id wordt gewijzigd telkens wanneer Agents Playground opnieuw wordt gestart)
  4. Plak de JSON van uw aangepaste activiteit en werk het personal-chat-id veld bij met de gespreks-id die u hebt gekopieerd. Raadpleeg het voorbeeld van een e-mailmelding
  5. Selecteer Activiteit verzenden
  6. Het resultaat weergeven in zowel het chatgesprek als het logboekvenster

E-mailmelding

Hiermee wordt een e-mailbericht gesimuleerd dat naar de agent wordt verzonden. Vervang tijdelijke aanduidingen door de werkelijke agentgegevens:

{
  "type": "message",
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "timestamp": "2025-09-24T17:40:19+00:00",
  "serviceUrl": "http://localhost:56150/_connector",
  "channelId": "agents",
  "name": "emailNotification",
  "from": {
    "id": "manager@contoso.com",
    "name": "Agent Manager",
    "role": "user"
  },
  "recipient": {
    "id": "agent@contoso.com",
    "name": "Agent",
    "agenticUserId": "<your-agentic-user-id>",
    "agenticAppId": "<your-agent-app-id>",
    "tenantId": "<your-tenant-id>"
  },
  "conversation": {
    "conversationType": "personal",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "id": "personal-chat-id"
  },
  "membersAdded": [],
  "membersRemoved": [],
  "reactionsAdded": [],
  "reactionsRemoved": [],
  "locale": "en-US",
  "attachments": [],
  "entities": [
    {
      "id": "email",
      "type": "productInfo"
    },
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "type": "emailNotification",
      "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "conversationId": "personal-chat-id",
      "htmlBody": "<body dir=\"ltr\">\n<div class=\"elementToProof\" style=\"font-family: Aptos, Aptos_EmbeddedFont, Aptos_MSFontService, Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\">\nYour email message content here</div>\n\n\n</body>"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
    }
  },
  "listenFor": [],
  "textHighlights": []
}

Waarneembaarheidslogboeken weergeven

Als u waarneembaarheidslogboeken wilt weergeven tijdens lokale ontwikkeling, voorziet u uw agent van een waarneembaarheidscode (zie Waarneembaarheid voor codevoorbeelden) en configureert u de omgevingsvariabelen zoals beschreven in Waarneembaarheidsvariabelen. Zodra deze is geconfigureerd, worden realtime traceringen weergegeven in de console met:

  • Traceringen voor aanroepen van agenten
  • Uitvoeringsdetails van hulpprogramma
  • LLM-deductie-aanroepen
  • Invoer- en uitvoerberichten
  • Tokengebruik
  • Reactietijden
  • Foutgegevens

Deze logboeken helpen u bij het opsporen van problemen, het begrijpen van het gedrag van agenten en het optimaliseren van de prestaties.

Probleemoplossing

Deze sectie bevat oplossingen voor veelvoorkomende problemen, die kunnen optreden bij het lokaal testen van uw agent.

Verbindings- en omgevingsproblemen

Deze problemen hebben betrekking op netwerkconnectiviteit, poortconflicten en problemen met de omgevingsinstellingen, die kunnen verhinderen dat uw agent correct communiceert.

Verbindingsproblemen met Agents Playground

Symptoom: Agents Playground kan geen verbinding maken met uw agent

Oplossingen:

  • Controleren of de agentserver wordt uitgevoerd
  • Controleer of de poortnummers overeenkomen tussen uw agent en Agents Playground
  • Zorg ervoor dat er geen firewallregels zijn die lokale verbindingen blokkeren
  • Start de agent en Agents Playground opnieuw op

Verouderde versie van Agents Playground

Symptoom: onverwachte fouten of ontbrekende functies in Agents Playground

Oplossing: Agents Playground verwijderen en opnieuw installeren:

winget uninstall agentsplayground
winget install agentsplayground

Poortconflicten

Symptoom: fout die aangeeft dat de poort al in gebruik is

Oplossing:

  • Alle andere exemplaren van uw agent stoppen
  • De poort in uw configuratie wijzigen
  • Alle processen beëindigen met behulp van de poort:
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

Kan DeveloperMCPServer niet toevoegen

Symptoom: fout bij het toevoegen van DeveloperMCPServer in VS Code

Oplossing: sluit Visual Studio Code en open deze opnieuw en probeer de server opnieuw toe te voegen.

Verificatieproblemen

Deze problemen treden op wanneer uw agent niet goed kan worden geverifieerd met Microsoft 365-services of wanneer referenties zijn verlopen of onjuist zijn geconfigureerd.

Bearer-token is verlopen

Symptoom: verificatiefouten of 401 Niet-geautoriseerde antwoorden

Oplossing: Bearer-tokens verlopen na ongeveer 1 uur. Een nieuw token verkrijgen en uw configuratie bijwerken.

Agentische verificatiefouten in Python

Symptoom: fout bij het verkrijgen van een agentisch exemplaartoken

Oplossing: controleer de ALT_BLUEPRINT_NAME instelling in uw .env:

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

Problemen met hulpprogramma's en meldingen

Deze problemen hebben betrekking op aanroepen van hulpprogramma's, interacties tussen MCP-servers en het leveren van meldingen.

E-mail niet ontvangen

Symptoom: de agent geeft aan dat e-mail is verzonden, maar u ontvangt deze niet

Oplossingen:

  • Controleer uw spam- of aanbiedingenmap
  • E-mailbezorging kan een paar minuten worden vertraagd - wacht maximaal 5 minuten
  • Controleer of het e-mailadres van de geadresseerde juist is
  • Agentlogboeken controleren op eventuele fouten tijdens het verzenden van e-mail

Reacties op opmerkingen in Word werken niet

Bekend probleem: de meldingsservice kan momenteel niet rechtstreeks reageren op opmerkingen in Word. Deze functionaliteit is in ontwikkeling.

Hulp krijgen

Als u problemen ondervindt die niet worden behandeld in deze sectie voor probleemoplossing, bekijkt u deze resources:

Microsoft Agent 365 SDK-opslagplaatsen

Meer ondersteuning

Volgende stappen

Nu u uw agent lokaal hebt getest, kunt u deze implementeren in Azure en deze publiceren naar Microsoft 365:

  • Agents implementeren en publiceren: leer hoe u uw agent implementeert in Azure Web App en deze publiceert naar het Microsoft-beheercentrum, zodat uw organisatie deze kan detecteren en inhuren in Microsoft 365.
  • Last updated on