Del via

Test agenter ved hjælp af Microsoft Agent 365 SDK

Vigtigt

Du skal være en del af Frontier-forhåndsversionsprogrammet for at få tidlig adgang til Microsoft Agent 365. Frontier forbinder dig direkte med Microsofts seneste AI-innovationer. Frontier-forhåndsversioner er underlagt de eksisterende forhåndsversionsbetingelser i dine kundeaftaler. Da disse funktioner stadig er under udvikling, kan deres tilgængelighed og egenskaber ændre sig over tid.

Test din agent lokalt ved hjælp af Agents Playground før udrulningen. I denne vejledning beskrives konfiguration af dit udviklingsmiljø, konfiguration af godkendelse og validering af din agents funktionalitet med testværktøjet Agents Playground.

Når din agent arbejder lokalt, kan du udrulle og publicere den til test i Microsoft 365-programmer som Teams.

Forudsætninger

Før du begynder at teste din agent, skal du sørge for, at du har installeret følgende forudsætninger:

Almindelige forudsætninger

Sprogspecifikke forudsætninger

Konfigurer agenttestmiljø

I dette afsnit beskrives indstilling af miljøvariabler, godkendelse af dit udviklingsmiljø og forberedelse af din Agent 365-baserede agent til test.

Konfiguration af dit agenttestmiljø følger en sekventiel arbejdsproces:

  1. Konfigurer dit miljø – Opret eller opdater miljøkonfigurationsfilen

  2. LLM-konfiguration – Hent API-nøgler, og konfigurer OpenAI- eller Azure OpenAI-indstillinger

  3. Konfigurer godkendelse – Konfigurer agentbaseret godkendelse

  4. Reference til miljøvariabler – Konfigurer påkrævede miljøvariabler:

    1. Godkendelsesvariabler
    2. Konfiguration af MCP-slutpunkt
    3. Observerbarhedsvariabler
    4. Konfiguration af agentprogramserver

Når du har fuldført disse trin, er du klar til at begynde at teste din agent i Agents Playground.

Trin 1: Konfigurere dit miljø

Konfigurer konfigurationsfilen:

cp .env.template .env

Bemærk

Se Microsoft Agent 365 SDK-eksemplerne for at finde konfigurationsskabeloner, der viser obligatoriske felter.

Trin 2: Konfiguration af LLM

Konfigurer OpenAI- eller Azure OpenAI-indstillinger til lokal test. Føj dine API-nøgler og tjenesteslutpunkter, der er hentet fra forudsætningerne, til konfigurationsfilen sammen med eventuelle modelparametre.

Føj til din .env-fil:

# 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-miljøvariabler

Variabel Beskrivelse Påkrævet Eksempel
OPENAI_API_KEY API-nøgle til OpenAI-tjenesten For OpenAI sk-proj-...
AZURE_OPENAI_API_KEY API-nøgle til Azure OpenAI-tjenesten For Azure OpenAI a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT URL-adresse til Azure OpenAI-tjenesteslutpunkt For Azure OpenAI https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Installationsnavn i Azure OpenAI For Azure OpenAI gpt-4
AZURE_OPENAI_API_VERSION API-version for Azure OpenAI For Azure OpenAI 2024-02-15-preview

Trin 3: Konfigurer godkendelsesværdier for agentidentitetsgodkendelse

Brug kommandoen A365 CLI a365 config display til at hente dine legitimationsoplysninger til agentplanen.

a365 config display -g

Denne kommando viser konfigurationen af agentplanen. Kopiér følgende værdier:

Værdi Beskrivelse
agentBlueprintId Din agents klient-id
agentBlueprintClientSecret Din agents klienthemmelighed
tenantId Dit Microsoft Entra-lejer-id

Brug disse værdier til at konfigurere agentbaseret godkendelse i din agent:

Føj følgende indstillinger til filen .env, hvor pladsholderværdierne erstattes med dine faktiske legitimationsoplysninger:

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
Variabel Beskrivelse Påkrævet Eksempel
USE_AGENTIC_AUTH Aktivér agentbaseret godkendelsestilstand Ja true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID Klient-id'et for agentplanen fra a365 config display -g Ja 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Klienthemmeligheden for agentplanen fra a365 config display -g Ja abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID Microsoft Entra-lejer-id fra a365 config display -g Ja adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

Bemærk

For .NET skal du også sikre, at USE_AGENTIC_AUTH=true er angivet i launchSettings.json (se Trin 4: Reference til miljøvariabler)

Trin 4: Reference til miljøvariabler

Fuldfør konfigurationen af dit miljø ved at konfigurere følgende påkrævede miljøvariabler:

Godkendelsesvariable

Konfigurer de indstillinger for godkendelseshandler, der kræves, for at agentbaseret godkendelse fungerer korrekt.

Føj til din .env-fil:

# 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
Variabel Beskrivelse Påkrævet
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Godkendelseshandlertype Ja
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Godkendelsesområde for Microsoft Graph Ja
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Forbindelsesnavn for alternativ plan Ja
CONNECTIONSMAP_0_SERVICEURL Mønster for URL-adresse til tjeneste for forbindelsestilknytning Ja
CONNECTIONSMAP_0_CONNECTION Forbindelsesnavn for tilknytning Ja

Konfiguration af MCP-slutpunkt

Konfigurationen af MCP-slutpunktet (Model Context Protocol) er påkrævet for at angive, hvilket Agent 365-platformslutpunkt din agent skal oprette forbindelse til. Når du genererer det værktøjsmanifest, der definerer værktøjsserverne for din agent, skal du angive MCP-platformens slutpunkt. Dette slutpunkt bestemmer, hvilket miljø (præproduktion, test eller produktion) MCP-værktøjsserverne opretter forbindelse til for at få Microsoft 365-integrationsfunktioner.

Føj til din .env-fil:

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
Variabel Beskrivelse Obligatorisk Standard Eksempel
MCP_PLATFORM_ENDPOINT URL-adresse til MCP-platformslutpunkt (præproduktion, test eller produktion) Nej Slutpunkt for produktion

Vigtigt! Hvis MCP_PLATFORM_ENDPOINT ikke er angivet, er det som standard produktionsslutpunktet.

Observerbarhedsvariabler

Konfigurer disse påkrævede variabler for at aktivere logføring og distribueret sporing for din agent. Få mere at vide om funktioner til observerbarhed og bedste praksis

Bemærk

Konfigurationen af observerbarhed er den samme på tværs af alle sprog.

Variabel Beskrivelse Standard Eksempel
ENABLE_A365_OBSERVABILITY Aktivér/deaktiver observerbarhed false true
ENABLE_A365_OBSERVABILITY_EXPORTER Eksportér sporinger til observerbarhedstjenesten false true
OBSERVABILITY_SERVICE_NAME Tjenestenavn til sporing Navn på agent my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE Tjenestenavneområde agent365-samples my-company-agents

Konfiguration af agentprogramserver

Konfigurer den port, hvor agentprogramserveren kører. Dette er valgfrit og gælder for Python- og JavaScript-agenter.

Føj til din .env-fil:

# Server Configuration
PORT=3978
Variabel Beskrivelse Obligatorisk Standard Eksempel
PORT Portnummer, hvor agentserveren kører Nej 3978 3978

Installér afhængigheder, og start agentprogramserveren

Når dit miljø er konfigureret, skal du installere de påkrævede afhængigheder og starte din agentprogramserver lokalt med henblik på test.

Installer afhængighederne

uv pip install -e .

Denne kommando læser de pakkeafhængigheder, der er defineret i pyproject.toml, og installerer dem fra PyPI. Når du opretter et agentprogram fra bunden, skal du oprette en pyproject.toml-fil for at definere dine afhængigheder. Eksempelagenter fra eksempellageret har allerede disse pakker defineret. Du kan tilføje eller opdatere dem efter behov.

Start agentprogramserveren

python <main.py>

Erstat <main.py> med navnet på den primære Python-fil, der indeholder indgangspunktet for agentprogrammet (f.eks. start_with_generic_host.py, app.py eller main.py).

Eller ved hjælp af uv:

uv run python <main.py>

Din agentserver bør nu køre og være klar til at modtage anmodninger fra Agents Playground- eller Microsoft 365-programmer.

Test agent i Agents Playground

Agents Playground er et lokalt testværktøj, der simulerer Microsoft 365-miljøet uden at kræve en fuld lejerkonfiguration. Det er den hurtigste måde at validere din agents logik og aktivering af værktøjer på. Du kan få mere at vide under Test med Agents Playground.

Åbn en ny terminal (PowerShell på Windows), og start Agents Playground:

agentsplayground

Dette åbner en webbrowser med Agents Playground-grænsefladen. Værktøjet viser en chatgrænseflade, hvor du kan sende meddelelser til din agent.

Grundlæggende test

Start med at kontrollere, at agenten er konfigureret korrekt. Send en meddelelse til agenten:

What can you do?

Agenten bør svare med de instruktioner, den er konfigureret med, baseret på din agents systemprompt og funktioner. Dette bekræfter, at:

  • Din agent kører korrekt
  • Agenten kan behandle meddelelser og svare
  • Kommunikation mellem Agents Playground og din agent fungerer

Test aktivering af værktøjer

Når du har konfigureret dine MCP-værktøjsservere i toolingManifest.json (se Værktøjer for at få en konfigurationsvejledning), skal du teste aktivering af værktøjer med eksempler som disse:

Først skal du kontrollere, hvilke værktøjer der er tilgængelige:

List all tools I have access to

Test derefter aktivering af specifikke værktøjer:

Mailværktøjer

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

Forventet svar: Agenten sender en mail ved hjælp af Mail MCP-serveren og bekræfter, at meddelelsen blev sendt.

Kalenderværktøjer

List my calendar events for today

Forventet svar: Agenten henter og viser dine kalenderbegivenheder for den aktuelle dag.

SharePoint-værktøjer

List all SharePoint sites I have access to

Forventet svar: Agenten forespørger SharePoint og returnerer en liste over websteder, du har adgang til.

Du kan få vist aktivering af værktøjerne i:

  • Chatvinduet – Se agentens svar og eventuelle værktøjskald
  • Logpanelet – Se detaljerede aktivitetsoplysninger, herunder værktøjsparametre og svar

Test med meddelelsesaktiviteter

Under lokal udvikling kan du teste meddelelsesscenarier ved at simulere brugerdefinerede aktiviteter i Agents Playground. Det giver dig mulighed for at bekræfte din agents håndtering af meddelelser, før du udruller den til produktion.

Før du tester meddelelsesaktiviteter, skal du sikre dig, at du har:

Meddelelser kræver både korrekt konfiguration af værktøjer og korrekt konfiguration af meddelelser for at fungere korrekt. Du kan teste scenarier, f.eks. mailmeddelelser eller Word-kommentarer, ved hjælp af den brugerdefinerede aktivitetsfunktion.

Sådan sender du brugerdefinerede aktiviteter:

  1. Start din agent og Agents Playground
  2. I Agents Playground skal du navigere til Modelaktivitet>Brugerdefineret aktivitet
  3. Kopiér conversationId fra aktiviteten (samtale-id'et ændres, hver gang Agents Playground genstartes)
  4. Indsæt din brugerdefinerede aktivitets-JSON, og opdater feltet personal-chat-id med det samtale-id, du har kopieret. Se eksemplet på mailmeddelelsen
  5. Vælg Send aktivitet
  6. Få vist resultatet i både chatsamtalen og logpanelet

Mailbesked

Dette simulerer en mail, der er sendt til agenten. Erstat pladsholderværdier med faktiske oplysninger om din agent:

{
  "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": []
}

Få vist logge over observerbarhed

Hvis du vil have vist logge over observerbarhed under lokal udvikling, skal du instrumentere din agent med observerbarhedskode (se Observerbarhed for at få kodeeksempler) og konfigurere miljøvariabler som beskrevet i Observerbarhedsvariabler. Når de er konfigureret, vises sporinger i realtid i konsollen, der viser:

  • Sporinger af agentaktivering
  • Oplysninger om værktøjsudførelse
  • LLM-inferenskald
  • Input- og outputmeddelelser
  • Brug af token
  • Svartider
  • Fejloplysninger

Disse logge hjælper dig med at foretage fejlfinding af problemer, forstå agentens funktionsmåde og optimere ydeevnen.

Fejlfinding

Dette afsnit indeholder løsninger på almindelige problemer, du kan støde på, når du tester din agent lokalt.

Problemer med forbindelse og miljø

Disse problemer vedrører netværksforbindelse, portkonflikter og problemer med miljøkonfiguration, der kan forhindre agenten i at kommunikere korrekt.

Agents Playground-forbindelsesproblemer

Symptom: Agenter Playground kan ikke oprette forbindelse til din agent

Løsninger:

  • Kontrollér, at agentserveren kører
  • Kontrollér, at portnumrene stemmer overens mellem din agent og Agent Playground
  • Sørg for, at der ikke er nogen firewallregler, som blokerer lokale forbindelser
  • Prøv at genstarte både agenten og Agents Playground

Forældet version af Agents Playground

Symptom: Uventede fejl eller manglende funktioner i Agents Playground

Løsning: Fjern og geninstaller Agents Playground:

winget uninstall agentsplayground
winget install agentsplayground

Portkonflikter

Symptom: Fejl, der er tegn på, at porten allerede er i brug

Løsning:

  • Stop alle andre forekomster af din agent
  • Skift porten i konfigurationen
  • Afslut alle processer, der bruger porten:
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

DeveloperMCPServer kan ikke tilføjes

Symptom: Fejl under forsøg på at tilføje DeveloperMCPServer i VS Code

Løsning: Luk og åbn Visual Studio Code igen, og prøv derefter at tilføje serveren igen.

Godkendelsesfejl

Disse problemer opstår, når din agent ikke kan godkende korrekt med Microsoft 365-tjenester, eller når legitimationsoplysningerne er udløbet eller konfigureret forkert.

Ihændehavertokenet er udløbet

Symptom: Godkendelsesfejl eller 401 Uautoriserede svar

Løsning: Ihændehavertokens udløber efter ca. 1 time. Hent et nyt token, og opdater konfigurationen.

Fejl i agentbaseret godkendelse i Python

Symptom: Fejl under hentning af agentbaseret forekomsttoken

Løsning: Kontrollér indstillingen ALT_BLUEPRINT_NAME i .env:

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

Problemer med værktøjer og meddelelser

Disse problemer omfatter problemer med aktivering af værktøjer, MCP-serverinteraktioner og levering af meddelelser.

Mail ikke modtaget

Symptom: Agenten angiver, at mailen blev sendt, men du modtager den ikke

Løsninger:

  • Kontrollér mappen Uønsket post/spam
  • Levering af mail kan forsinkes med et par minutter – vent op til 5 minutter
  • Kontrollér, at modtagermailadressen er korrekt
  • Kontrollér agentlogge for eventuelle fejl under afsendelse af mail

Svar på Word-kommentarer fungerer ikke

Kendt problem: Meddelelsestjenesten kan i øjeblikket ikke svare direkte på Word-kommentarer. Denne funktionalitet er under udvikling.

Få hjælp

Hvis du støder på problemer, der ikke er beskrevet i dette fejlfindingsafsnit, kan du udforske disse ressourcer:

Microsoft Agent 365 SDK-lagre

Mere support

Næste trin

Nu, hvor du har testet din agent lokalt, er du klar til at udrulle den på Azure og publicere den i Microsoft 365:

  • Udrul og publicer agenter: Få mere at vide om, hvordan du udruller din agent på Azure Web App og publicerer den i Microsoft Administration, så den bliver tilgængelig for din organisation, så den kan findes og anvendes i Microsoft 365.
  • Last updated on