Konfigurera agent blueprint

Agent blueprint definierar din agents identitet, behörigheter och infrastrukturkrav. Skapa varje agentinstans utifrån denna agent blueprint.

För mer information om Agent 365 Identity, se Agent 365 Identity.

Krav

Innan du börjar, se till att du har följande förutsättningar:

1. Agent 365 CLI - se Installera Agent 365 CLI.

2. Behörigheter som krävs:

   • Giltig användare i klientorganisationen med en av följande roller:
     • Global administratör för
     • Agent ID-utvecklare
   • Tillgång till en Azure-prenumeration med behörigheter att skapa resurser

   Dricks

   Agenter (inte AI-teammedlemmar) behöver ingen konfigurationsfil. Använd a365 setup all --agent-name <name> och CLI:n hanterar automatiskt din Azure-tenant och klientapp. Konfiguration av AI-teammedlem kräver en manuellt skapad a365.config.json.

Skapa blueprint för en agent

Använd kommandot a365 setup för att skapa Azure-resurser och registrera din agent-blueprint. Blueprint definierar din agents identitet, behörigheter och infrastrukturkrav. Detta steg lägger grunden för att distribuera och köra din agent i Azure.

Kör -konfiguration

Kör konfigurationskommandot:

a365 setup -h

Kommandot har olika alternativ. Du kan slutföra hela uppsättningen i ett enda kommando genom att använda a365 setup all eller välja mer detaljerade alternativ.

Agentuppsättning (förval):

# With a config file
a365 setup all

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

M365-agentuppsättning (Teams/Copilot):

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

AI-lagkamratuppställning:

a365 setup all --aiteammate

Hela uppsättningsprocessen utför dessa operationer:

1. Skapar Azure-infrastruktur (om den inte redan finns):

   • Resursgrupp
   • App Service Plan med angiven SKU
   • Azure Web App med hanterad identitet aktiverad

2. Registrerar agent blueprint:

   • Skapar agent blueprinten i din Microsoft Entra-tenant
   • Skapar Microsoft Entra-applikationsregistreringar
   • Konfigurerar agentidentiteten med nödvändiga behörigheter
   • Sätter managerApplications på ritningen, vilket krävs för plattformshantering

   Viktigt

   Blueprints måste ha managerApplications satt för att accepteras av plattformen. CLI ställer in detta automatiskt. Om du har en befintlig blueprint som skapades innan detta krav infördes, ta bort den och kör a365 setup all igen, eller patcha den manuellt via Graph API:n.

3. Konfigurera API-behörigheter:

   • Sätter upp Microsoft Graph API-scopes
   • Konfigurerar meddelandebot-API-behörigheter
   • Tillämpar ärvbara behörigheter för agentinstanser

4. Uppdaterar GDPR-konfigurationsfiler:

   • Sparar genererade ID:n och endpoints till en ny fil i din arbetskatalog som heter a365.generated.config.json
   • Sparar information om hanterad identitet och resurser

Uppsättning genom att använda Agent ID Developer

Om du kör som Agent ID Developer (inte Global Administrator), utför a365 setup all de flesta steg automatiskt, men OAuth2-behörigheter måste godkännas separat av en Global Administrator.

Vilka steg utförs automatiskt:

• Azure-infrastruktur (resursgrupp, App Service Plan, Web App)
• Registrering av agent blueprint
• Ärvbara behörigheter för agentinstanser

Steg som kräver en Global administratör:

• OAuth2 delegerade behörighetsbeviljanden (AllPrincipalssamtycke) för Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API, och Power Platform API

Hur man slutför installationen med ett icke-administratörskonto:

Kör kommandona:

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

Dela nästa steg som visas i CLI-utskriften med din Global Administratör. De kan öppna den angivna länken eller samtyckes-URL:en för att slutföra OAuth2-godkännandena.

Verifiera konfigurationen

När uppsättningen är klar ser du en sammanfattning som visar alla slutförda steg. Verifiera de skapade resurserna:

1. Verifiera genererad konfiguration:

   Öppna a365.generated.config.json i din arbetskatalog. Eller använd PowerShell:

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

   Förväntad utdata innehåller dessa kritiska värden:

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

   Nyckelfält att verifiera:

   Fält	Syfte	Vad du bör kontrollera
   managedIdentityPrincipalId	Autentisering för hanterad identitet i Azure	Ska vara ett giltigt GUID
   agentBlueprintId	Din agents unika identifierare	Används i utvecklarportalen och administrationscentret
   agentBlueprintObjectId	Blueprintens Microsoft Entra ID
   messagingEndpoint	Meddelanderouting	Där Teams/Outlook skickar meddelanden till din agent
   agentBlueprintClientSecret	Autentiseringshemlighet	Ska finnas (värdet maskeras)
   resourceConsents	API-behörigheter	Ska innehålla resurser som Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API
   completed	Konfigurationsstatus	Ska vara true

   Kommentar

   Om du körde installationen som Agent-ID-administratör eller Agent-ID-utvecklare kan resourceConsents vara tom och completed vara false tills en global administratör har slutfört OAuth2-tillståndsbeviljanden enligt de nästa steg som skrivs ut av CLI:n.

2. Verifiera Azure-resurser i Azure Portal:

   Eller använda az resource listPowerShell-kommandot.

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

   Verifiera att följande resurser är skapade:

   • Resursgrupp:

     • Gå till Resursgrupper> och välj din resursgrupp
     • Verifiera att den innehåller din App Service Plan och webbapp

   • App Service-plan

     • Gå till App-tjänster>App Service-planer
     • Hitta din plan och verifiera att prisstegen matchar din konfigurations-SKU

   • Webbapp:

     • Gå till App Services>Web Apps
     • Hitta din webbapp och gå sedan till Inställningar>Identitet>Systemtilldelad
     • Kontrollera att statusen är På
     • Notera att objekt-ID (huvudidentitet) matchar managedIdentityPrincipalId

3. Verifiera Microsoft Entra-applikationer i Azure Portal:

   Gå till Azure Active Directory> > Appregistreringar> > Alla applikationer:

   • Sök efter din mäklarritning via agentBlueprintId

   • Öppna applikationen och välj API-behörigheter

   • Verifiera att behörigheter är beviljade och markeras med gröna bockar:

     • Microsoft Graph (delegerade och applikationsbehörigheter)
     • Meddelandrobot-API-behörigheter

   • Alla behörigheter visar "Beviljat för [Din hyresgäst]"

4. Verifiera att den genererade konfigurationsfilen skapats:

   Du bör ha en fil med namnet a365.generated.config.json som innehåller all konfigurationsdata.

   Använd PowerShell-kommandot Test-Path för att kontrollera att filen finns.

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

   Viktigt

   Spara båda filerna a365.config.json och a365.generated.config.json. Du behöver dessa värden för driftsättning och felsökning.

5. Verifiera att webbappen har hanterad identitet aktiverad:

   Använd kommandot az webapp identity show för att kontrollera om managed identity är aktiverat.

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

   Förväntad:

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

6. Verifiera att Agent blueprint är registrerad i Microsoft Entra:

   I Microsoft Entra administrationscenter, sök efter ditt agentBlueprintId eller sök efter namn.

   Verifiera det:

   ✅ Appregistrering och företagsapplikation visas
   ✅ På blueprinten för appregistrering visar fliken API-behörigheter alla behörigheter
   ✅ Status visar "Beviljat för [din hyresgäst]"

Mer information finns i:

• Problem med anpassade klientappar

Agentbehörigheter

Innan appar och agenter kan läsa eller skriva Microsoft 365-data (användare, e-post, filer, Teams, agenter och så vidare) måste du uttryckligen ge dem Microsoft Graph-behörigheter. Microsoft Graph-behörigheter är den auktoriseringsmodell som styr vilken data och vilka åtgärder en app eller tjänst kan komma åt via Microsoft Graph-API:er över Microsoft 365 och Microsoft Entra ID.

Läs mer: Översikt över Microsoft Graph-behörigheter

För att använda Graph-behörigheter för Agent 365-agentinstanser måste utvecklaren ange dem i agentens Blueprint. När en administratör aktiverar ritningen i Administrationscenter för Microsoft 365 granskar portalen ritningens Graph-behörigheter och uppmanar administratören att samtycka till dem.

För att förstå och validera hur grafbehörigheter möjliggör din agent kan du:

• Visa alla tillgängliga grafbehörigheter .
• Besök Graph Explorer för att prova frågor, granska svar och förstå behörigheter.
• Använd Microsoft 365 Agents Playground för att testa din agent lokalt innan distribution.

Tillämpa behörigheter på din blueprint

Använd a365 setup permissions custom för att tillämpa anpassade API-behörigheter direkt på din blueprint i Microsoft Entra.

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

För fullständig information om hur man konfigurerar och tar bort anpassade behörigheter, se setup permissions custom.

Nästa steg

Distribuera din agentkod till molnet:

Felsökning

Detta avsnitt beskriver vanliga problem vid konfigurering av agent blueprints.

Dessa problem uppstår ibland under registreringen:

• Otillräckliga behörigheter
• Azure CLI-autentisering saknas
• Resursen finns redan
• Administratörens godkännande har inte slutförts
• Konfigurationsfilen saknas eller är ogiltig
• Konfigurationen slutförs men resurserna skapas inte
• Agentmall är inte registrerad i Microsoft Entra
• API-behörigheter har inte tilldelats
• Hanterad identitet är inte aktiverad
• Uppsättningen tar för lång tid eller slutar svara
• Rensa en agent utan konfiguration
• Det går inte att skicka det första meddelandet i Teams

Otillräckliga behörigheter

Symptom: Otillräckliga behörigheter vid körning av a365 setupkommando.

Du behöver en av följande roller i din Microsoft Entra-tenant:

• Global administratör för
• Agent ID-utvecklare

Och behörighet som Azure-prenumerationsdeltagare eller ägare.

Lösning: Verifiera att du har nödvändiga behörigheter i Microsoft Entra.

• Gå till: Microsoft Entra administrationscenter> Din profil > Tilldelade roller
• Kontrollera åtkomst till Azure-prenumerationen med az account show PowerShell-kommandot

Azure CLI-autentisering saknas

Symptom: Installationen misslyckas med autentiseringsfel.

Lösning: Se till att du är ansluten till Azure och verifiera ditt konto och din prenumeration.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

Resursen finns redan

Symptom: Installationen misslyckas med Resource already exists fel för resursgrupp, App Service-plan eller webbapp.

Lösningar: Välj en av följande lösningar.

• Använd befintliga resurser

  Om resurser finns och du vill använda dem, se till att de matchar din konfiguration. Använd az resource listPowerShell-kommandot.

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

• Ta bort konflikterande resurser

  Ta bort resursgruppen eller byt namn på dina resurser i a365.config.json och kör om uppsättningen.

  Använd PowerShell-kommandot az group delete för att ta bort en resursgrupp.

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

• Använd cleanup-kommandot för att börja om från början

  Använd kommandot cleanup för att ta bort alla Agent 365-resurser, och använd sedan kommandot a365 setup all för att köra om uppsättningen.

  Varning!

  Att köra a365 cleanup är destruktivt.

  a365 cleanup
  a365 setup all
  

Administratörens godkännande har inte slutförts

Symptom: Du öppnade webbläsarfönster under installationen men stängde dem innan samtycket slutfördes, eller installationen slutfördes men OAuth2-behörighetsbeviljanden är ännu inte godkända.

Lösning: Välj utifrån din roll:

• Global administratör: Kör a365 setup all igen. CLI:n begär administratörssamtycke. Slutför samtycket i det webbläsarfönster som öppnas.

• Agent ID-administratör eller utvecklare: Du kan inte slutföra OAuth2-behörigheter direkt. Kör a365 setup all — setup-sammanfattningen visar nästa steg för en global administratör, inklusive en direktlänk eller samtyckes-URL för att slutföra tilldelningen av behörigheter. Dela dessa detaljer med din globala administratör.

Konfigurationsfilen saknas eller är ogiltig

Symptom: Setup misslyckas med "Konfiguration saknas" eller valideringsfel.

Lösning:

1. Kontrollera att a365.config.json-filen finns.
2. Om den saknas eller är ogiltig, skapa den manuellt eller använd a365 setup all --agent-name <name> (endast för agenter).

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

Konfigurationen slutförs men resurserna skapas inte

Symptom: Setup-kommandot lyckas men Azure-resurser har inte skapats.

Lösning:

1. Kontrollera skapade resurser genom att öppna a365.generated.config.json i din arbetskatalog.
2. Kontrollera att Azure-resurser finns genom att köra kommandotaz resource list.
3. Om resurser saknas, granska om det finns fel i setup-utdata och kör uppsättningen igen med a365 setup allkommandot.

# 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

Agentmall är inte registrerad i Microsoft Entra

Symptom: Installationen slutförs men du kan inte hitta agent blueprint i Microsoft Entra administrationscenter.

Lösning:

1. Hämta ett blueprint-ID från a365.generated.config.json.

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

2. Sök i Microsoft Entra administrationscenter:

   1. Gå till: Microsoft Entra administrationscenter..
   2. Navigera till Appregistreringar>Alla applikationer.
   3. Sök efter din agentBlueprintId.

3. Om det inte hittas, kör om installationen med kommandota365 setup all.

   a365 setup all
   

API-behörigheter har inte tilldelats

Symptom: Uppsättningen slutförs men behörigheterna visas som "Ej beviljade" i Microsoft Entra.

Lösning:

1. ÖppnaMicrosoft Entra administrationscenter..

2. Hitta din agent blueprint-appregistrering.

3. Gå till API-behörigheter.

4. Bevilja administratörsmedgivande:

   1. Välj Bevilja administratörsmedgivande för [din klientorganisation].
   2. Bekräfta åtgärden.

5. Kontrollera att alla behörigheter visar gröna bockar.

Hanterad identitet är inte aktiverad

Symptom: Webbappen finns, men hanterad identitet är inte aktiverad.

Lösning:

1. Kontrollera status för hanterad identitet genom att använda kommandotaz webapp identity show.
2. Om det inte är aktiverat, aktivera det manuellt genom att använda kommandotaz webapp identity assign.
3. Verifiera att det är aktiverat genom att använda kommandotaz webapp identity show.

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

Uppsättningen tar för lång tid eller slutar svara

Symptom: Setup-kommandot körs i mer än 10 minuter utan att slutföras.

Lösning:

1. Om du kör som Global Administratör, kontrollera om ett webbläsarfönster väntar på administratörssamtycke. Slutför samtyckesflödet för att avblockera installationen.

2. Om uppsättningen verkligen slutar svara, avbryt den (Ctrl+C) och kontrollera vilka resurser som har skapats.

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

3. Rensa och försök igen.

   a365 cleanup
   a365 setup all
   

Rensa en agent utan konfiguration

Symptom: Du har provisionerat en agent med a365 setup all --agent-name <name> och vill nu ta bort den, men saknar en a365.config.json-fil.

Lösning: Använd a365 cleanup --agent-name för att ta bort agenten utan en konfigurationsfil. CLI:n läser resurs-ID:n från den globalt genererade konfigurationen som skapades under Bootstrap-uppsättningen.

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

Om du inte längre har den globalt genererade konfigurationen (till exempel efter att ha installerat om CLI), använd a365 cleanup med en manuellt skapad minimal a365.config.json, eller ta bort resurser direkt via Azure Portal och Microsoft Entra administrationscenter.

Det går inte att skicka det första meddelandet i Teams

Symptom: Efter att en agentinstans har provisionerats kan den inte skicka ett meddelande till agentansvarig som ett välkomstmeddelande.

Lösning: [Chat.Create][perm-chatcreate]-behörigheten krävs för att skapa ett nytt chattobjekt. Om en en-till-en-chatt redan finns returnerar denna operation den befintliga chatten och skapar ingen ny.

• För att implementera, konfigurera blueprintens ärvbara behörigheter så att de inkluderar Chat.Create-scope.
• Konfigurera ett Teams-chattmeddelande att skickas när en agentinstans är provisionerad.
• Skapa en ny agentinstans från blueprinten och testa förstahandsmeddelandet.