Agentin suunnitelman määrittäminen

Agentin etenemissuunnitelma määrittelee agentin käyttäjätieto-, käyttöoikeus- ja infrastruktuurivaatimukset. Jokainen agenttiesiintymä luodaan tästä agentin etenemissuunnitelmasta.

Lisätietoja Agent 365 -käyttäjätiedoista on kohdassa Agent 365 -käyttäjätiedot.

Edellytykset

Ennen aloittamista on varmistettava, että seuraavat edellytykset täyttyvät:

1. Agent 365 CLI – lisätietoja on kohdassa Agent 365 CLI -asennus.

2. Tarvittavat oikeudet:

   • Kelvollinen vuokraajan käyttäjä, jolla on jompikumpi seuraavista rooleista:
     • – yleinen järjestelmänvalvoja
     • Agenttitunnuksen kehittäjä
   • Resurssien luontioikeudet sisältävän Azure-tilauksen käyttöoikeus

   Vinkki

   Agentit (ei koske tekoälytiimikavereita) eivät tarvitse määritystiedostoa. Kun käytössä on a365 setup all --agent-name <name>, komentorivikäyttöliittymä ratkaisee vuokraajan ja asiakassovelluksen automaattisesti. Tekoälytiimikaverin määritykseen tarvitaan manuaalisesti luotu a365.config.json.

Agentin etenemissuunnitelman luominen

Luo Azure-resurssit ja rekisteröi agentin etenemissuunnitelmaa365 setup-komennolla. Etenemissuunnitelma määrittelee agentin käyttäjätieto-, käyttöoikeus- ja infrastruktuurivaatimukset. Tämä vaihe muodostaa perustan agentin käyttöönotolle ja suorittamiselle Azuressa.

Suorita -määritys

Suorita määrityskomento:

a365 setup -h

Komennosta on useita vaihtoehtoja. Koko määritys voidaan suorittaa yhdellä komennolla, kun käytössä on a365 setup all. Voit myös rakenteisempia vaihtoehtoja.

Agentin määritys (oletus):

# With a config file
a365 setup all

# Config-free — no a365.config.json needed
a365 setup all --agent-name <your-agent-name>

M365-agentin määritys (Teams/Copilot):

# Registers the messaging endpoint via MCP Platform
a365 setup all --m365

Tekoälytiimitoverin määritys:

a365 setup all --aiteammate

Määritysprosessi suorittaa seuraavat toiminnot:

1. Azure-infrastruktuurin luonti (jos sellaista ei vielä ole):

   • Resurssiryhmä
   • Sovelluspalvelupaketti ja määritetty SKU
   • Azure-verkkosovellus hallitut käyttäjätiedot käyttöönotettuina

2. Agentin etenemissuunnitelman rekisteröinti:

   • Luo agentin etenemissuunnitelman Microsoft Entra -vuokraajaan
   • Luo Microsoft Entran sovellusrekisteröinnit
   • Määrittää agentin käyttäjätiedot ja tarvittavat käyttöoikeudet
   • Tekee managerApplications-määrityksen etenemissuunnitelma, mitä ympäristön hallittavuus edellyttää.

   Tärkeää

   Ympäristön on hyväksyttävä etenemissuunnitelman managerApplications-määritys. Ohjelmointirajapintaa määrittää sen automaattisesti. Jos etenemissuunnitelma luotiin, ennen kuin tämä vaatimus otettiin käyttöön, se on poistettava ja a365 setup all suoritettava uudelleen. Vaihtoehtoisesti se voidaan korjata manuaalisesti Graph API:n kautta.

3. Ohjelmointirajapinnan oikeuksien määritys:

   • Määrittää Microsoft Graph API -vaikutusalueet
   • Määrittää viestintäbotin ohjelmointirajapinnan oikeudet
   • Käyttää periytyviä oikeuksia agenttiesiintymissä

4. Määritystiedostojen päivitys:

   • Tallentaa luodut tunnukset ja päätepisteet uuteen työhakemiston tiedostoon, jonka nimi on a365.generated.config.json.
   • Kirjaa hallitut käyttäjätiedot ja resurssin tiedot

Agenttitunnuksen kehittäjän suorittama määritys

Jos kyseessä on agenttitunnuksen kehittäjä (eikä yleinen järjestelmävalvoja), a365 setup all suorittaa useimmat vaiheet automaattisesti; OAuth2-oikeuksien myöntämiseen tarvitaan kuitenkin erillistä yleisen järjestelmänvalvojan vaihetta.

Automaattisesti suoritettavat vaiheet:

• Azure-infrastruktuuri (resurssiryhmä, sovelluspalvelupaketti, verkkosovellus)
• Agentin etenemissuunnitelman rekisteröinti
• Agenttiesiintymien periytyvät käyttöoikeudet

Yleisen järjestelmänvalvojan toimia edellyttävät vaiheet:

• Delegoitujen OAuth2-oikeuksien myöntäminen (AllPrincipalssuostumus) seuraaville: Microsoft Graph, Agent 365 Tools, viestibotin ohjelmointirajapinta, havaittavuuden ohjelmointirajapinta ja Power Platformin ohjelmointirajapinta

Määrityksen viimeistely muun kuin järjestelmänvalvojan tiliä käytettäessä:

Komentojen suorittaminen:

# Developer runs:
a365 setup all
# Setup completes all steps it can. The CLI prints the next steps
# for a Global Administrator directly in the output, including a
# direct link or consent URL they can open to complete the grants.

Seuraavat komentorivikäyttöliittymän tulokseksi antamat vaiheet välitetään yleiselle järjestelmänvalvojalle. Tämä voi sitten myöntää OAuth2-oikeudet avaamalla annetun linkin tai suostumuksen URL-osoitteen.

Määrityksen tarkistaminen

Kun määritys on valmis, kaikki suoritetut vaiheet näkyvät yhteenvedossa. Tarkista luodut resurssit:

1. Tarkista luotu määritys:

   Avaa a365.generated.config.json työhakemistossa. Voit käyttää vaihtoehtoisesti PowerShellia:

   Get-Content a365.generated.config.json | ConvertFrom-Json
   

   Odotettu tulos sisältää seuraavat tärkeät arvot:

   {
   "managedIdentityPrincipalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintServicePrincipalObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintClientSecret": "xxx~xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "agentBlueprintClientSecretProtected": true,
   "botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "botMsaAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "messagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
   "resourceConsents": [],
   "completed": true,
   "completedAt": "xxxx-xx-xxTxx:xx:xxZ",
   "cliVersion": "x.x.xx"
   }
   

   Tarkistettavat keskeiset kentät:

   Kenttä	Tarkoitus	Tarkistettava asia
   managedIdentityPrincipalId	Azuren hallittujen käyttäjätietojen todennus	GUID-tunnuksen on oltava kelvollinen
   agentBlueprintId	Agentin yksilöllinen tunniste	Käytetään kehittäjäportaalissa ja hallintakeskuksessa
   agentBlueprintObjectId	Etenemissuunnitelman Microsoft Entra ID
   messagingEndpoint	Viestien reititys	Paikka, johon Teams/Outlook lähettää viestejä agentille
   agentBlueprintClientSecret	Todennussalaisuus	Oltava olemassa (arvo on peitetty)
   resourceConsents	Ohjelmointirajapinnan käyttöoikeudet	Sen on sisällettävä resursseja, kuten Microsoft Graph, Agent 365 Tools, viestibotin ohjelmointirajapinta ja havaittavuuden ohjelmointirajapinta
   completed	Määrityksen tila	Oltava true

   Muistiinpano

   Jos määritys tehdään agentin tunnuksen järjestelmänvalvojan tai agentin tunnuksen kehittäjänä, resourceConsents saattaa olla tyhjä ja completed saattaa olla false, kunnes yleinen järjestelmänvalvoja myöntää OAuth2-oikeudet käyttämällä komentorivikäyttöliittymän tulokseksi antamia seuraavia vaiheita.

2. Varmista Azure-resurssit Azure-portaalissa:

   Vaihtoehtoisesti voit käyttää PowerShellin az resource list-komentoa.

   # List all resources in your resource group
   az resource list --resource-group <your-resource-group> --output table
   

   Varmista, että seuraavat resurssit on luotu:

   • Resurssiryhmä:

     • Valitse ensin Resurssiryhmät> ja sitten resurssiryhmä
     • Varmista, että se sisältää sovelluspalvelupaketin ja verkkosovelluksen

   • Sovelluspalvelupaketti:

     • Valitse Sovelluspalvelut>Sovelluspalvelupaketit
     • Etsi palvelupaketti ja tarkista, että hinnoittelutaso vastaan määrityksen SKU:ta

   • Verkkosovellus:

     • Valitse Sovelluspalvelut>Verkkosovellukset
     • Etsi verkkosovellus ja valitse sitten Asetukset>Käyttäjätiedot>Järjestelmän määrittämät
     • Tarkista, että tilana on Käytössä
     • Huomaa, että objektin (päänimen) tunnus on sama kuin managedIdentityPrincipalId

3. Tarkista Microsoft Entra -sovellukset Azure-portaalissa:

   Valitse Azure Active Directory>Sovellusten rekisteröinnit>Kaikki sovellukset:

   • Hae agentin etenemissuunnitelmaa agentBlueprintId-komennolla

   • Avaa sovellus ja valitse Ohjelmointirajapinna oikeudet.

   • Varmista vihreän valintamerkin avulla, että oikeudet on myönnetty:

     • Microsoft Graph (delegoidut ja sovelluksen oikeudet)
     • Viestibotin ohjelmointirajapinnan oikeudet

   • Kaikki oikeudet näkyvät kohdassa Myönnetty vuokraajalle [vuokraaja]

4. Tarkista, että generoitu määritystiedosto luotiin:

   Käytettävissä on oltava a365.generated.config.json-tiedosto, joka sisältää kaikki määritystiedot.

   Tarkista, että se on olemassa, PowerShellin Testipolku-komennolla.

   # Check file exists
   Test-Path a365.generated.config.json
   # Should return: True
   

   Tärkeää

   Tallenna sekä a365.config.json- että a365.generated.config.json-tiedosto. Näitä arvoja tarvitaan käyttöönottoon ja vianmääritykseen.

5. Varmista, että hallitut käyttäjätiedot on otettu käyttöön verkkosovelluksessa:

   Tarkista az webapp identity show-komennolla, ovatko hallitut käyttäjätiedot käytössä.

   az webapp identity show --name <your-web-app> --resource-group <your-resource-group>
   

   Odotettu:

   {
   "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "type": "SystemAssigned"
   }
   

6. Tarkista Microsoft Entraan rekisteröity agentin etenemissuunnitelma:

   Käytä Microsoft Entra -hallintakeskuksessa hakusanaa agentBlueprintId tai hae nimellä.

   Tarkista, että

   ✅ sovelluksen rekisteröinti ja Enterprise-sovellus näkyvät
   ✅ Kaikki oikeudet näkyvät sovelluksen rekisteröinnin etenemissuunnitelmassa Ohjelmointirajapinnan käyttöoikeudet -välilehdessä
   ✅ Tilana näkyy Myönnetty vuokraajalle [vuokraaja]

Lisätietoja:

• Mukautettujen asiakassovellusten ongelmat

Agentin käyttöoikeudet

Ennen kuin sovellukset ja agentit voivat lukea tai kirjoittaa Microsoft 365 -tietoja (käyttäjät, sähköposti, tiedostot, Teams, agentit jne.), niille on erikseen myönnettävä Microsoft Graphin käyttöoikeudet. Microsoft Graphin käyttöoikeudet ovat valtuutusmalli, joka määrittää, mitä tietoihin ja toimintoja sovellus tai palvelu voi käyttää Microsoft Graph API:en kautta Microsoft 365:ssä ja Microsoft Entra ID:ssä.

Lisätietoja: Microsoft Graphin käyttöoikeuksien yleiskatsaus

Graph-käyttöoikeuksien käyttö Agent 365 -agenttiesiintymissä edellyttää, että kehittäjä esittelee ne agentin etenemissuunnitelmassa. Kun järjestelmänvalvoja aktivoi etenemissuunnitelman Microsoft 365 -hallintakeskuksessa, portaali tarkistaa etenemissuunnitelman Graph-oikeudet ja pyytää järjestelmää hyväksymään ne.

Graph-käyttöoikeuksien agentille mahdollistaman toiminnan ymmärtäminen ja tarkistaminen:

• Kaikkien Graph-oikeuksien, jotka ovat saatavilla, tarkasteleminen.
• Graph-työkalun testauksessa voi kokeilla kyselyjä, tarkastaa vastauksia ja ymmärtää käyttöoikeuksia.
• Microsoft 365:n agenttien testausalustassa testata agenttiasi paikallisesti ennen käyttöönottoa.

Käyttöoikeuksien käyttäminen etenemissuunnitelmassa

a365 setup permissions custom mahdollistaa mukautetun ohjelmointirajapinnan oikeuksien käytön suoraan etenemissuunnitelmassa Microsoft Entrassa.

a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

Lisätietoja mukautettujen käyttöoikeuksien määrittämisestä ja poistamisesta on kohdassa setup permissions custom.

Seuraavat vaiheet

Agenttikoodin ottaminen käyttöön pilvessä:

Vianmääritys

Tässä osiossa käsitellään yleisiä agentin etenemissuunnitelmien määrittämistä koskevia ongelmia.

Seuraavat ongelmat esiintyvät joskus rekisteröinnin aikana:

• Riittämättömiä käyttöoikeuksia koskeva virhe
• Azure CLI -todennus puuttuu
• Resurssi on jo olemassa
• Järjestelmänvalvojan suostumusta ei ole annettu
• Määritystiedostot puuttuvat tai ovat virheellisiä
• Määritys suoritetaan mutta resursseja ei luoda
• Agentin etenemissuunnitelmaa ei ole rekisteröity Microsoft Entraan
• Ohjelmointirajapinnan oikeuksia ei ole myönnetty
• Hallittuja käyttäjätietoja ei ole otettu käyttöön
• Määritys kestää liian kauan tai lakkaa vastaamasta
• Määrityksettömän agentin puhdistaminen
• Aloitusviestin lähetys Teamsissa ei onnistu

Riittämättömiä käyttöoikeuksia koskeva virhe

Oire: riittämättömiä käyttöoikeuksia koskeva virhe a365 setup -komennon suorittamisen aikana.

Tarvitset jommankumman seuraavista rooleista Microsoft Entra -vuokraajassa:

• – yleinen järjestelmänvalvoja
• Agenttitunnuksen kehittäjä

Azure-tilauksen osallistujan tai omistajan käyttöoikeus.

Ratkaisu: Tarkista Microsoft Entrassa, että sinulla on vaaditut käyttöoikeudet.

• Valitse Microsoft Entra -hallintakeskus>Oma profiili > Määrätyt roolit
• Tarkista Azure-tilauksen käyttöoikeus PowerShellin az account show-komennolla

Azure CLI -todennus puuttuu

Oire: määritys epäonnistuu todennusvirheiden vuoksi.

Ratkaisu: Azure-yhteys on varmistettava sekä tili ja tilaus tarkistettava.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

Resurssi on jo olemassa

Oire: määritys epäonnistuu resurssiryhmän, sovelluspalvelupaketin tai verkkosovelluksen Resource already exists-virheen vuoksi.

Ratkaisut: valitse yksi seuraavista ratkaisuista.

• Käytä aiemmin luotuja resursseja

  Jos resurssit ovat olemassa ja haluat käyttää niitä, varmista, että ne vastaavat määritystä. Käytä PowerShellin az resource list-komentoa.

  az resource list --resource-group <your-resource-group>
  

• Poista ristiriitaiset resurssit

  Poista resurssiryhmä tai nimeä resurssit uudelleen a365.config.json-tiedostossa ja suorita määritys uudelleen.

  Poista resurssiryhmä käyttämällä PowerShellin az group delete-komentoa.

  # WARNING: This command deletes all resources in it
  az group delete --name <your-resource-group>
  

• Aloita alusta puhdistuskomennon käytön jälkeen

  Poista kaikki Agent 365 -resurssit cleanup-komennolla ja suorita määritys sitten uudelleen a365 setup all-komennolla.

  Varoitus

  a365 cleanup-komennon suorittaminen on tuhoavaa.

  a365 cleanup
  a365 setup all
  

Järjestelmänvalvojan suostumusta ei ole annettu

Oire: selainikkunat avattiin määrityksen aikana ja ne suljettiin suostumatta antamatta taikka määritys valmistui, mutta OAuth2-oikeuksien myöntäminen odottaa vielä.

Ratkaisu: valitse roolin perusteella:

• Yleinen järjestelmänvalvoja: Suorita a365 setup all uudelleen. Komentorivikäyttöliittymä pyytää järjestelmänvalvojan suostumusta. Suorita suostumustyönkulku avautuvassa selainikkunassa.

• Agenttitunnuksen järjestelmänvalvoja tai kehittäjä: OAuth2-oikeuksia ei voi myöntää suoraan. Suorita a365 setup all – määrityksen yhteenvedossa on seuraavat yleistä järjestelmänvalvojaa koskevat vaiheet, mukaan lukien suora oikeuksien myöntämislinkki tai suostumuksen URL-osoite. Välitä nämä tiedot yleiselle järjestelmänvalvojalle.

Määritystiedostot puuttuvat tai ovat virheellisiä

Oire: määrityksen epäonnistuu joko Määritys ei löydy- tai tarkistusvirheiden vuoksi.

Ratkaisu:

1. Varmista, että a365.config.json-tiedosto on olemassa.
2. Jos tiedosto puuttuu tai on virheellinen, luo se manuaalisesti tai käytä komentoa a365 setup all --agent-name <name> (vain agentit).

# Verify a365.config.json exists
Test-Path a365.config.json

Määritys suoritetaan mutta resursseja ei luoda

Oire: määrityskomento onnistuu, mutta Azure-resursseja ei ole.

Ratkaisu:

1. Tarkista luodut resurssit avaamalla a365.generated.config.json työhakemistossa.
2. Varmista, että Azure-resurssit ovat olemassa käyttämällä az resource list-komentoa.
3. Jos resursseja puuttuu, tarkista, onko määrityksen tuloksissa palautettu virheitä, suorita määritys uudelleen a365 setup all-komennolla.

# Check created resources
Get-Content a365.generated.config.json | ConvertFrom-Json

# Verify Azure resources exist
az resource list --resource-group <your-resource-group> --output table

# If resources missing, check for errors in setup output and re-run
a365 setup all

Agentin etenemissuunnitelmaa ei ole rekisteröity Microsoft Entraan

Oire: määritys valmistuu mutta agentin etenemissuunnitelmaa ei löydy Microsoft Entra -hallintakeskuksesta.

Ratkaisu:

1. Hae etenemissuunnitelman tunnus a365.generated.config.json-tiedostosta.

   Get-Content a365.generated.config.json | ConvertFrom-Json | Select-Object agentBlueprintId
   

2. Tee haku Microsoft Entra -hallintakeskuksessa:

   1. Siirry: Microsoft Entra -hallintakeskus.
   2. Valitse Sovelluksen rekisteröinnit>Kaikki sovellukset.
   3. Hae oma agentBlueprintId-tunnuksesi.

3. Jos etenemissuunnitelma ei löydy, suorita määritys uudelleen a365 setup all-komennolla.

   a365 setup all
   

Ohjelmointirajapinnan oikeuksia ei ole myönnetty

Oire: määritys valmistuu, mutta käyttöoikeuden tilana näkyy Microsoft Entrassa Ei myönnetty.

Ratkaisu:

1. Avaa Microsoft Entra -hallintakeskus.

2. Etsi agentin etenemissuunnitelman sovelluksen rekisteröinti.

3. Siirry Ohjelmointirajapintaoikeuksiin.

4. Myönnä järjestelmänvalvojan suostumus:

   1. Valitse Myönnä järjestelmänvalvojan suostumus vuokraajalle [vuokraaja].
   2. Vahvista toiminto.

5. Varmista, että kaikissa käyttöoikeuksissa on vihreä valintamerkki.

Hallittuja käyttäjätietoja ei ole otettu käyttöön

Oire: verkkosovellus on olemassa, mutta hallittuja käyttäjätietoja ei ole otettu käyttöön.

Ratkaisu:

1. Tarkista hallittujen käyttäjätietojen tila az webapp identity show-komennolla.
2. Jos ottamatta käyttöön, tee käyttöönotto manuaalisesti az webapp identity assign-komennolla.
3. Varmista käyttöönotto az webapp identity show-komennolla.

# Check managed identity status
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

# If not enabled, enable it manually
az webapp identity assign --name <your-web-app> --resource-group <your-resource-group>

# Verify it's enabled
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

Määritys kestää liian kauan tai lakkaa vastaamasta

Oire: määrityskomentoa suoritetaan yli 10 minuuttia eikä se valmistu.

Ratkaisu:

1. Jos käyttäjä on yleinen järjestelmänvalvoja, tarkista odottaako selainikkuna järjestelmänvalvoja suostumusta. Poista määrityksen esto suorittamalla suostumustyönkulku loppuun.

2. Jos määritys todellakin lakkaa vastaamasta, peruuta se (Ctrl+C) ja tarkista, mitä luotiin.

   # Check generated config
   Get-Content a365.generated.config.json | ConvertFrom-Json
   
   # Check Azure resources
   az resource list --resource-group <your-resource-group>
   

3. Puhdista ja yritä uudelleen.

   a365 cleanup
   a365 setup all
   

Määrityksettömän agentin puhdistaminen

Oire: agentti valmisteltiin a365 setup all --agent-name <name>-komennolla ja haluat poistaa sen, mutta a365.config.json-tiedostoa ei ole.

Ratkaisu:Poista agentti ilman määritystiedostoa a365 cleanup --agent-name-komennolla. Komentorivikäyttöliittymä lukee resurssitunnukset yleisesti luodusta määrityksestä, joka kirjoitettiin Bootstrap-määrityksen aikana.

a365 cleanup --agent-name <your-agent-name>

Jos yleisesti luotu määritys ei ole enää käytettävissä (esimerkiksi käyttörivikäyttöliittymän uudelleenasennuksen jälkeen), käytä a365 cleanup-koodia manuaalisesti luodun minimaalisen a365.config.json-tiedoston kanssa tai poista resurssit suoraan Azure-portaalissa ja Microsoft Entra -hallintakeskuksessa.

Aloitusviestin lähetys Teamsissa ei onnistu

Oire: agenttiesiintymän valmistelun jälkeen viestin lähettäminen tervehdysviestinä agenttien hallintaan ei onnistu.

Ratkaisu: Uuden keskusteluobjektin luontia varten tarvitaan [Chat.Create][perm-chatcreate]-oikeus. Jos kahdenkeskinen keskustelu on jo olemassa, tämä toiminto palauttaa olemassa olevan keskustelun eikä luo uutta.

• Toteutus edellyttää etenemissuunnitelman periytyvien oikeuksien määrittäminen sisältämään Chat.Create-vaikutusalue.
• Teams-keskusteluviesti määritetään lähetettäväksi, kun agenttiesiintymä on valmisteltu.
• Uuden agenttiesiintymän luonti etenemissuunnitelmasta ja aloitusviestin testaaminen.