Megosztás:

Ügynökök tesztelése a Microsoft Agent 365 SDK használatával

Fontos

A Microsoft Agent 365-höz való korai hozzáféréshez a Frontier előzetes verziójának részeként kell lennie. A Frontier közvetlenül összekapcsolja Önt a Microsoft legújabb AI-innovációival. Gyakorlati ismereteket szerezhet az úttörő funkciókról, megoszthatja észrevételeit a termékcsapatokkal, és segíthet a mesterséges intelligencia jövőjének alakításában. A Frontier előzetesekre az ügyfélszerződések meglévő előzetes feltételei vonatkoznak. Mivel ezek a funkciók még fejlesztés alatt állnak, rendelkezésre állásuk és képességeik idővel változhatnak."

Az ügynök helyi tesztelése az Ügynökök játszóterével az üzembe helyezés előtt. Ez az útmutató bemutatja a fejlesztési környezet beállítását, a hitelesítés konfigurálását és az ügynök funkcióinak az Agents Playground tesztelési eszközzel való érvényesítését.

Miután az ügynök helyileg működik, üzembe helyezheti és közzéteheti , hogy tesztelje a Microsoft 365-alkalmazásokban, például a Teamsben.

Előfeltételek

Mielőtt megkezdené az ügynök tesztelését, győződjön meg arról, hogy telepítve vannak a következő előfeltételek:

Gyakori előfeltételek

Nyelvspecifikus előfeltételek

Ügynöktesztelési környezet konfigurálása

Ez a szakasz a környezeti változók beállítását, a fejlesztési környezet hitelesítését és az Ügynök 365-alapú ügynök tesztelésre való előkészítését ismerteti.

Az ügynöktesztelési környezet beállítása szekvenciális munkafolyamatot követ:

  1. A környezet konfigurálása – A környezeti konfigurációs fájl létrehozása vagy frissítése

  2. LLM-konfiguráció – API-kulcsok lekérése és az OpenAI vagy az Azure OpenAI beállításainak konfigurálása

  3. Hitelesítés konfigurálása – Ügynöki hitelesítés beállítása

  4. Környezeti változók referenciája – A szükséges környezeti változók konfigurálása:

    1. Hitelesítési változók
    2. MCP-végpont konfigurációja
    3. Megfigyelhetőségi változók
    4. Ügynökalkalmazás-kiszolgáló konfigurálása

A lépések elvégzése után készen áll arra, hogy megkezdje az ügynök tesztelését az Agents Playground-ban.

1. lépés: A környezet konfigurálása

A konfigurációs fájl beállítása:

cp .env.template .env

Megjegyzés:

A szükséges mezőket tartalmazó konfigurációs sablonok megkereséséhez tekintse meg a Microsoft Agent 365 SDK-mintáit .

2. lépés: LLM-konfiguráció

Konfigurálja az OpenAI vagy az Azure OpenAI beállításait a helyi teszteléshez. Adja hozzá az előfeltételekből beszerzett API-kulcsokat és szolgáltatásvégpontokat a konfigurációs fájlhoz a modellparaméterekkel együtt.

Hozzáadás a .env fájlhoz:

# 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 környezeti változók

Variable Description Kötelező Example
OPENAI_API_KEY API-kulcs az OpenAI szolgáltatáshoz Az OpenAI részére sk-proj-...
AZURE_OPENAI_API_KEY API-kulcs az Azure OpenAI szolgáltatáshoz Az Azure OpenAI számára a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT Azure OpenAI szolgáltatásvégpont URL-címe Azure OpenAI esetén https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Üzembe helyezés neve az Azure OpenAI-ban Azure OpenAI esetén gpt-4
AZURE_OPENAI_API_VERSION API-verzió az Azure OpenAI-hoz Azure OpenAI esetén 2024-02-15-preview

3. lépés: Hitelesítési értékek konfigurálása az ügynökidentitás-hitelesítéshez

Az A365 CLI a365 config display parancs segítségével kérje le az ügynök tervrajz hitelesítő adatait.

a365 config display -g

Ez a parancs megjeleníti az ügynök tervkonfigurációját. Másolja ki a következő értékeket:

Érték Description
agentBlueprintId Az ügynök ügyfélazonosítója
agentBlueprintClientSecret Az ügynök ügyfélkódja
tenantId A Microsoft Entra-bérlő azonosítója

Az ügynök ügynöki hitelesítésének konfigurálásához használja ezeket az értékeket:

Adja hozzá a következő beállításokat a .env fájlhoz, és cserélje le a helyőrző értékeket a tényleges hitelesítő adatokra:

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
Variable Description Kötelező Example
USE_AGENTIC_AUTH Ügynöki hitelesítési mód engedélyezése Igen true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID Az ügynöksablon ügyfélazonosítója innen: a365 config display -g Igen 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Ügynökterv ügyfélkódja a a365 config display -g Igen abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID Microsoft Entra-bérlőazonosító innen: a365 config display -g Igen adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

Megjegyzés:

A .NET esetében is győződjön meg arról, hogy USE_AGENTIC_AUTH=true be van állítva launchSettings.json (lásd 4. lépés: A környezeti változókra vonatkozó hivatkozás)

4. lépés: Környezeti változók referenciája

Végezze el a környezet beállítását a következő szükséges környezeti változók konfigurálásával:

Hitelesítési változók

Konfigurálja az ügynöki hitelesítés megfelelő működéséhez szükséges hitelesítési kezelőbeállításokat.

Hozzáadás a .env fájlhoz:

# 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
Variable Description Kötelező
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Hitelesítési kezelő típusa Igen
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES A Microsoft Graph hitelesítési hatókörei Igen
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Alternatív tervkapcsolat neve Igen
CONNECTIONSMAP_0_SERVICEURL Szolgáltatás URL-címe a kapcsolatleképezéshez Igen
CONNECTIONSMAP_0_CONNECTION Kapcsolatnév a megfeleltetéshez Igen

MCP-végpont konfigurációja

Az MCP (Model Context Protocol) végpontkonfigurációja szükséges annak megadásához, hogy az ügynök melyik 365-ös platformvégponthoz csatlakozzon. Amikor létrehozza az ügynök eszközkiszolgálóit meghatározó eszközjegyzéket, meg kell adnia az MCP platformvégpontot. Ez a végpont határozza meg, hogy az MCP-eszközkiszolgálók mely környezethez (előzetes, tesztelési vagy éles) csatlakoznak a Microsoft 365 integrációs képességeihez.

Hozzáadás a .env fájlhoz:

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
Variable Description Kötelező Alapértelmezett Example
MCP_PLATFORM_ENDPOINT MCP platformvégpont URL-címe (előprojekt, teszt vagy próba) Nem Éles végpont

Fontos: Ha MCP_PLATFORM_ENDPOINT nincs megadva, alapértelmezés szerint a termelési végpontra irányul.

Megfigyelhetőségi változók

Konfigurálja ezeket a szükséges változókat az ügynök naplózásának és elosztott nyomkövetésének engedélyezéséhez. További információ a megfigyelhetőségi funkciókról és az ajánlott eljárásokról

Megjegyzés:

A megfigyelhetőségi konfiguráció minden nyelven azonos.

Variable Description Alapértelmezett Example
ENABLE_A365_OBSERVABILITY Megfigyelhetőség engedélyezése/letiltása false true
ENABLE_A365_OBSERVABILITY_EXPORTER Nyomkövetések exportálása az megfigyelhetőségi szolgáltatásba false true
OBSERVABILITY_SERVICE_NAME A nyomkövetés szolgáltatásneve Ügynök neve my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE Szolgáltatásnévtér agent365-samples my-company-agents

Ügynökalkalmazás-kiszolgáló konfigurálása

Konfigurálja azt a portot, amelyen az ügynökalkalmazás-kiszolgáló fut. Ez nem kötelező, és a Python- és JavaScript-ügynökökre vonatkozik.

Hozzáadás a .env fájlhoz:

# Server Configuration
PORT=3978
Variable Description Kötelező Alapértelmezett Example
PORT Portszám, amelyen az ügynökkiszolgáló fut Nem 3978 3978

Függőségek telepítése és az ügynökalkalmazás-kiszolgáló elindítása

A környezet konfigurálása után telepítenie kell a szükséges függőségeket, és helyileg kell elindítania az ügynökalkalmazás-kiszolgálót a teszteléshez.

Függőségek telepítése

uv pip install -e .

Ez a parancs beolvassa a pyproject.toml fájlban meghatározott csomagfüggőségeket, és telepíti őket a PyPI-ről. Az ügynökalkalmazások létrehozásakor létre kell hoznia egy pyproject.toml fájlt a függőségek meghatározásához. A mintaadattárból származó mintaügynökök már definiálták ezeket a csomagokat. Igény szerint hozzáadhatja vagy frissítheti őket.

Az ügynökalkalmazás-kiszolgáló indítása

python <main.py>

Cserélje le <main.py> az ügynökalkalmazás belépési pontját tartalmazó fő Python-fájl nevét (például start_with_generic_host.py: , app.pyvagy main.py).

Vagy uv:

uv run python <main.py>

Az ügynökkiszolgálónak most már futnia kell, és készen kell állnia arra, hogy kéréseket fogadjon az Agents Playground vagy a Microsoft 365-alkalmazásoktól.

Tesztügynök az Agents Playground-ban

Az Agents Playground egy helyi tesztelési eszköz, amely teljes bérlői beállítás nélkül szimulálja a Microsoft 365-környezetet. Ez a leggyorsabb módszer az ügynök logikájának és eszközhívásainak ellenőrzésére. További információ: Test with Agents Playground.

Nyisson meg egy új terminált (PowerShell Windows rendszeren), és indítsa el az Ügynökök játszóterét:

agentsplayground

Ekkor megnyílik egy webböngésző az Agents Playground felülettel. Az eszköz megjelenít egy csevegőfelületet, ahol üzeneteket küldhet az ügynökének.

Alapszintű teszt

Először ellenőrizze, hogy az ügynök megfelelően van-e konfigurálva. Üzenet küldése az ügynöknek:

What can you do?

Az ügynöknek válaszolnia kell az általa beállított utasításokkal, az ügynök rendszerkérésének és képességeinek megfelelően. Ez megerősíti, hogy:

  • Az ügynök megfelelően fut
  • Az ügynök feldolgozhatja az üzeneteket és válaszolhat
  • Az Ügynökök játszótere és az ügynök közötti kommunikáció működik

Eszközhívások tesztelése

Miután konfigurálta az MCP-eszközkiszolgálókat toolingManifest.json a (telepítési utasításokért lásd az Eszközkészletezést ) az eszközhívásokat a következő példákkal tesztelheti:

Először ellenőrizze, hogy mely eszközök érhetők el:

List all tools I have access to

Ezután tesztelje az adott eszközhívásokat:

Levelezési eszközök

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

Várt válasz: Az ügynök e-mailt küld a Mail MCP-kiszolgálóval, és megerősíti, hogy az üzenet el lett küldve.

Naptáreszközök

List my calendar events for today

Várt válasz: Az ügynök lekéri és megjeleníti az aktuális napra vonatkozó naptáreseményeket.

SharePoint-eszközök

List all SharePoint sites I have access to

Várt válasz: Az ügynök lekérdezi a SharePointot, és visszaadja azoknak a webhelyeknek a listáját, amelyekhez hozzáféréssel rendelkezik.

Az eszközhívásokat a következő helyen tekintheti meg:

  • A csevegőablak – az ügynök válaszainak és az eszközhívásoknak a megtekintése
  • A Napló panel – részletes tevékenységinformációk, beleértve az eszközparamétereket és a válaszokat

Tesztelés értesítési tevékenységekkel

A helyi fejlesztés során tesztelheti az értesítési forgatókönyveket egyéni tevékenységek szimulálásával az Agents Playground-ban. Ez lehetővé teszi az ügynök értesítéskezelésének ellenőrzését, mielőtt éles környezetben üzembe helyeznénk.

Az értesítési tevékenységek tesztelése előtt győződjön meg arról, hogy:

Az értesítésekhez a megfelelő eszközkonfiguráció és az értesítési beállítás is szükséges. Az egyéni tevékenység funkcióval tesztelhet forgatókönyveket, például e-mail-értesítéseket vagy Word-megjegyzéseket.

Egyéni tevékenységek elküldése:

  1. Indítsa el az ügynököt és az Ügynökök játszóterét.
  2. Ügynökök játszóterén navigáljon az aktiválás szimulálása>egyéni tevékenység lehetőségre.
  3. Másolja a conversationId-t a tevékenységből (a beszélgetés azonosítója minden alkalommal megváltozik, amikor újraindul az Ügynökök játszótere [Agents Playground])
  4. Illessze be az egyéni tevékenység JSON-fájlját, és frissítse a personal-chat-id mezőt a másolt beszélgetési azonosítóval. Tekintse meg az e-mail-értesítési példát
  5. Válassza a Küldési tevékenység lehetőséget
  6. A csevegési beszélgetésben és a naplópanelen is tekintse meg az eredményt.

E-mailes értesítés

Ez egy, az ügynöknek küldött e-mailt szimulál. Cserélje le a helyőrző értékeket az ügynök tényleges adataira:

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

Megfigyelhetőségi naplók megtekintése

Ha a helyi fejlesztés során szeretné megtekinteni a megfigyelhetőségi naplókat, az ügynököt megfigyelhetőségi kóddal kell beállítania (a kód példáihoz lásd az Megfigyelhetőséget ), és konfigurálja a környezeti változókat az Megfigyelhetőségi változókban leírtak szerint. A konfigurálás után valós idejű nyomkövetések jelennek meg a konzolon, amelyek a következőt mutatják:

  • Ügynökhívási nyomkövetések
  • Eszközvégrehajtás részletei
  • LLM-inferencia hívások
  • Bemeneti és kimeneti üzenetek
  • Token használat
  • Válaszidők
  • Hibainformációk

Ezek a naplók segítenek a hibák elhárításában, az ügynök viselkedésének megértésében és a teljesítmény optimalizálásában.

Hibaelhárítás

Ez a szakasz megoldást nyújt az ügynök helyi tesztelése során felmerülő gyakori problémákra.

Kapcsolati és környezeti problémák

Ezek a problémák a hálózati kapcsolattal, a portütközésekkel és a környezet beállítási problémáival kapcsolatosak, amelyek megakadályozhatják az ügynök megfelelő kommunikációját.

Ügynökök – Játszótér kapcsolati problémái

Tünet: Az Agentek játszótere nem tud kapcsolódni az ön ügynökéhez

Megoldások:

  • Ellenőrizze, hogy az ügynökkiszolgáló fut-e
  • Ellenőrizze, hogy a portszámok megegyeznek-e az ügynöke és az Agent Playground között.
  • Győződjön meg arról, hogy nincsenek olyan tűzfalszabályok, amelyek blokkolják a helyi kapcsolatokat
  • Próbálja meg újraindítani az ügynököt és az Agents Playgroundot is.

Elavult ügynökök játszótéri verziója

Tünet: Váratlan hibák vagy hiányzó funkciók az Agents Playground-ban

Megoldás: Az Agents Playground eltávolítása és újratelepítése:

winget uninstall agentsplayground
winget install agentsplayground

Portütközések

Hiba: Hiba, amely azt jelzi, hogy a port már használatban van

Solution

  • Állítsd le az ügynök minden más példányát
  • A port módosítása a konfigurációban
  • A portot használó folyamatok leállása:
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

A DeveloperMCPServer nem vehető fel

Hiba: Hiba a DeveloperMCPServer hozzáadásakor a VS Code-ban

Megoldás: Zárja be és nyissa meg újra a Visual Studio Code-ot, majd próbálja meg újból hozzáadni a kiszolgálót.

Hitelesítési problémák

Ezek a problémák akkor fordulnak elő, ha az ügynök nem tud megfelelően hitelesíteni a Microsoft 365-szolgáltatásokkal, vagy ha a hitelesítő adatok lejártak vagy helytelenül lettek konfigurálva.

A hordozó token lejárt

Tünet: Hitelesítési hibák vagy 401 Jogosulatlan válaszok

Megoldás: A hordozó tokenek körülbelül 1 óra elteltével lejárnak. Szerezzen be egy új tokent, és frissítse a konfigurációt.

Ügynöki hitelesítési hibák a Pythonban

Tünet: Hiba az agenti példány token beszerzésekor

Megoldás: Ellenőrizze a ALT_BLUEPRINT_NAME beállítást a .env-ban:

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

Eszköz- és értesítési problémák

Ezek a problémák az eszközhívásokkal, az MCP-kiszolgáló interakcióival és az értesítési kézbesítéssel kapcsolatos problémákat is magukban foglalják.

Nem érkezett e-mail

Hibajelenség: Az ügynök azt jelzi, hogy az e-mail el lett küldve, de Ön nem kapja meg

Megoldások:

  • A Levélszemét/Szemét mappa ellenőrzése
  • Az e-mail kézbesítése néhány perccel késleltethető – akár 5 percet is várhat
  • Ellenőrizze, hogy a címzett e-mail-címe helyes-e
  • Ellenőrizze az ügynöknaplókat, hogy vannak-e hibák az e-mailek küldése során

A Word megjegyzésre adott válaszai nem működnek

Ismert probléma: Az értesítési szolgáltatás jelenleg nem tud közvetlenül válaszolni a Word megjegyzéseire. Ez a funkció fejlesztés alatt áll.

Segítség kérése

Ha a hibaelhárítási szakaszban nem tárgyalt problémákat tapasztal, tekintse át az alábbi erőforrásokat:

Microsoft Agent 365 SDK-adattárak

További támogatás

Következő lépések

Most, hogy sikeresen tesztelte az ügynököt helyileg, készen áll arra, hogy üzembe helyezze az Azure-ban, és tegye közzé a Microsoft 365-ben:

  • Ügynökök üzembe helyezése és közzététele: Megtudhatja, hogyan helyezheti üzembe az ügynökét az Azure Web Appban, és hogyan teheti közzé a Microsoft Felügyeleti központban, és hogyan teheti elérhetővé a szervezet számára a Microsoft 365-ben való felderítéshez és felvételhez.
  • Last updated on