Testaa agentteja Microsoft Agent 365 SDK:n avulla

Ennen käyttöönottoa testaa agenttisi paikallisesti käyttämällä agenttien testausalustaa. Tämä opas kattaa kehitysympäristön määrittämisen, tunnistautumisen konfiguroinnin ja agentin toiminnallisuuden validoinnin agenttien testausalustan avulla.

Kun agenttisi toimii paikallisesti, siirry noudattamaan Agent 365 -kehityselinkaarta testataksesi agenttia Microsoft 365 -sovelluksissa, kuten Teamsissa, Wordissa ja Outlookissa.

Edellytykset

Ennen kuin aloitat agenttisi testaamisen, varmista, että olet asentanut seuraavat edellytykset:

Yleiset ennakkovaatimukset

Kielikohtaiset ennakkovaatimukset

  • Python 3.11 tai uudempi: Lataa python.orgista tai Microsoft Storesta
  • UV-pakettienhallinta: Asenna UV käyttämällä pip install uv
  • Tarkista asennus: python --version

Määritä agentin testausympäristö

Tässä osiossa kuvataan, miten asetetaan ympäristömuuttujat, autentikoidaan kehitysympäristö ja valmistellaan Agent 365 -pohjainen agentti testattavaksi.

Konfiguroi agentin testausympäristö noudattamalla tätä peräkkäistä työnkulkua:

  1. Määritä ympäristösi – luo tai päivitä ympäristön konfiguraatiotiedosto.

  2. LLM-konfiguraatio – Hanki API-avaimet ja määritä OpenAI- tai Azure OpenAI -asetukset.

  3. Määritä todennus - Aseta agenttinen tunnistautuminen.

  4. Ympäristömuuttujien viite - Määritä vaaditut ympäristömuuttujat:

    1. Todennusmuuttujat
    2. MCP-päätepisteen määritys
    3. Observability-muuttujat
    4. Agentin sovelluspalvelimen määritys

Kun olet suorittanut nämä vaiheet, olet valmis aloittamaan agenttisi testaamisen Agenttien testausalustassa.

Vaihe 1: ympäristön määrittäminen

Määritä määritystiedosto:

cp .env.template .env

Muistiinpano

Katso Microsoft Agent 365 SDK -esimerkeistä määritysmallit, joissa on vaaditut kentät.

Vaihe 2: LLM-määritykset

Määritä OpenAI- tai Azure OpenAI -asetukset paikallista testausta varten. Lisää API-avaimet ja palvelupäätepisteet ennakkovaatimuksista konfiguraatiotiedostoon sekä mahdolliset malliparametrit.

Lisää .env-tiedostoosi:

# 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-ympäristömuuttujat

Muuttuja Description Pakollinen Esimerkki
OPENAI_API_KEY API-avain OpenAI-palvelulle OpenAI:lle sk-proj-...
AZURE_OPENAI_API_KEY API-avain Azure OpenAI -palvelulle Azure OpenAI -palvelulle a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT Azure OpenAI -palvelun päätepisteen URL-osoite Azure OpenAI -palvelulle https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Käyttöönoton nimi Azure OpenAI:ssa Azure OpenAI -palvelulle gpt-4
AZURE_OPENAI_API_VERSION API-versio Azure OpenAI:lle Azure OpenAI -palvelulle 2024-02-15-preview

Vaihe 3: Agentin todennuksen määrittäminen

Valitse yksi seuraavista todennustavoista agentillesi:

  • Agenttinen todennus – Käytä tuotantoympäristössä, kun agenttinen käyttäjäidentiteetti on käytettävissä.
  • (On‑Behalf‑Of) OBO-todennus – Käytä tuotantotilanteissa, kun tarvitset edustajakäyttäjän oikeuksia ilman agentti-identiteettiä.
  • Bearer-token-tunnistautuminen – Käytetään vain varhaisessa kehitys- ja testaustilanteissa ennen tuotannon tunnistautumisen määritystä.

Agenttinen tunnistautuminen

Avaa a365.generated.config.json työskentelyhakemistossasi ja hae agentin blueprint-tunnistetiedot. Kopioi seuraavat arvot:

Arvo Description
agentBlueprintId Agenttisi asiakastunnus
agentBlueprintClientSecret Agenttisi asiakassalasana
tenantId Microsoft Entra -vuokraajan tunnus

Käytä näitä arvoja agenttisen tunnistautumisen määrittämiseen agentissasi:

Lisää tiedostoon .env seuraavat asetukset, korvaten paikkamerkkiarvot omilla tunnistetiedoillasi:

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
Muuttuja Description Pakollinen Esimerkki
USE_AGENTIC_AUTH Ota käyttöön agentin todennustila Kyllä true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID Agentin blueprint-asiakastunnus kohteesta a365.generated.config.json Kyllä 11112222-bbbb-3333-cccc-4444dddd5555
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Agentin blueprint-asiakassalasana kohteesta a365.generated.config.json Kyllä abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID Microsoft Entra -vuokraajan tunnus kohteesta a365.generated.config.json Kyllä 22223333-cccc-4444-dddd-5555eeee6666

OBO-todennus

Käyttämällä On-Behalf-Of (OBO) -todennusta agenttisi voi käyttää MCP-palvelimen työkaluja delegoitujen käyttöoikeuksien avulla ilman omaa käyttäjäidentiteettiä. Tässä prosessissa agentti saa käyttäjän delegoidun tunnisteen ja vaihtaa sen toiseen tunnisteeseen suorittaakseen toimintoja käyttäjän puolesta.

OBO-todennus soveltuu tuotantoympäristöihin, joissa:

  • Agentilla ei ole omaa käyttäjäidentiteettiä.
  • Tarvitset pääsyn resursseihin, jotka vaativat käyttäjäkohtaisia oikeuksia.
  • Haluat agentin toimivan todennetun käyttäjän puolesta.

Katso Todennustyönkulut saadaksesi lisätietoja OBO-työnkulun toiminnasta. Täydellisen toteutusesimerkin löydät Microsoft 365 -agenttien SDK:n OBO-valtuutusesimerkistä.

Haltijatunnuksen todentaminen

Varhaisissa kehitys- ja testaustilanteissa, joissa tuotannon tunnistautumista ei ole määritetty, käytä haltijatunnistautumista agentin testaamiseen. Tämä menetelmä käyttää interaktiivista selaimen kautta tapahtuvaa tunnistautumista delegoidun käyttöoikeustunnuksen saamiseksi. Tämän tunnuksen avulla agenttisi voi kutsua MCP Server -työkaluja käyttäjäoikeuksiasi käyttäen. Tämä lähestymistapa simuloi, miten agentin käyttäjä pääsee käsiksi tuotantoresursseihin ilman varsinaista agenttiesiintymää.

Käytä ensin a365 develop add-permissions lisätäksesi tarvittavat MCP-palvelimen käyttöoikeudet sovellukseesi:

a365 develop add-permissions

Sitten käytä a365 develop get-token haltijatunnusten hakemiseen ja määrittämiseen:

a365 develop get-token

Komento get-token suorittaa automaattisesti seuraavat toiminnot:

  • Lukee ToolingManifest.json löytääkseen kaikki konfiguroidut MCP-palvelimet.
  • Hankkii yhden tunnuksen per käyttäjäryhmä – palvelinkohtaiset MCP-palvelimet saavat tunnuksen, joka on kohdistettu niiden omaan sovellustunnukseen; jaetut ATG-palvelimet saavat tunnuksen, joka on kohdistettu jaettuun Agent Tools Gateway -sovellustunnukseen (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1).
  • Tallentaa tunnukset projektin konfiguraatiotiedostoihin:
    • Palvelinkohtaiset tunnukset: BEARER_TOKEN_<SERVER_NAME> (esim. BEARER_TOKEN_MCP_MAILTOOLS)
    • Jaettu ATG-tunnus: BEARER_TOKEN

Lisää paikkamerkinnät projektin määritystiedostoon ennen kuin suoritat get-token.

  • .NET: Lisää "BEARER_TOKEN": "" ja/tai "BEARER_TOKEN_<SERVER_NAME>": ""environmentVariables-osioon kussakin profiilissa tiedostossa Properties/launchSettings.json. Komento päivittää vain profiileja, joilla nämä avaimet on jo määritelty.
  • Python/Node.js: Luo .env-tiedosto, joka sisältää BEARER_TOKEN= ja/tai BEARER_TOKEN_<SERVER_NAME>= ennen suoritusta. Jos tiedosto puuttuu, komento ohittaa tallennuksen ja näyttää ohjeistuksen.

Muistiinpano

Jos suoritat a365 develop get-token --app-id <id> ilman a365.config.json-tiedostoa, tunnuksia ei tallenneta automaattisesti. Kopioi ja liitä ne manuaalisesti tiedostoon Properties/launchSettings.json (.NET) tai tiedostoon .env (Python/Node.js).

Haltijatunnukset vanhenevat noin tunnin kuluttua. Käytä a365 develop get-token vanhentuneiden tunnusten päivittämiseen.

Vaihe 4: Ympäristömuuttujaviite

Viimeistele ympäristön määritys konfiguroimalla seuraavat vaaditut ympäristömuuttujat:

Todennusmuuttujat

Määritä todennuskäsittelijän asetukset, jotta agenttipohjainen todennus toimisi oikein.

Lisää .env-tiedostoosi:

# 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
Muuttuja Description Pakollinen
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Todennuskäsittelijätyyppi Kyllä
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Microsoft Graphin käyttöoikeudet Kyllä
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Vaihtoehtoisen blueprint-yhteyden nimi Kyllä
CONNECTIONSMAP_0_SERVICEURL Palvelun URL-malli yhdistämismääritykseen Kyllä
CONNECTIONSMAP_0_CONNECTION Yhteyden nimi yhdistämismääritykseen Kyllä

Haltijatunnusmuuttujat (vain paikalliseen kehitykseen)

Muuttuja Description Pakollinen
BEARER_TOKEN Jaettu haltijatunnus jaetuille ATG MCP -palvelimille. Komento a365 develop get-token kirjoittaa tämän tunnuksen automaattisesti. Jaetun ATG:n paikallinen kehitys
BEARER_TOKEN_<SERVER_NAME> Palvelinkohtainen haltijatunnus. SDK muodostaa nimen muuttamalla mcpServerNameToolingManifest.json:sta isoiksi kirjaimiksi (esimerkiksi, mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS). Komento a365 develop get-token kirjoittaa tämän tunnuksen automaattisesti. Palvelinkohtainen paikallinen kehitysympäristö
SKIP_TOOLING_ON_ERRORS Aseta arvoksi true, jotta käytetään pelkkää LLM:ää, jos MCP-työkalut eivät lataudu. Tämä on voimassa vain, kun ASPNETCORE_ENVIRONMENT tai ENVIRONMENT on Development. Ei

Tärkeää

Haltijatunnukset on tarkoitettu vain paikallista kehitystä varten. Älä koskaan määritä BEARER_TOKEN tai BEARER_TOKEN_<SERVER_NAME> tuotantoympäristössä.

MCP-päätepisteen määritys

Määritä Agent 365 -alustan päätepiste, johon agenttisi muodostaa yhteyden. Kun luot työkalumanifestin, jossa määritellään työkalupalvelimet agentillesi, määritä MCP-alustan päätepiste. Tämä päätepiste määrittää, mihin ympäristöön (esituotanto, testi tai tuotanto) MCP-työkalupalvelimet yhdistävät Microsoft 365 -integraatio-ominaisuuksia varten.

Lisää .env-tiedostoosi:

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
Muuttuja Description Pakollinen Oletus Esimerkki
MCP_PLATFORM_ENDPOINT MCP-alustan päätepisteen URL (preprod, test tai prod) Ei Tuotantopäätepiste

Tärkeää: Mikäli et määritä MCP_PLATFORM_ENDPOINT-koodia, sovellus käyttää tuotantopäätepistettä.

Muistiinpano

Jos käytät CLI:n mock tooling -palvelinta, aseta päätepiste kohteeseen http://localhost:<port> käyttämällä käyttämääsi porttinumeroa. Oletusportti on 5309.

Observability-muuttujat

Määritä nämä tarvittavat muuttujat ottaaksesi käyttöön lokituksen ja hajautetun jäljityksen agentillesi. Täydellinen luettelo ympäristömuuttujista, määritysvaihtoehdoista ja koodiesimerkeistä on saatavilla kohdassa Agentin havaittavuus.

Muistiinpano

Havaittavuuden asetukset ovat samat kaikissa kielissä. Lisätietoja on kohdassa määritys.

Muuttuja Description Oletus Esimerkki
ENABLE_A365_OBSERVABILITY_EXPORTER Vie jäljet havaittavuuspalveluun. Kun false, vienti ulottuu konsolille. false true
A365_OBSERVABILITY_LOG_LEVEL Havaittavuus-SDK:n sisäinen lokitustaso. Hyödyllinen testauksen aikana ilmenevien vientiongelmien vianetsinnässä. none info, warn, error, debug

Agentin sovelluspalvelimen määritys

Määritä portti, jossa agenttisovelluspalvelin toimii. Tämä asetus on valinnainen ja koskee Python- ja JavaScript-agentteja.

Lisää .env-tiedostoosi:

# Server Configuration
PORT=3978
Muuttuja Description Pakollinen Oletus Esimerkki
PORT Porttinumero, jossa agenttipalvelin toimii Ei 3978 3978

Asenna tarvittavat riippuvuudet ja käynnistä agenttipalvelin

Kun ympäristösi on määritetty, asenna tarvittavat riippuvuudet ja käynnistä agenttipalvelin paikallisesti testausta varten.

Asenna riippuvuudet

uv pip install -e .

Tämä komento lukee pyproject.toml-tiedostossa määritetyt pakettiriippuvuudet ja asentaa ne PyPI:n kautta. Kun luot agenttisovellusta alusta, luo pyproject.toml-tiedosto riippuvuuksien määrittämiseen. Esimerkkisäilön esimerkkiagentit ovat jo määritelleet nämä paketit. Voit lisätä tai päivittää niitä tarvittaessa.

Käynnistä agenttisovelluspalvelin

python <main.py>

Korvaa <main.py> pääasiallisen Python-tiedostosi nimellä, joka sisältää agenttisovelluksesi aloituspisteen (esimerkiksi start_with_generic_host.py, app.py tai main.py).

Tai käytä uv:tä:

uv run python <main.py>

Agenttipalvelimesi on nyt käynnissä ja valmis vastaanottamaan pyyntöjä Agenttien testausalustasta tai Microsoft 365 -sovelluksilta.

Testaa agenttia Agenttien testausalustassa

Agenttien testausalusta on paikallinen testausväline, joka simuloi Microsoft 365 -ympäristöä ilman, että vaaditaan täyden vuokraajaympäristön käyttöönottoa. Se on nopein tapa validoida agenttisi logiikka ja työkalukutsut. Lisätietoja: katso Testaa Agenttien testausalustan avulla.

Määritä Agenttien testausalusta agenttista tunnistautumista varten

Muistiinpano

Tämä konfiguraatio on tarpeen vain, kun käytetään agenttista tunnistautumista. Jos käytät haltijatunnus-tunnistautumista, voit ohittaa tämän osion ja siirtyä suoraan perustestiin.

Kun käytät agenttitunnistautumista, määritä Agenttien testausalustan YAML-tiedosto agenttisi tiedoilla:

  1. Määritä konfiguraatiotiedosto: Luo tai päivitä .m365agentsplayground.yml tiedosto siihen kansioon, jossa suoritat Agenttien testausalustan. Katso yksityiskohtaiset asennusohjeet kohdasta Teams-kontekstin mukauttaminen.

  2. Päivitä botin määritykset: Lisää seuraavat botin tiedot .m365agentsplayground.yml-tiedostoon korvaamalla paikkamerkkiarvot agenttisi tunnistetiedoilla:

    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>
    Ominaisuus Kuvaus Pakollinen
    id Agenttikäyttäjän sähköpostiosoite muodossa agentusername@tenant.onmicrosoft.com Kyllä
    name Näyttönimi agentin käyttäjälle Kyllä
    role Täytyy asettaa agenticUser agenttisen tunnistautumisen yhteydessä Kyllä
    agenticUserId Agenttikäyttäjän objektitunnus. Löydät tämän arvon Microsoft Entra -hallintakeskuksesta agenttikäyttäjän profiilisivulta. Kyllä
    agenticAppId Agenttikäyttäjän agenttitunnus. Löydät tämän arvon Microsoft Entra -hallintakeskuksesta agenttikäyttäjän profiilisivulta. Kyllä

Avaa uusi terminaali (PowerShell Windowsissa) ja käynnistä Agenttien testausalusta:

agentsplayground

Tämä komento avaa verkkoselaimen, jossa on Agenttien testausalusta -käyttöliittymä. Työkalu näyttää keskustelukäyttöliittymän, jossa voit lähettää viestejä agentillesi.

Perustesti

Aloita varmistamalla, että agenttisi on oikein määritetty. Lähetä viesti agentille:

What can you do?

Agentti vastaa sille määritetyillä ohjeilla, perustuen agentin järjestelmäkehoteeseen ja kykyihin. Tämä vastaus vahvistaa, että:

  • Agenttisi toimii oikein.
  • Agentti voi käsitellä viestejä ja vastata.
  • Agenttien testausalustan ja agenttisi välinen viestintä toimii.

Työkalukutsujen testaaminen

Kun olet konfiguroinut MCP-työkalupalvelimet toolingManifest.json (katso Työkalut asennusohjeet), testaa työkalukutsuja seuraavien esimerkkien avulla:

Tarkista ensin, mitä työkaluja on saatavilla:

List all tools I have access to

Sen jälkeen testaa työkalujen yksittäisiä kutsuja:

Sähköpostityökalut

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

Odotettu vastaus: Agentti lähettää sähköpostin Mail MCP -palvelimen kautta ja vahvistaa, että viesti on lähetetty.

Kalenterityökalut

List my calendar events for today

Odotettu vastaus: Agentti hakee ja näyttää kalenterisi tapahtumat tältä päivältä.

SharePoint-työkalut

List all SharePoint sites I have access to

Odotettu vastaus: Agentti hakee tietoja SharePointista ja palauttaa listan sivustoista, joihin sinulla on pääsy.

Voit tarkastella työkalukutsuja seuraavissa paikoissa:

  • Keskusteluikkuna – katso agentin vastaus ja työkalukutsut.
  • Lokipaneeli – katso yksityiskohtaiset aktiviteettitiedot, mukaan lukien työkalun parametrit ja vastaukset.

Testaa ilmoitustoiminnoilla

Paikallisen kehityksen aikana voit testata ilmoitusskenaarioita hyödyntämällä Agenttien testausalusta -työkalun valmiita ilmoituslaukaisimia.

Kuvakaappaus, jossa näkyy Agenttien testausalusta -työkalun käyttöliittymä Mock an Activity -valikko laajennettuna ja Käynnistä ilmoitustoiminto -vaihtoehdot, mukaan lukien Lähetä sähköpostiviesti ja Mainitse Wordissa.

Ennen kuin testaat ilmoitustoimintoja, varmista:

Sähköposti-ilmoitusten testaaminen

Sähköposti-ilmoitusten käsittelyn testaaminen:

  1. Käynnistä agenttisi ja Agenttien testausalusta.
  2. Siirry Agenttien testausalustassa kohtaan Mock an Activity>Käynnistä ilmoitustoiminto.
  3. Valitse Lähetä sähköpostiviesti.
  4. Päivitä tiedot-valintaikkunassa mallisähköpostin tiedot, kuten lähettäjän nimi ja sähköpostin sisältö, tarpeen mukaan.
  5. Valitse Lähetä toiminto.
  6. Näytä tulos sekä chat-keskustelussa että lokipaneelissa.

Agentti saa simuloidun sähköposti-ilmoituksen ja käsittelee sen ilmoitusten käsittelylogiikan mukaisesti. Katso sähköposti-ilmoituksen hyötykuorman rakenne kohdasta Sähköposti-ilmoituksen hyötykuorma.

Word-mainintailmoitusten testaus

Word-dokumentin mainintailmoitusten testaus:

  1. Käynnistä agenttisi ja Agenttien testausalusta.
  2. Siirry Agenttien testausalustassa kohtaan Mock an Activity>Käynnistä ilmoitustoiminto.
  3. Valitse Maininta Wordissa.
  4. Tiedot-valintaikkunassa päivitä mock-kommentin tiedot, kuten dokumentin tunnus ja kommenttiteksti, tarpeen mukaan.
  5. Valitse Lähetä toiminto.
  6. Näytä tulos sekä chat-keskustelussa että lokipaneelissa.

Agentti vastaanottaa simuloidun Word-maininta-ilmoituksen ja reagoi määrittelemäsi ilmoituksen käsittelylogiikan mukaisesti. Lisätietoja Word-kommentti-ilmoituksen hyötykuormarakenteesta löydät kohdasta Asiakirjakommentti-ilmoituksen hyötykuorma.

Testaa agentin asennus- ja poistotapahtumat

Kun Agenttien testausalusta muodostaa yhteyden agenttiisi, se lähettää automaattisesti InstallationUpdate-aktiviteetin, jossa on toiminto add. Jos otat käyttöön asennuskäsittelijän, agenttisi tervetuloviesti näkyy keskustelussa heti yhteyden muodostuttua.

Asennustapahtumien käsittelyn tarkistaminen:

  1. Käynnistä agenttipalvelin.
  2. Avaa Agenttien testausalusta. Agenttien testausalusta yhdistyy agenttiisi ja käynnistää automaattisesti asennustapahtuman.
  3. Varmista, että tervetuloviesti näkyy chat-keskustelussa.

Kuvakaappaus, jossa Agenttien testausalusta -käyttöliittymässä näkyy agentin tervetuloviesti: 'Kiitos, että palkkasit minut! Odotan innolla, että voin auttaa sinua ammatillisella matkallasi!' Viesti näkyy keskustelussa ja lokipaneelissa sen jälkeen, kun asennustapahtuma käynnistyy automaattisesti.

Katso lisätietoja käsittelijän toteutuksesta kohdasta Agentin asennus- ja poistotapahtumien käsittely.

Tarkastele havaittavuuslokit

Jos haluat tarkastella havaittavuuslokeja paikallisen kehityksen aikana, instrumentoi agenttisi havaittavuuskoodilla (katso Havaittavuus koodiesimerkeistä) ja määritä ympäristömuuttujat kuten on kuvattu kohdassa Havaittavuusmuuttujat. Yksityiskohtaiset ohjeet vaiheittaiseen validointiin ja odotettuun lokitulosteeseen löydät kohdasta Validoi paikallisesti. Kun konfiguraatio on valmis, konsolissa näkyy reaaliaikaiset jäljet, jotka osoittavat:

  • Agentin kutsujäljet
  • Työkalusuorituksen tiedot
  • LLM-inferenssikutsut
  • Syöte- ja tulosviestit
  • Tunnuksen käyttö
  • Vasteajat
  • Virheen tiedot

Nämä lokit auttavat sinua korjaamaan ongelmia, ymmärtämään agentin käyttäytymistä ja optimoimaan suorituskyvyn. Ennen julkaisua käytä Store-julkaisun validointi -toimintoa varmistaaksesi, että kaikki vaaditut ominaisuudet ovat olemassa.

Seuraavat vaiheet

Kun olet testannut agenttisi paikallisesti, ota se käyttöön Azureen ja julkaise Microsoft 365:ssä.

Jos haluat testata agenttiasi Microsoft 365 -sovelluksissa, kuten Teamsissa, Wordissa ja Outlookissa, katso Agent 365:n kehityksen elinkaari.

Vianmääritys

Tämä osio tarjoaa ratkaisuja yleisiin ongelmiin, joita saatat kohdata testatessasi agenttiasi paikallisesti.

Vinkki

Agent 365:n vianmääritysopas sisältää yleisluontoisia vianmääritykseen liittyviä suosituksia, parhaita käytäntöjä sekä linkkejä vianmääritykseen liittyvään sisältöön Agent 365:n kehityksen elinkaaren kaikissa vaiheissa.

Yhteys- ja ympäristöongelmat

Nämä ongelmat liittyvät verkkoyhteyksiin, porttikonflikteihin ja ympäristön konfigurointiongelmiin, jotka estävät agenttisi kommunikoimasta asianmukaisesti.

Agenttien testausalustan yhteysongelmat

Oire: Agenttien testausalusta ei saa yhteyttä agenttiin.

Ratkaisut:

  • Varmista, että agenttipalvelimesi on käynnissä.
  • Tarkista, että porttinumerot vastaavat toisiaan agentin ja Agenttien testausalustan välillä.
  • Varmista, ettei palomuurisääntöjä ole estämässä paikallisia yhteyksiä.
  • Yritä käynnistää agentti ja Agenttien testausalusta uudelleen.

Agenttien testausalustan vanhentunut versio

Oire: Odottamattomia virheitä tai ominaisuuksien puuttumista Agenttien testausalustassa.

Ratkaisu: Poista ja asenna Agenttien testausalusta uudelleen.

winget uninstall agentsplayground
winget install agentsplayground

Portin ristiriidat

Oire: Virheilmoitus, että portti on jo käytössä.

Ratkaisu:

  • Pysäytä kaikki muut agenttisi instanssit.
  • Vaihda portti konfiguraatiossasi.
  • Tapa kaikki porttia käyttävät prosessit.
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

DeveloperMCPServerin lisääminen ei onnistu

Oire: Virhe ilmenee, kun yritetään lisätä DeveloperMCPServer Visual Studio Codeen.

Ratkaisu: Sulje ja avaa Visual Studio Code uudelleen, ja kokeile sitten lisätä palvelin uudelleen.

Todennus- ja tunnusongelmat

Nämä ongelmat ilmenevät, kun agenttisi ei pysty tunnistautumaan oikein Microsoft 365 -palveluihin tai kun tunnistetiedot vanhenevat tai ne on väärin konfiguroitu.

Oireet:

  • 401 Unauthorized -virheet
  • "Haltijatunnus vanhentunut" -viestit
  • Agenttisen todennuksen virheet

Juurisyy:

  • Tunnukset vanhenevat noin tunnin kuluttua
  • Virheellinen tunnistautumiskokoonpano
  • Puuttuvat tai virheelliset tunnukset

Ratkaisut:

  • Haltijatunnuksen vanhentuminen

    Päivitä tunnuksesi ja päivitä ympäristömuuttujasi.

    # Get a new token
a365 develop get-token

# Update your .env file with the new token

  • Palvelinkohtaisten haltijatunnusten epäonnistumiset

    Varmista, että konfiguraatiotiedostossa on paikkamerkit jokaiselle palvelimelle (BEARER_TOKEN_<SERVER_NAME>), ja suorita a365 develop get-token uudelleen niiden täyttämiseksi. SDK muodostaa muuttujan nimen muuntamalla mcpServerNameToolingManifest.json:ssä isoiksi kirjaimiksi ja korvaamalla yhdysviivat alaviivoilla (esimerkiksi mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS).

  • Agenttisen tunnistautumisen virheet (Python)

    Tarkista .env-tiedosto

    # Should be (with underscore):
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

# Not:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

  • Puuttuvat tunnistetiedot

    Varmista, että tarvittavat tunnistetiedot ovat paikallaan ennen testausta.

    Varmista, että .env tai appsettings.json sisältävät:

    • API-avaimet ja salaisuudet
    • Vuokraajatunnus
    • Asiakastunnus
    • Blueprint ID (jos käytössä agenttinen autentikointi)

    Vahvistus:

    Testaa yksinkertaisella pyynnöllä Agenttien testausalustassa. Sinun pitäisi saada vastaus ilman 401-virheitä.

  • Työkalu- ja ilmoitusongelmat

    Nämä ongelmat liittyvät työkalukutsuihin, MCP-palvelinvuorovaikutuksiin ja ilmoitusten toimitukseen.

Sähköpostiviestiä ei vastaanotettu

Oire: Agentti ilmoittaa, että sähköposti on lähetetty, mutta et saa sitä

Ratkaisut:

  • Tarkista roskaposti- tai roskapostikansiosi.
  • Sähköpostin toimitus voi viivästyä muutamalla minuutilla. Odota enintään viisi minuuttia.
  • Varmista, että vastaanottajan sähköpostiosoite on oikea.
  • Tarkista agentin lokit sähköpostin lähetyksen virheiden varalta.

Wordin kommenttivastaukset eivät toimi

Tunnettu ongelma: Ilmoituspalvelu ei tällä hetkellä pysty vastaamaan suoraan Wordin kommentteihin. Tämä toiminnallisuus on kehitteillä.

Viestit eivät tavoita agenttia

Oire: agenttisovelluksesi ei vastaanota viestejä, jotka lähetetään agentille Teamsissa.

Mahdolliset syyt:

  • Kehittäjäportaali ei ole määritetty käyttämään agentin Blueprintia.
  • Azure Web Appin ongelmat (käyttöönottovirheet, sovelluksen toimimattomuus, konfiguraatiovirheet).
  • Agentin instanssi ei muodostu oikein Teamsissa.

Ratkaisut:

  • Tarkista kehittäjäportaalin asetukset:

    Varmista, että agentin blueprintin määritys on tehty kehittäjäportaalissa. Opi, miten agentin blueprintin konfigurointi tehdään kehittäjäportaalissa..

  • Tarkista Azure Web App Health:

    Jos otat agentin käyttöön Azureen, varmista, että Web App toimii oikein:

    1. Siirry Azure-portaaliin.
    2. Siirry Web App -resurssiisi.
    3. Tarkista Yleiskatsaus>Tila (sen tulisi olla "Käynnissä").
    4. Tarkista Lokin suoratoistoSeurataan-kohdasta mahdollisten suorituksenaikaisten virheiden varalta.
    5. Tarkista Käyttöönottokeskuksen lokit varmistaaksesi, että käyttöönotto onnistui.
    6. Varmista, että Määritys>Sovelluksen asetukset sisältävät kaikki vaaditut ympäristömuuttujat.

  • Varmista agentin instanssin luominen:

    Varmista, että luot agentti-instanssin oikein Microsoft Teamsissa:

    1. Avaa Microsoft Teams.
    2. Siirry kohtaan Sovellukset ja etsi agenttia.
    3. Varmista, että agentti näkyy hakutuloksissa.
    4. Jos agenttia ei löydy, varmista että se on julkaistu Microsoft 365 -hallintakeskuksen kohdassa Agentit.
    5. Luo uusi instanssi valitsemalla Lisää agentin kohdalla.
    6. Katso yksityiskohtaiset ohjeet kohdasta Agenttien käyttöönotto.

Havaittavuuslokien vianmääritys

Jos agentin havaittavuuslokit eivät näy odotetusti, katso havaittavuusoppaasta kohdasta Vianmääritys.

  • Last updated on