Agenten testen met behulp van de Microsoft Agent 365 SDK

Test vóór de implementatie uw agent lokaal met Agents Playground. 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, volgt u de Agent 365 Ontwikkelingslevenscyclus om te testen in Microsoft 365-toepassingen zoals Teams, Word en Outlook.

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 wordt beschreven hoe u omgevingsvariabelen instelt, uw ontwikkelomgeving verifieert en uw Agent 365-agent voorbereidt op testen.

Stel de testomgeving van uw agent in door deze sequentiële werkstroom te volgen:

  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 voor configuratiesjablonen die de vereiste velden tonen de voorbeelden van de Microsoft Agent 365 SDK.

Stap 2: LLM-configuratie

Configureer OpenAI- of Azure OpenAI-instellingen voor lokaal testen. Voeg uw API-sleutels en service-eindpunten toe 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: verificatie configureren voor uw agent

Kies een van de volgende verificatiemethoden voor uw agent:

  • Agentische verificatie: gebruiken voor productiescenario's wanneer een agentische gebruikersidentiteit beschikbaar is.
  • (On-Behalf-Of) OBO-verificatie: gebruiken voor productiescenario's wanneer u gedelegeerde gebruikersrechten nodig hebt zonder een agentische gebruikersidentiteit.
  • Bearer-tokenverificatie: alleen gebruiken voor vroege ontwikkelings- en testscenario’s voordat productieverificatie is geconfigureerd.

Agentverificatie

Open a365.generated.config.json in uw werkmap om uw agentblauwdrukreferenties op te halen. Kopieer de volgende waarden:

Waarde 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.generated.config.json Ja 11112222-bbbb-3333-cccc-4444dddd5555
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Clientgeheim van agentblauwdruk van a365.generated.config.json Ja abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID Microsoft Entra-tenant-ID van a365.generated.config.json Ja 22223333-cccc-4444-dddd-5555eeee6666

OBO-verificatie

Met On-Behalf-Of (OBO)-verificatie kan uw agent MCP-servertools benaderen met machtigingen van een gemachtigde gebruiker zonder dat een agentgebruikersidentiteit vereist is. In deze stroom ontvangt de agent een gedelegeerd token van de gebruiker en wisselt deze in om acties namens de gebruiker uit te voeren.

OBO-verificatie is geschikt voor productiescenario's waarin:

  • Uw agent geen eigen gebruikersidentiteit als agent heeft.
  • U toegang moet krijgen tot bronnen met gebruikersspecifieke machtigingen.
  • U wilt dat de agent namens de geverifieerde gebruiker handelt.

Zie voor details over hoe de OBO-stroom werkt Verificatiestromen. Zie voor een volledig implementatievoorbeeld het OBO-autorisatievoorbeeld in de SDK voor Microsoft 365-agenten.

Bearer-tokenverificatie

Voor vroege ontwikkelings- en testscenario's waarin productieverificatie niet is geconfigureerd, kunt u bearer-tokenverificatie gebruiken om uw agent te testen. Deze methode gebruikt interactieve browserverificatie om een gedelegeerd toegangstoken te verkrijgen. Door dit token te gebruiken kan uw agent MCP Server-tools aanroepen met uw gebruikersrechten. Deze aanpak simuleert hoe een agentgebruiker in productie toegang krijgt tot resources zonder dat er een daadwerkelijk agentexemplaar nodig is.

Gebruik eerst a365 develop add-permissions om de vereiste MCP-serverrechten aan uw toepassing toe te voegen:

a365 develop add-permissions

Gebruik vervolgens a365 develop get-token om bearer-tokens op te halen en te configureren:

a365 develop get-token

De opdracht get-token voert automatisch het volgende uit:

  • Leest ToolingManifest.json om alle geconfigureerde MCP-servers te ontdekken.
  • Verwerft één token per doelgroep; per-server MCP-servers ontvangen een token dat is afgestemd op hun specifieke app-id; gedeelde ATG-servers ontvangen een token dat is gekoppeld aan de gedeelde Agent Tools Gateway app-id (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1).
  • Schrijft tokens naar uw projectconfiguratiebestanden:
    • Per-server tokens: BEARER_TOKEN_<SERVER_NAME> (bijvoorbeeld BEARER_TOKEN_MCP_MAILTOOLS)
    • Gedeeld ATG-token: BEARER_TOKEN

Voeg, voordat u get-token uitvoert, plaatsvervangende items toe aan uw projectconfiguratiebestand:

  • .NET: voeg "BEARER_TOKEN": "" en/of "BEARER_TOKEN_<SERVER_NAME>": "" toe aan environmentVariables in elk profiel in Properties/launchSettings.json. De opdracht werkt alleen profielen bij waarin deze sleutels al zijn gedefinieerd.
  • Python/Node.js: maak een .env-bestand met BEARER_TOKEN= en/of BEARER_TOKEN_<SERVER_NAME>= voordat u uitvoert. Als het bestand ontbreekt, slaat de opdracht het opslaan over en toont het richtlijnen.

Notitie

Als u a365 develop get-token --app-id <id> zonder een a365.config.json-bestand uitvoert, worden tokens niet automatisch opgeslagen. Kopieer en plak ze handmatig in Properties/launchSettings.json (voor .NET) of in uw .env-bestand (voor Python/Node.js).

Bearer-tokens verlopen na ongeveer een uur. Gebruik a365 develop get-token om verlopen tokens te verversen.

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

Bearer-tokenvariabelen (alleen lokale ontwikkeling)

Variabele Omschrijving Vereist
BEARER_TOKEN Gedeeld bearer-token voor gezamenlijke ATG MCP-servers. De opdracht a365 develop get-token schrijft dit token automatisch. Voor gezamenlijke ATG-lokale ontwikkeling
BEARER_TOKEN_<SERVER_NAME> Bearer-token per-server. De SDK bepaalt de naam door mcpServerName uit ToolingManifest.json in hoofdletters te zetten (bijvoorbeeld, mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS). De opdracht a365 develop get-token schrijft dit token automatisch. Voor lokale ontwikkeling per server
SKIP_TOOLING_ON_ERRORS Stel dit in om true terug te vallen naar een kale LLM als MCP-tools niet worden geladen. Alleen gerespecteerd wanneer ASPNETCORE_ENVIRONMENT of ENVIRONMENT is Development. Nee

Belangrijk

Bearer-tokens zijn alleen voor lokale ontwikkeling. Stel BEARER_TOKEN of BEARER_TOKEN_<SERVER_NAME> nooit in bij productie-implementaties.

Configuratie van MCP-eindpunt

Specificeer het Agent 365-platformeindpunt waarmee uw agent verbinding maakt. Wanneer u het toolingmanifest genereert dat de toolingservers 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 Standaard Voorbeeld
MCP_PLATFORM_ENDPOINT URL van MCP-platformeindpunt (preproductie, test of productie) Nee Productie-eindpunt

Belangrijk: als u MCP_PLATFORM_ENDPOINT niet specificeert, gebruikt de app het productie-eindpunt.

Notitie

Als u de mock tooling-server vanuit de CLI gebruikt, stel dan het eindpunt in op http://localhost:<port> door het poortnummer te specificeren dat u hebt gebruikt. De standaardpoort is 5309.

Waarneembaarheidsvariabelen

Configureer deze vereiste variabelen om logboekregistratie en gedistribueerde tracering voor uw agent in te schakelen. Zie voor de volledige lijst van omgevingsvariabelen, configuratieopties en codevoorbeelden Waarneembaarheid van agent.

Notitie

De waarneembaarheidsconfiguratie is hetzelfde in alle talen. Raadpleeg Configuratie voor meer informatie.

Variabele Omschrijving Standaard Voorbeeld
ENABLE_A365_OBSERVABILITY_EXPORTER Traceringen exporteren naar de waarneembaarheidsservice. Indien false reikt naar export in plaats daarvan naar de console. false true
A365_OBSERVABILITY_LOG_LEVEL Intern logniveau voor de waarneembaarheids-SDK Nuttig voor het debuggen van exportproblemen tijdens het testen. none info, warn, error, debug

Configuratie van agenttoepassingsserver

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

Toevoegen aan uw .env-bestand:

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

Afhankelijkheden installeren en de agenttoepassingsserver starten

Nadat 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 wordt nu uitgevoerd en is klaar 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.

Agents Playground configureren voor agentische verificatie

Notitie

Deze configuratie is alleen vereist wanneer u agentische verificatie gebruikt. Als u bearer token-authenticatie gebruikt, kunt u deze sectie overslaan en direct doorgaan naar Basistest.

Wanneer u agentische verificatie gebruikt, configureert u het Agents Playground YAML-bestand met de gegevens van uw agent:

  1. Stel het configuratiebestand in: maak het bestand .m365agentsplayground.yml of werk het bij in de map waar u Agents Playground uitvoert. Zie Teams-context aanpassen voor gedetailleerde installatie-instructies.

  2. Werk de botconfiguratie bij: voeg de volgende botgegevens toe aan uw .m365agentsplayground.yml-bestand, waarbij de tijdelijke waarden worden vervangen door uw daadwerkelijke agentreferenties:

    bot:
  id: <your-agent-email>@<your-tenant>.onmicrosoft.com
  name: <Your Agent Name>
  role: agenticUser
  agenticUserId: <your-agentic-user-id>
  agenticAppId: <your-agentic-app-id>
    Eigenschap Beschrijving Vereist
    id Het e-mailadres van uw agentgebruiker in de indeling agentusername@tenant.onmicrosoft.com Ja
    name Weergavenaam voor uw agentgebruiker Ja
    role Moet worden ingesteld op agenticUser voor agentische verificatie Ja
    agenticUserId De object-id van de agentgebruiker. U vindt deze waarde in het Microsoft Entra-beheercentrum op de profielpagina van de agentgebruiker. Ja
    agenticAppId De agent-id van de agentgebruiker. U vindt deze waarde in het Microsoft Entra-beheercentrum op de profielpagina van de agentgebruiker. Ja

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

agentsplayground

Deze opdracht opent een webbrowser met de Agents Playground-interface. 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 reageert met de instructies waarmee deze is geconfigureerd, op basis van de systeemprompt en mogelijkheden van uw agent. Dit antwoord 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 Tooling voor installatie-instructies), test u hulpprogramma-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 de respons van de agent en eventuele hulpprogramma-aanroepen.
  • Het paneel Logboek: bekijk gedetailleerde activiteitsgegevens, waaronder hulpprogrammaparameters en responsen.

Testen met meldingsactiviteiten

Tijdens lokale ontwikkeling test u meldingsscenario's met behulp van de ingebouwde meldingstriggers in Agents Playground.

Schermopname van de Agents Playground-interface met het menu Een activiteit simuleren uitgeklapt, waarin opties voor het activeren van meldingsactiviteiten worden weergegeven, waaronder E-mail verzenden en Vermelden in Word.

Voordat u meldingsactiviteiten test, moet u het volgende doen:

E-mailmeldingen testen

De afhandeling van e-mailmeldingen testen:

  1. Start uw agent en Agents Playground.
  2. Ga in Agents Playground naar Een activiteit simuleren>Meldingsactiviteit activeren.
  3. Selecteer E-mail verzenden.
  4. Werk in de payloaddialoog de e-maildetails voor simulatie bij, zoals de afzendernaam en de inhoud van de e-mail, indien nodig.
  5. Selecteer Activiteit verzenden.
  6. Het resultaat weergeven in zowel het chatgesprek als het logboekvenster.

De agent ontvangt een gesimuleerde e-mailmelding en verwerkt deze volgens uw afhandelingslogica voor meldingen. Zie voor meer informatie over de structuur van de e-mailmeldingspayload E-mailmeldingspayload.

Meldingen over Word-vermelding testen

Meldingen over vermeldingen in Word-documenten testen:

  1. Start uw agent en Agents Playground.
  2. Ga in Agents Playground naar Een activiteit simuleren>Meldingsactiviteit activeren.
  3. Selecteer Vermelding in Word.
  4. Werk in de payloaddialoog de details van het simulatiecommentaar bij, zoals de document-id en de commentaartekst, indien nodig.
  5. Selecteer Activiteit verzenden.
  6. Het resultaat weergeven in zowel het chatgesprek als het logboekvenster.

De agent ontvangt een gesimuleerde melding over een Word-vermelding en reageert volgens uw logica voor meldingsverwerking. Zie Payload voor documentcommentaarmelding voor details over de structuur van de payload voor Word-commentaarmelding.

De installatie- en verwijderingsgebeurtenissen van de agent testen

Wanneer Agents Playground verbinding maakt met uw agent, stuurt het automatisch een InstallationUpdate-activiteit met actie add. Als u een installatiehandler implementeert, verschijnt het welkomstbericht van uw agent direct in de chat nadat de verbinding tot stand is gekomen.

De afhandeling van installatiegebeurtenissen verifiëren:

  1. Start uw agentserver.
  2. Open Agents Playground. De playground maakt verbinding met uw agent en activeert automatisch de installatiegebeurtenis.
  3. Bevestig dat het welkomstbericht in het chatgesprek verschijnt.

Schermopname van de Agents Playground-interface met het welkomstbericht van de agent: Dank u voor het inhuren! Ik kijk ernaar uit om u te ondersteunen in uw professionele traject!' weergegeven in het chatgesprek en het logvenster, nadat de installatiegebeurtenis automatisch is geactiveerd.

Zie Agent-installatie- en -deïnstallatiegebeurtenissen afhandelen voor details over het implementeren van de handler.

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. Zie voor stapsgewijze validatie-instructies en de verwachte loguitvoer Lokaal valideren. Eenmaal geconfigureerd verschijnen realtime traceringen in de console die het volgende tonen:

  • 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. Gebruik vóór publicatie Valideren voor publicatie in de Store om te bevestigen dat alle vereiste kenmerken aanwezig zijn.

Volgende stappen

Nadat u uw agent lokaal hebt getest, implementeert u deze naar Azure en publiceert u deze in Microsoft 365.

Om uw agent te testen in Microsoft 365-toepassingen zoals Teams, Word en Outlook raadpleegt u de Agent 365 Ontwikkelingslevenscyclus.

Probleemoplossing

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

Fooi

De Agent 365 Probleemoplossingsgids bevat algemene aanbevelingen voor probleemoplossing, best practices en links naar probleemoplossingsinhoud voor elk onderdeel van de Agent 365-ontwikkelingscyclus.

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.
  • Probeer de agent en Agents Playground opnieuw te starten.

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.
  • Stop alle processen 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 Visual Studio Code.

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

Verificatie- en tokenproblemen

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

Symptomen:

  • 401 Ongeautoriseerde fouten
  • "Bearer-token is verlopen"-berichten
  • Fouten met agentische verificatie

Hoofdoorzaak:

  • Tokens verlopen na ongeveer een uur
  • Onjuiste verificatieconfiguratie
  • Ontbrekende of ongeldige referenties

Oplossingen:

  • Voor verval van bearer-token

    Ververs uw token en werk uw omgevingsvariabelen bij.

    # Get a new token
a365 develop get-token

# Update your .env file with the new token

  • Voor per-server bearer-tokenfouten

    Controleer of uw configuratiebestand plaatsvervangende invoer bevat voor elke server (BEARER_TOKEN_<SERVER_NAME>) en voer a365 develop get-token opnieuw uit om ze te vullen. De SDK leidt de variabelenaam af door mcpServerName in ToolingManifest.json om te zetten naar hoofdletters en koppeltekens te vervangen door onderstrepingstekens (bijvoorbeeld mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS).

  • Voor agentische verificatiefouten (Python)

    Controleer uw .env-bestand:

    # Should be (with underscore):
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

# Not:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

  • Voor ontbrekende referenties

    Bevestig dat de vereiste referenties aanwezig zijn voordat u test.

    Zorg ervoor dat .env of appsettings.json het volgende bevat:

    • API-sleutels en geheimen
    • Tenant-id
    • Client-ID
    • Blauwdruk-id (als agentische verificatie wordt gebruikt)

    Verificatie:

    Test met een eenvoudig verzoek in Agents Playground. U zou een antwoord moeten ontvangen zonder 401-fouten.

  • 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 junk-map.
  • De bezorging van e-mail kan vertraagd worden en enkele minuten duren. Wacht maximaal vijf minuten.
  • Controleer of het e-mailadres van de geadresseerde juist is.
  • Controleer agentlogboeken 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.

Berichten komen niet bij de agent aan

Symptoom: Uw agenttoepassing ontvangt geen berichten die naar de agent in Teams zijn verzonden.

Mogelijke oorzaken:

  • De Ontwikkelaarsportal is niet geconfigureerd met de agentblauwdruk.
  • Azure Web App-problemen (implementatiefouten, app die niet draait, configuratiefouten).
  • Het agentexemplaar wordt niet correct gemaakt in Teams.

Oplossingen:

  • Controleer de Ontwikkelaarsportal-configuratie:

    Zorg ervoor dat u de agentblauwdrukconfiguratie voltooit in Ontwikkelaarsportal. Leer hoe u een agentblauwdruk configureert in Ontwikkelaarsportal.

  • De status van de Azure Web App controleren:

    Als u uw agent naar Azure implementeert, controleer dan of de webapp goed draait:

    1. Ga naar Azure Portal.
    2. Ga naar uw Web App-resource.
    3. Controleer Overzicht>Status (moet "Actief" tonen).
    4. Controleer Logstroom onder Bewaking op runtimefouten.
    5. Bekijk de logboeken van Implementatiecentrum om te verifiëren dat de implementatie is geslaagd.
    6. Controleer of Configuratie>Toepassingsinstellingen alle benodigde omgevingsvariabelen bevat.

  • Maken van agentexemplaar verifiëren:

    Zorg ervoor dat u het agentexemplaar correct maakt in Microsoft Teams:

    1. Microsoft Teams openen.
    2. Ga naar Apps en zoek naar uw agent.
    3. Controleer of de agent in de zoekresultaten verschijnt.
    4. Als de agent niet wordt gevonden, controleer of deze is gepubliceerd in Microsoft 365-beheercentrum - Agents.
    5. Maak een nieuw exemplaar door Toevoegen te selecteren bij uw agent.
    6. Zie Onboard agents voor gedetailleerde instructies.

Problemen met waarneembaarheidslogboeken oplossen

Als de waarneembaarheidslogboeken van uw agent niet verschijnen zoals verwacht, raadpleeg dan Problemen oplossen in de gids over waarneembaarheid.

  • Last updated on