Dela via

Testa agenter med Microsoft Agent 365 SDK

Viktigt

Du måste vara en del av förhandsversionen av Frontier för att få tidig åtkomst till Microsoft Agent 365. Frontier ansluter dig direkt till Microsofts senaste AI-innovationer. Förhandsversioner av Gräns omfattas av de befintliga förhandsversionsvillkoren för dina kundavtal. Eftersom dessa funktioner fortfarande är under utveckling kan deras tillgänglighet och funktioner ändras över tid.

Testa din agent lokalt med agenterna Playground före distributionen. Den här guiden beskriver hur du konfigurerar utvecklingsmiljön, konfigurerar autentisering och validerar agentens funktioner med testverktyget Agents Playground.

När agenten fungerar lokalt kan du distribuera och publicera den för att testa den i Microsoft 365-program som Teams.

Förutsättningar

Innan du börjar, se till att du har följande förutsättningar på plats:

Vanliga förutsättningar

Språkspecifika krav

Konfigurera agenttestningsmiljö

Det här avsnittet beskriver hur du ställer in miljövariabler, autentiserar utvecklingsmiljön och förbereder agenten med Agent 365 för testning.

När du konfigurerar din agenttestningsmiljö följer ett sekventiellt arbetsflöde:

  1. Konfigurera din miljö – Skapa eller uppdatera din miljökonfigurationsfil

  2. LLM-konfiguration – Hämta API-nycklar och konfigurera OpenAI- eller Azure OpenAI-inställningar

  3. Konfigurera autentisering – Konfigurera agentisk autentisering

  4. Referens för miljövariabler – Konfigurera nödvändiga miljövariabler:

    1. Autentiseringsvariabler
    2. MCP-slutpunktskonfiguration
    3. Observerbarhetsvariabler
    4. Konfiguration av agentprogramserver

När du har slutfört de här stegen är du redo att börja testa din agent i Agents Playground.

Steg 5: Konfigurera din -miljö

Konfigurera konfigurationsfilen:

cp .env.template .env

Obs

Se Microsoft Agent 365 SDK-exempel för att hitta konfigurationsmallar som visar obligatoriska fält.

Steg 2: LLM-konfiguration

Konfigurera OpenAI- eller Azure OpenAI-inställningar för lokal testning. Lägg till dina API-nycklar och tjänstslutpunkter som hämtats från förutsättningarna i konfigurationsfilen tillsammans med eventuella modellparametrar.

Ladda upp filen till .env.

# 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 Description Obligatoriskt Exempel
OPENAI_API_KEY API-nyckel för OpenAI-tjänsten För OpenAI sk-proj-...
AZURE_OPENAI_API_KEY API-nyckel för Azure OpenAI-tjänsten För Azure OpenAI: Kör a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT URL för Azure OpenAI-tjänstslutpunkt För Azure OpenAI: Kör https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Distributionsnamn i Azure OpenAI För Azure OpenAI: Kör gpt-4
AZURE_OPENAI_API_VERSION API-version för Azure OpenAI För Azure OpenAI: Kör 2024-02-15-preview

Steg 3: Konfigurera autentiseringsvärden för agentidentitetsautentisering

Använd A365 CLI-kommandot a365 config display för att hämta dina autentiseringsuppgifter för agentritningen.

a365 config display -g

Det här kommandot visar konfigurationen av agentritningen. Ange följande värden.

Värde Description
agentBlueprintId Agentens klient-ID
agentBlueprintClientSecret Agentens klienthemlighet
tenantId Ditt klientorganisations-ID för Microsoft Entra ID.

Använd dessa värden för att konfigurera agentisk autentisering i din agent:

Lägg till följande inställningar i .env filen och ersätt platshållarvärdena med dina faktiska autentiseringsuppgifter:

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 Description Obligatoriskt Exempel
USE_AGENTIC_AUTH Aktivera agentiskt autentiseringsläge Ja true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID Klient-ID för agentritning från a365 config display -g Ja 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Agentskissklienthemlighet från a365 config display -g Ja abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID Microsoft Entra-klient-ID från a365 config display -g Ja adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

Obs

För .NET kontrollerar du också att USE_AGENTIC_AUTH=true anges i launchSettings.json (se Referens för steg 4: Miljövariabler)

Steg 2: Miljövariabler

Slutför miljökonfigurationen genom att konfigurera följande obligatoriska miljövariabler:

Autentiseringsvariabler

Konfigurera autentiseringshanterarinställningarna som krävs för att agentisk autentisering ska fungera korrekt.

Ladda upp filen till .env.

# 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 Description Obligatoriskt
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Typ av autentiseringshanterare Ja
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Autentiseringsomfång för Microsoft Graph Ja
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Alternativt namn på skissanslutning Ja
CONNECTIONSMAP_0_SERVICEURL Tjänst-URL-mönster för anslutningsmappning Ja
CONNECTIONSMAP_0_CONNECTION Anslutningsnamn för mappning Ja

Slutpunktskonfiguration

MCP-slutpunktskonfigurationen (Model Context Protocol) krävs för att ange vilken agent 365-plattformsslutpunkt som agenten ska ansluta till. När du genererar verktygsmanifestet som definierar verktygsservrarna för din agent måste du ange MCP-plattformens slutpunkt. Den här slutpunkten avgör vilken miljö (preprod, test eller produktion) MCP-verktygsservrarna ansluter till för Microsoft 365-integreringsfunktioner.

Ladda upp filen till .env.

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
Variabel Description Obligatoriskt Standardvärde Exempel
MCP_PLATFORM_ENDPOINT URL för MCP-plattformsslutpunkt (preprod, test eller prod) Nej. Produktionens slutdatum

Viktigt: Om MCP_PLATFORM_ENDPOINT inte har angetts används produktionsslutpunkten som standard.

Observerbarhetsvariabler

Konfigurera de här nödvändiga variablerna för att aktivera loggning och distribuerad spårning för din agent. Läs mer om observerbarhetsfunktioner och metodtips

Obs

Observerbarhetskonfigurationen är densamma på alla språk.

Variabel Description Standardvärde Exempel
ENABLE_A365_OBSERVABILITY Aktivera/inaktivera observerbarhet false true
ENABLE_A365_OBSERVABILITY_EXPORTER Exportera spårningar till observerbarhetstjänsten false true
OBSERVABILITY_SERVICE_NAME Tjänstnamn för spårning Agentens namn my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE Service Bus namnrymd agent365-samples my-company-agents

Konfiguration av agentprogramserver

Konfigurera porten där agentprogramservern körs. Detta är valfritt och gäller för Python- och JavaScript-agenter.

Ladda upp filen till .env.

# Server Configuration
PORT=3978
Variabel Description Obligatoriskt Standardvärde Exempel
PORT Portnummer där agentservern körs Nej. 3978 3978

Installera beroenden och starta agentprogramservern

När din miljö har konfigurerats måste du installera nödvändiga beroenden och starta agentprogramservern lokalt för testning.

Installera beroenden:

uv pip install -e .

Det här kommandot läser de paketberoenden som definierats i pyproject.toml och installerar dem från PyPI. När du skapar ett agentprogram från grunden måste du skapa en pyproject.toml fil för att definiera dina beroenden. Exempelagenter från exempellagringsplatsen har redan definierat dessa paket. Du kan uppdatera, lägga till eller ta bort rader efter behov.

Starta agentprogramservern

python <main.py>

Ersätt <main.py> med namnet på din huvudsakliga Python-fil som innehåller startpunkten för agentprogrammet (till exempel start_with_generic_host.py, app.pyeller main.py).

Eller med uv:

uv run python <main.py>

Agentservern bör nu vara igång och redo att ta emot begäranden från Agents Playground eller Microsoft 365-program.

Testagent i Agents Playground

Agents Playground är ett lokalt testverktyg som simulerar Microsoft 365-miljön utan att kräva en fullständig klientkonfiguration. Det är det snabbaste sättet att verifiera agentens logik och verktygsanrop. Mer information finns i Testa med agenter Playground.

Öppna en ny terminal (PowerShell i Windows) och starta Agents Playground:

agentsplayground

Då öppnas en webbläsare med agenternas Playground-gränssnitt. Verktyget visar ett chattgränssnitt där du kan skicka meddelanden till din agent.

Grundläggande tester

Börja med att kontrollera att agenten är korrekt konfigurerad. Skicka ett meddelande till agenten:

What can you do?

Agenten bör svara med de instruktioner som den har konfigurerats med, baserat på agentens systemuppvisning och funktioner. Detta bekräftar att:

  • Din agent körs korrekt
  • Agenten kan bearbeta meddelanden och svara
  • Kommunikationen mellan Agents Playground och din agent fungerar

Testverktygsanrop

När du har konfigurerat MCP-verktygsservrarna i toolingManifest.json (se Verktyg för installationsinstruktioner) testar du verktygsanrop med exempel som dessa:

Kontrollera först vilka verktyg som är tillgängliga:

List all tools I have access to

Testa sedan specifika verktygsanrop:

E-postverktyg

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

Förväntat svar: Agenten skickar ett e-postmeddelande med hjälp av MAIL MCP-servern och bekräftar att meddelandet skickades.

Kalenderverktyg

List my calendar events for today

Förväntat svar: Agenten hämtar och visar dina kalenderhändelser för den aktuella dagen.

SharePoint-verktyg

List all SharePoint sites I have access to

Förväntat svar: Agenten frågar SharePoint och returnerar en lista över webbplatser som du har åtkomst till.

Du kan visa verktygsanropen i:

  • Chattfönstret – se agentens svar och eventuella verktygsanrop
  • Loggpanelen – se detaljerad aktivitetsinformation, inklusive verktygsparametrar och svar

Testa med meddelandeaktiviteter

Under den lokala utvecklingen kan du testa meddelandescenarier genom att simulera anpassade aktiviteter i Agents Playground. På så sätt kan du verifiera agentens meddelandehantering innan du distribuerar den till produktion.

Kontrollera att du har följande innan du testar meddelandeaktiviteter:

Meddelanden kräver att både rätt verktygskonfiguration och meddelandekonfiguration fungerar korrekt. Du kan testa scenarier som e-postaviseringar eller Word-kommentarer med hjälp av funktionen anpassad aktivitet.

Så här skickar du anpassade aktiviteter:

  1. Starta din agent och agenter Playground
  2. I Agents Playground navigerar du till Mock an Activity Custom activity (Simulera en aktivitetsanpassad>aktivitet)
  3. conversationId Kopiera från aktiviteten (konversations-ID:t ändras varje gång Agents Playground startas om)
  4. Klistra in din anpassade aktivitets-JSON och uppdatera fältet personal-chat-id med det konversations-ID som du kopierade. Se exemplet med e-postaviseringar
  5. Välj Lägg till aktivitet.
  6. Visa resultatet i både chattkonversationen och loggpanelen

E-postavisering

Detta simulerar ett e-postmeddelande som skickas till agenten. Ersätt platshållarvärden med din faktiska agentinformation:

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

Visa observerbarhetsloggar

Om du vill visa observerbarhetsloggar under lokal utveckling kan du instrumentera din agent med observerbarhetskod (se Observerbarhet för kodexempel) och konfigurera miljövariablerna enligt beskrivningen i Observabilitetsvariabler. När de har konfigurerats visas realtidsspårningar i konsolen som visar:

  • Agentanropsspårningar
  • Information om körning
  • LLM-slutsatsdragningsanrop
  • Indata- och utdatameddelanden
  • Tokenanvändning
  • Svarstid
  • Felinformationen.

De här loggarna hjälper dig att felsöka problem, förstå agentbeteende och optimera prestanda.

Felsökning

Det här avsnittet innehåller lösningar på vanliga problem som kan uppstå när du testar din agent lokalt.

Problem med anslutning och miljö

De här problemen gäller nätverksanslutningar, portkonflikter och miljökonfigurationsproblem som kan hindra agenten från att kommunicera korrekt.

Anslutningsproblem för Agents Playground

Symptom: Agenter Playground kan inte ansluta till din agent

### Lösning:

  • Kontrollera att agentservern körs
  • Kontrollera att portnumren matchar mellan din agent och Agents Playground
  • Kontrollera att det inte finns några brandväggsregler som blockerar åtkomsten till blobcontainern.
  • Prova att starta om både agenten och Agents Playground

Inaktuella agenter Playground-version

Symptom: Oväntade fel eller saknade funktioner i Agents Playground

Lösning: Avinstallera och installera om Agenter Playground:

winget uninstall agentsplayground
winget install agentsplayground

Portkonflikter

Symptom: Fel som anger att porten redan används

### Lösning:

  • Stoppa andra instanser av din agent
  • Ändra porten i konfigurationen
  • Avsluta alla processer med hjälp av porten:
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

Det går inte att lägga till DeveloperMCPServer

Symptom: Fel vid försök att lägga till DeveloperMCPServer i VS Code

Lösning: Stäng och öppna Visual Studio Code igen och försök sedan lägga till servern igen.

Autentiseringsproblem

Dessa problem uppstår när din agent inte kan autentiseras korrekt med Microsoft 365-tjänster eller när autentiseringsuppgifterna har upphört att gälla eller är felkonfigurerade.

Ägartoken har upphört att gälla

Symptom: Autentiseringsfel eller 401 Otillåtna svar

Lösning: Ägartoken upphör att gälla efter cirka 1 timme. Hämta en ny token och uppdatera konfigurationen.

Agentiska autentiseringsfel i Python

Symptom: Fel vid anskaffning av agentisk instanstoken

Lösning: Verifiera inställningen 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

Kända problem och aviseringar

Dessa problem omfattar problem med verktygsanrop, MCP-serverinteraktioner och meddelandeleverans.

E-postmeddelanden har inte tagits emot

Symptom: Agenten anger att e-post har skickats, men du får den inte

### Lösning:

  • Kontrollera din skräppostmapp.
  • E-postleverans kan fördröjas med några minuter – vänta upp till 5 minuter
  • Kontrollera att mottagarens e-postadress är korrekt
  • Kontrollera agentloggarna efter eventuella fel vid e-postöverföring

Word-kommentarssvar fungerar inte

Känt problem: Meddelandetjänsten kan för närvarande inte svara direkt på Word-kommentarer. En del av den här funktionaliteten utvecklas i våg 1.

Få hjälp

Om du stöter på problem som inte beskrivs i det här felsökningsavsnittet kan du utforska dessa resurser:

Microsoft Agent 365 SDK-lagringsplatser

Mer support

Gå vidare

Nu när du har testat din agent lokalt är du redo att distribuera den till Azure och publicera den till Microsoft 365:

  • Distribuera och publicera agenter: Lär dig hur du distribuerar din agent till Azure Web App och publicerar den till Microsoft Admin Center, vilket gör den tillgänglig för din organisation att identifiera och anställa i Microsoft 365.
  • Last updated on