Agent-blauwdruk instellen

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

Notitie

Het instellen van een agentblueprint is vereist om de functies Registreren, Work IQ en AI-teamgenoten in te schakelen. Zie Aan de slag met Agent 365-ontwikkeling om te begrijpen welke functies van toepassing zijn op uw agent.

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.

Notitie

a365 setup all Standaard is de blueprint-agentmodus ingeschakeld. Om in plaats daarvan een AI-teamgenootagent in te stellen, geeft u --aiteammate door. Voor M365-agents (Teams, Copilot) geeft u ook --m365 door om het berichteneindpunt automatisch te registreren.

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

Notitie

Het instellen duurt doorgaans 3-5 minuten en de configuratie wordt automatisch opgeslagen in a365.generated.config.json. Als u de globale beheerder uitvoert, kan de CLI een browservenster openen voor toestemming van de beheerder. Voltooi de toestemmingsprocedure om door te gaan. Als u de installatie uitvoert als Agent ID Developer, verschijnt er geen browservenster; de CLI genereert toestemmings-URL's die een globale beheerder later moet voltooien.

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:

Stap Wie Actie
1 Ontwikkelaar Voer a365 setup all uit. De CLI voltooit alle stappen die mogelijk zijn en print de volgende stappen, inclusief een toestemmings-URL die een globale beheerder moet openen.
2 Ontwikkelaar Deel de toestemmings-URL uit de CLI-uitvoer met uw globale beheerder.
3 Wereldwijde beheerder Open de toestemmings-URL in een browser waarin u bent aangemeld als globale beheerder en verleen de gevraagde machtigingen.

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:

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:

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:

Azure

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

Agent publiceren in Microsoft-beheercentrum

Probleemoplossing

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

Fooi

De Gids voor probleemoplossing in Agent 365 bevat aanbevelingen voor probleemoplossing op hoog niveau, best practices en links naar relevante probleemoplossingsinformatie voor elk onderdeel van de Agent 365-ontwikkelingscyclus.

Deze problemen kunnen zich soms voordoen tijdens de registratie:

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.

Notitie

Als u de rol Agent-ID Beheerder of Agent-ID Ontwikkelaar hebt (niet Globale Beheerder), a365 setup all lukt het nog steeds, maar worden de OAuth2-machtigingen overgeslagen. Nadat de installatie is voltooid, geeft de CLI de volgende stappen weer voor een Globale Beheerder om de resterende machtigingen te voltooien. Deze workflow is te verwachten voor organisaties waar de agentontwikkelaar en de Globale Beheerder verschillende personen zijn.

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

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>

Fooi

Als de opdracht vastloopt tijdens de authenticatie, wordt automatisch teruggevallen op de apparaatcode-flow. Volg de instructies in de terminal om de aanmelding te voltooien.

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.
  • Last updated on