Agent-blauwdruk instellen

De agentblueprint definieert de identiteit, machtigingen en infrastructuurvereisten van uw agent. Maak elke agentinstantie aan op basis van deze agentblueprint.

Zie Agent 365-identiteit voor meer informatie over Agent 365 Identity.

Vereisten

Zorg ervoor dat u, voordat u begint, aan de volgende vereisten voldoet:

1. Agent 365 CLI - Zie Installatie van Agent 365 CLI.

2. Vereiste machtigingen:

   • Geldige tenantgebruiker met een van de volgende rollen:
     • Globale beheerder
     • Agent-id-ontwikkelaar
   • Toegang tot een Azure-abonnement met machtigingen voor het maken van resources

   Fooi

   Agenten (geen AI-teamgenoten) hebben geen configuratiebestand nodig. Gebruik a365 setup all --agent-name <name> en de CLI lost uw tenant- en client-app automatisch op. Voor het instellen van een AI-teamgenoot is een handmatig gemaakte a365.config.json vereist.

Agentblauwdruk maken

Gebruik de opdracht a365 setup om Azure-resources te maken en uw agentblauwdruk te registreren. De blauwdruk definieert de identiteit, machtigingen en infrastructuurvereisten van uw agent. Met deze stap wordt de basis gelegd voor het implementeren en uitvoeren van uw agent in Azure.

Configuratie van uitvoeren

Voer de setup-opdracht uit:

a365 setup -h

De opdracht heeft verschillende opties. U kunt de volledige installatie in één opdracht voltooien door a365 setup all te gebruiken, of u kunt gedetailleerdere opties kiezen.

Agentconfiguratie (standaard):

# With a config file
a365 setup all

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

M365-agentconfiguratie (Teams/Copilot):

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

AI-teamgenootconfiguratie:

a365 setup all --aiteammate

Het volledige configuratieproces voert de volgende bewerkingen uit:

1. Er wordt een Azure-infrastructuur gemaakt (als deze nog niet bestaat):

   • Resourcegroep
   • App-serviceplan met opgegeven SKU
   • Azure Web App waarvoor beheerde identiteit is ingeschakeld

2. Er wordt een agentblauwdruk geregistreerd:

   • Maakt de agentblauwdruk in uw Microsoft Entra-tenant
   • Maakt registraties voor Microsoft Entra-toepassingen
   • De agent-id met de vereiste machtigingen wordt geconfigureerd
   • Stelt managerApplications in op de blauwdruk, wat vereist is voor platformbeheer

   Belangrijk

   Voor blauwdrukken moet managerApplications zijn ingesteld om door het platform te worden geaccepteerd. De CLI stelt dit automatisch in. Als u een bestaande blauwdruk heeft die is gemaakt voordat deze vereiste werd geïntroduceerd, verwijdert u deze en voert u a365 setup all opnieuw uit, of patcht u deze handmatig via de Graph API.

3. API-machtigingen worden geconfigureerd:

   • Er worden Microsoft Graph API-bereiken ingesteld
   • Er worden machtigingen voor de berichtenbot-API geconfigureerd
   • Overgenomen machtigingen voor agentexemplaren worden toegepast

4. Configuratiebestanden worden bijgewerkt:

   • Slaat gegenereerde ID's en eindpunten op in een nieuw bestand in uw werkmap genaamd a365.generated.config.json
   • Informatie over beheerde identiteiten en resources worden geregistreerd

Installatie met Agent ID Developer

Als u de installatie uitvoert als Agent ID Developer (niet als globale beheerder), a365 setup allworden de meeste stappen automatisch voltooid, maar voor het verlenen van OAuth2-machtigingen is een aparte stap van de globale beheerder vereist.

Welke stappen worden automatisch voltooid:

• Azure-infrastructuur (resourcegroep, App Service Plan, Web App)
• Registratie van agentblauwdrukken
• Overerfbare machtigingen voor agentinstanties

Welke stappen vereisen een globale beheerder:

• Het verlenen van gedelegeerde OAuth2-machtigingen (AllPrincipalstoestemming) voor Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API en Power Platform API

Hoe u de installatie voltooit met een niet-beheerdersaccount:

De opdrachten uitvoeren:

# 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.

Deel de volgende stappen die door de CLI worden weergegeven met uw globale beheerder. Zij kunnen de verstrekte link of toestemmings-URL openen om de OAuth2-machtigingen te voltooien.

Installatie controleren

Wanneer de installatie is voltooid, ziet u een samenvatting met alle voltooide stappen. Controleer de gemaakte resources:

1. Controleer de gegenereerde configuratie:

   Open a365.generated.config.json in uw werkmap. Of PowerShell gebruiken:

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

   De verwachte uitvoer bevat deze kritieke waarden:

   {
   "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"
   }
   

   Belangrijke velden om te controleren:

   Veld	Doel	Wat u moet controleren
   managedIdentityPrincipalId	Authenticatie met beheerde Azure-identiteit	Moet een geldige GUID zijn
   agentBlueprintId	De unieke identificatie van uw agent	Gebruikt in de ontwikkelaarsportal en het beheercentrum
   agentBlueprintObjectId	Microsoft Entra ID van Blueprint
   messagingEndpoint	Berichtroutering	Waar Teams/Outlook berichten naar uw agent verzenden
   agentBlueprintClientSecret	Authenticatiegeheim	Moet bestaan ​​(waarde is gemaskeerd)
   resourceConsents	API-machtigingen	Moet resources bevatten zoals Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API
   completed	Instelstatus	Zou moeten zijn true

   Notitie

   Als u de installatie hebt uitgevoerd als Agent ID Administrator of Agent ID Developer, kan resourceConsents leeg zijn en completed mogelijk false totdat een globale beheerder de OAuth2-machtigingen heeft verleend met behulp van de volgende stappen die door de CLI worden weergegeven.

2. Controleer Azure-resources in Azure Portal:

   Of gebruik de az resource list PowerShell-opdracht.

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

   Controleer of de volgende resources zijn gemaakt:

   • Resourcegroep:

     • Ga naar Resourcegroepen> Selecteer uw resourcegroep
     • Controleer of het uw app-serviceplan en web-app bevat

   • App Service-plan:

     • Ga naar App Services>App Service-plannen
     • Zoek uw plan en controleer of de prijscategorie overeenkomt met uw configuratie-SKU

   • Web-app:

     • Ga naar App Services>Web Apps
     • Zoek uw web-app en ga vervolgens naar Instellingen>Identiteit>Door systeem toegewezen
     • Controleer of de status ingeschakeld is
     • De object-id (principal) komt overeen met managedIdentityPrincipalId

3. Microsoft Entra-toepassingen verifiëren in Azure Portal:

   Ga naar Azure Active Directory>App-registraties>Alle toepassingen:

   • Zoek op basis van de agentBlueprintId de blauwdruk van uw agent

   • Open de toepassing en selecteer API-machtigingen

   • Controleer aan de hand van groene vinkjes of de volgende machtigingen zijn verleend:

     • Microsoft Graph (gedelegeerde machtigingen en toepassingsmachtigingen)
     • Machtigingen voor berichtenbot-API

   • Alle machtigingen tonen "Toegekend voor [Uw tenant]"

4. Controleer of het gegenereerde configuratiebestand is aangemaakt:

   U zou een bestand moeten hebben met de naam a365.generated.config.json dat alle configuratiegegevens bevat.

   Gebruik de PowerShell-opdracht Test-Path om te controleren of het bestaat.

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

   Belangrijk

   Sla zowel het a365.config.json- als het a365.generated.config.json-bestand op. U heeft deze waarden nodig voor implementatie en probleemoplossing.

5. Controleer of beheerde identiteit is ingeschakeld voor de web-app:

   Gebruik de opdracht az webapp identity show om te controleren of beheerde identiteit is ingeschakeld.

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

   Verwacht:

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

6. Controleer of de agentblauwdruk is geregistreerd in Microsoft Entra:

   Zoek in het Microsoft Entra-beheercentrum naar uw agentBlueprintId of zoek op naam.

   Controleer of:

   ✅ App-registratie en bedrijfsapplicatie worden weergegeven
   ✅ Op de blauwdruk voor app-registratie toont het tabblad API-machtigingen alle machtigingen
   ✅ De status toont "Verleend voor [Uw tenant]"

Zie voor meer hulp:

• Problemen met aangepaste client-apps

Agentmachtigingen

Voordat apps en agents Microsoft 365-gegevens (gebruikers, e-mail, bestanden, Teams, agents, enzovoort) kunnen lezen of schrijven, moet u ze expliciet Microsoft Graph-machtigingen verlenen. Microsoft Graph-machtigingen zijn het autorisatiemodel dat bepaalt tot welke gegevens en acties een app of service toegang heeft via Microsoft Graph API's in Microsoft 365 en Microsoft Entra ID.

Meer informatie: Overzicht van Microsoft Graph-machtigingen

Om Graph-machtigingen te gebruiken voor Agent 365-agentinstanties, moet de ontwikkelaar deze in de agentblauwdruk declareren. Wanneer een beheerder de blauwdruk activeert in Microsoft 365-beheercentrum, controleert de portal de Graph-machtigingen van de blauwdruk en vraagt ​​de beheerder om toestemming.

Om te begrijpen en te controleren hoe Graph-machtigingen uw agent mogelijk maken, kunt u het volgende doen:

• Alle beschikbare Graph-machtigingen bekijken.
• Graph Explorer bezoeken om query's uit te proberen, antwoorden te inspecteren en machtigingen te begrijpen.
• Microsoft 365 Agents Playground gebruiken om uw agent lokaal te testen vóór de implementatie.

Machtigingen toepassen op uw blauwdruk

a365 setup permissions custom gebruiken om aangepaste API-machtigingen rechtstreeks op uw blauwdruk in Microsoft Entra toe te passen.

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

Zie setup permissions custom voor meer informatie over het configureren en verwijderen van aangepaste machtigingen.

Volgende stappen

Uw agentcode implementeren in de cloud:

Probleemoplossing

In dit gedeelte worden veelvoorkomende problemen beschreven die zich kunnen voordoen bij het instellen van agent-blueprints.

Deze problemen kunnen zich soms voordoen tijdens de registratie:

• Foutmelding 'Onvoldoende machtigingen'
• Authenticatie voor Azure CLI ontbreekt
• Resource bestaat al
• Beheerderstoestemming niet voltooid
• Configuratiebestanden ontbreken of zijn ongeldig
• Installatie voltooid, maar resources worden niet gemaakt
• Agentblauwdruk niet geregistreerd in Microsoft Entra
• API-machtigingen niet verleend
• Beheerde identiteit niet ingeschakeld
• Installatie duurt te lang of reageert niet meer
• Een agent zonder configuratie opschonen
• Kan het eerste bericht in Teams niet verzenden

Foutmelding 'Onvoldoende machtigingen'

Symptoom: Foutmelding 'Onvoldoende machtigingen' tijdens de uitvoering van de opdracht a365 setup.

U hebt een van de volgende rollen nodig in uw Microsoft Entra-tenant:

• Globale beheerder
• Agent-id-ontwikkelaar

En toegang als bijdrager of eigenaar van een Azure-abonnement.

Oplossing: Controleer of u de vereiste machtigingen in Microsoft Entra hebt.

• Ga naar: Microsoft Entra-beheercentrum> Uw profiel> Toegewezen rollen
• Controleer de toegang tot uw Azure-abonnement met behulp van de az account show PowerShell-opdracht

Authenticatie voor Azure CLI ontbreekt

Symptoom: De installatie mislukt met authenticatiefouten.

Oplossing: Zorg ervoor dat u bent verbonden met Azure en controleer uw account en abonnement.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

De resource bestaat al

Symptoom: De installatie mislukt met een Resource already exists fout voor resourcegroep, App Service-abonnement of web-app.

Oplossingen: Kies een van de volgende oplossingen.

• Bestaande resources gebruiken

  Als er resources bestaan ​​en u deze wilt gebruiken, zorg er dan voor dat ze overeenkomen met uw configuratie. Gebruik de PowerShell-opdracht az resource list.

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

• Verwijder conflicterende resources

  Verwijder de resourcegroep of hernoem uw resources in a365.config.json en voer de installatie opnieuw uit.

  Gebruik de PowerShell-opdracht az group delete om een ​​resourcegroep te verwijderen.

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

• Gebruik de opschoonopdracht om opnieuw te beginnen

  Gebruik de opdracht cleanup om alle Agent 365-resources te verwijderen en gebruik vervolgens de opdracht a365 setup all om de installatie opnieuw uit te voeren.

  Waarschuwing

  Het uitvoeren van a365 cleanup is destructief.

  a365 cleanup
  a365 setup all
  

Beheerderstoestemming niet voltooid

Symptoom: U heeft browservensters geopend tijdens de installatie, maar deze gesloten zonder de toestemming te voltooien, of de installatie is voltooid, maar de OAuth2-machtigingen zijn nog in behandeling.

Oplossing: Kies op basis van uw rol:

• Globale beheerder: Voer a365 setup all opnieuw uit. De CLI vraagt ​​om beheerderstoestemming. Voltooi de toestemmingsprocedure in het browservenster dat verschijnt.

• Agent-ID Beheerder of Ontwikkelaar: U kunt OAuth2-toekenningen niet rechtstreeks voltooien. Voer a365 setup all uit — het installatieoverzicht toont de volgende stappen voor een globale beheerder, inclusief een directe link of toestemmings-URL om de toekenningen te voltooien. Deel deze gegevens met uw globale beheerder.

Configuratiebestanden ontbreken of zijn ongeldig

Symptoom: De installatie mislukt met "Configuratie niet gevonden" of validatiefouten.

Oplossing:

1. Controleer of het bestand a365.config.json bestaat.
2. Als het ontbreekt of ongeldig is, maak het dan handmatig aan of gebruik a365 setup all --agent-name <name> (alleen voor agents).

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

Installatie voltooid, maar resources worden niet gemaakt

Symptoom: De installatieopdracht is geslaagd, maar de Azure-resources bestaan ​​niet.

Oplossing:

1. Controleer de aangemaakte resources door a365.generated.config.json in uw werkmap te openen.
2. Controleer of de Azure-resources bestaan ​​met behulp van de opdracht az resource list.
3. Als resources ontbreken, controleer dan de installatie-uitvoer op fouten en voer de installatie opnieuw uit met behulp van de opdracht a365 setup all.

# 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

Agentblauwdruk niet geregistreerd in Microsoft Entra

Symptoom: De installatie is voltooid, maar u kunt de agentblauwdruk niet vinden in het Microsoft Entra-beheercentrum.

Oplossing:

1. Haal de blauwdruk-ID op via a365.generated.config.json.

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

2. Zoeken in het Microsoft Entra-beheercentrum:

   1. Ga naar: Microsoft Entra-beheercentrum.
   2. Navigeer naar App-registraties>Alle toepassingen.
   3. Zoek naar uw agentBlueprintId.

3. Als u deze niet vindt, voert u de installatie opnieuw uit met de opdracht a365 setup all.

   a365 setup all
   

API-machtigingen niet verleend

Symptoom: De installatie is voltooid, maar de machtigingen worden in Microsoft Entra weergegeven als 'Niet verleend'.

Oplossing:

1. Open Microsoft Entra-beheercentrum.

2. Zoek de app-registratie van uw agentblueprint.

3. Ga naar API-machtigingen.

4. Beheerdersrechten verlenen:

   1. Selecteer Beheerdersrechten verlenen voor [Uw tenant].
   2. Bevestig de actie.

5. Controleer of alle machtigingen groene vinkjes weergeven.

Beheerde identiteit niet ingeschakeld

Symptoom: De web-app bestaat, maar de beheerde identiteit is niet ingeschakeld.

Oplossing:

1. Controleer de status van de beheerde identiteit met behulp van de az webapp identity show-opdracht.
2. Als deze niet is ingeschakeld, schakel deze dan handmatig in met behulp van de az webapp identity assign-opdracht.
3. Controleer of deze is ingeschakeld met behulp van de az webapp identity show-opdracht.

# 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>

Installatie duurt te lang of reageert niet meer

Symptoom: De installatieopdracht wordt langer dan 10 minuten uitgevoerd zonder te worden voltooid.

Oplossing:

1. Als u als globale beheerder werkt, controleer dan of er een browservenster wacht op toestemming van de beheerder. Voltooi de toestemmingsprocedure om de installatie te deblokkeren.

2. Als de installatie echt niet meer reageert, annuleer deze dan (Ctrl+C) en controleer wat er is gemaakt.

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

3. Opruimen en opnieuw proberen.

   a365 cleanup
   a365 setup all
   

Een agent zonder configuratie opschonen

Symptoom: U heeft een agent geconfigureerd met a365 setup all --agent-name <name> en wilt deze nu verwijderen, maar u hebt geen a365.config.json-bestand.

Oplossing: Gebruik a365 cleanup --agent-name om de agent zonder configuratiebestand te verwijderen. De CLI leest resource-ID's uit de globaal gegenereerde configuratie die tijdens de bootstrap-installatie is geschreven.

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

Als u de globaal gegenereerde configuratie niet meer hebt (bijvoorbeeld na het opnieuw installeren van de CLI), gebruikt u a365 cleanup met een handmatig gemaakte minimale a365.config.json, of verwijdert u resources rechtstreeks via Azure Portal en Microsoft Entra-beheercentrum.

Kan het eerste bericht in Teams niet verzenden

Symptoom: Na het inrichten van een agent-instantie kan deze geen welkomstbericht naar de agentmanager verzenden.

Oplossing: De machtiging [Chat.Create][perm-chatcreate] is vereist om een ​​nieuw chatobject te maken. Als er al een één-op-één-chat bestaat, retourneert deze bewerking de bestaande chat en maakt geen nieuwe aan.

• Om dit te implementeren, configureer de overerfbare machtigingen van uw blueprint zodat deze het Chat.Create-bereik bevatten.
• Configureer een Teams-chatbericht dat moet worden verzonden zodra een agent-instantie is ingericht.
• Maak een nieuwe agent-instantie aan vanuit de blueprint en test het eerste bericht.