Sett opp agent blueprint

Agentblåkopi definerer agentens identitet, tillatelser og infrastrukturkrav. Opprett hver agentforekomst fra denne agentblåkopien.

Notat

Oppsett av en agentblåkopi er nødvendig for å aktivere funksjonene Registrer, Work IQ og KI-lagkamerat. Se Kom i gang med Agent 365-utvikling for å forstå hvilke funksjoner som gjelder for din agent.

For mer informasjon om Agent 365-identitet kan du se Agent 365-identitet.

Forutsetning

Før du begynner, må du kontrollere at du har følgende forhåndskrav:

  1. Agent 365 CLI – Se Agent 365 CLI-installasjon.

  2. Nødvendige API-tillatelser:

    • Gyldig leietakerbruker med en av følgende roller:
      • Global administrator
      • Agent-ID-utvikler
    • Tilgang til et Azure-abonnement med tillatelser for å opprette ressurser

    Tips

    Agenter (ikke KI-lagkamerater) trenger ikke en konfigurasjonsfil. Bruk a365 setup all --agent-name <name>, og CLI-en løser leietakeren og klientappen din automatisk. KI-lagkameratoppsett krever en manuelt opprettet a365.config.json.

Opprett agentblåkopi

Bruk kommandoen a365 setup til å opprette Azure-ressurser og registrere agentblåkopien. Blåkopien definerer agentens identitet, tillatelser og infrastrukturkrav. Dette trinnet danner fundamentet for distribusjon og drift av agenten din i Azure.

Kjør -oppsett

Kjør oppsettkommandoen:

a365 setup -h

Kommandoen har flere alternativer. Du kan fullføre hele oppsettet i én enkelt kommando ved å bruke a365 setup all eller velge mer detaljerte alternativer.

Notat

Som standard settes a365 setup all til blåkopiagentmodus. For å sette opp en KI-lagkameratagent i stedet må du bestå --aiteammate. For M365-agenter (Teams, Copilot) må du også angi --m365 for å registrere meldingsendepunktet automatisk.

Agentoppsett (standard):

# With a config file
a365 setup all

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

M365-agentoppsett (Teams/Copilot):

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

KI-lagkameratoppsett:

a365 setup all --aiteammate

Hele oppsettsprosessen utfører disse operasjonene:

  1. Oppretter Azure-infrastruktur (hvis den ikke allerede eksisterer):

    • Ressursgruppe
    • Apptjenesteabonnement med spesifisert SKU
    • Azure Nettapp med administrert identitet aktivert

  2. Registrerer agentblåkopi:

    • Oppretter agentblåkopien i Microsoft Entra-leieren
    • Oppretter Microsoft Entra-programregistreringer
    • Konfigurerer agentidentiteten med nødvendige tillatelser
    • Angi managerApplications på blåkopien, noe som kreves for plattformadministrasjon

    Viktig!

    Blåkopier må være managerApplications satt til å bli akseptert av plattformen. CLI setter dette automatisk. Hvis du har en eksisterende blåkopi laget før dette kravet ble innført, sletter du den og kjører a365 setup all på nytt, eller oppdaterer den manuelt via Graph API.

  3. Konfigurere API-tillatelser:

    • Setter opp Microsoft Graph-API-omfang
    • Konfigurerer API-tillatelser for meldingsrobot
    • Anvender arvelige tillatelser for agentforekomster

  4. Oppdaterer konfigurasjonsfiler:

    • Lagrer genererte ID-er og endepunkter i en ny fil i arbeidsmappen din med navnet a365.generated.config.json
    • Lagrer informasjon om administrert identitet og ressurser

Notat

Oppsettet tar vanligvis 3–5 minutter og lagrer automatisk konfigurasjon til a365.generated.config.json. Hvis du kjører som Global administrator, kan CLI-en åpne et nettleservindu for administratorgodkjenning – fullfør godkjenningsflyten for å fortsette. Hvis du kjører som agent-ID-utvikler, åpnes ikke noe nettleservindu. CLI-en genererer samtykkenettadresser som en global administrator kan gjennomføre senere.

Oppsett ved å bruke agent-ID-utvikler

Hvis du kjører som agent-ID-utvikler (ikke Global administrator), a365 setup all utfører de fleste trinn automatisk, men OAuth2-tillatelsesgodkjenninger må utføres separat av en Global administrator.

Trinn som utføres automatisk:

  • Azure-infrastruktur (ressursgruppe, Apptjenesteabonnement, Nettapp)
  • Registrering av agentblåkopi
  • Arvede tillatelser for agentforekomster

Trinn som krever en global administrator:

  • OAuth2-delegerte tillatelsesgodkjenninger (AllPrincipals-samtykke) for Microsoft Graph, Agent 365 Tools, API for meldingsrobot, observerbarhets-API og Power Platform-API

Slik fullfører du oppsettet ved å bruke en ikke-administratorkonto:

Trinn Hvem Handling
1 Utvikler Kjør a365 setup all. CLI-en fullfører alle trinn den kan og skriver ut de neste trinn, inkludert en samtykkenettadresse som en global administrator kan åpne.
2 Utvikler Del samtykkenettadressen fra CLI-resultatet med din global administrator.
3 Global administrator Åpne samtykkenettadressen i en nettleser som er logget på som Global administrator og gi de forespurte tillatelsene.

Kjør kommandoene:

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

Del de neste trinnene som vises av CLI med Global administrator. De kan åpne den oppgitte koblingen eller samtykkenettadresse for å fullføre OAuth2-tilskuddene.

Verifiser oppsettet

Når oppsettet er ferdig, ser du et sammendrag som viser alle fullførte trinn. Verifiser de opprettede ressursene:

  1. Verifiser generert konfigurasjon:

    Åpne a365.generated.config.json i arbeidskatalogen. Eller bruk PowerShell:

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

    Forventet utdata inkluderer disse kritiske verdiene:

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

    Nøkkelfelter som skal verifiseres:

    Felt Formål Hva du bør sjekke
    managedIdentityPrincipalId Azure-administrert identitetsautentisering Må være en gyldig GUID
    agentBlueprintId Agentens unike identifikator Brukt i utviklerportalen og administrasjonssenteret
    agentBlueprintObjectId Blåkopiens Microsoft Entra ID
    messagingEndpoint Meldingsruting Hvor Teams/Outlook sender meldinger til agenten din
    agentBlueprintClientSecret Godkjenningshemmelighet Bør eksistere (verdien er maskert)
    resourceConsents API-tillatelser Bør inneholde ressurser som Microsoft Graph, Agent 365 Tools, API for meldingsrobot, observerbarhets-API
    completed Status for oppsett Skal være true

    Notat

    Hvis du utførte oppsettet som agent ID-administrator eller agent-ID-utvikler, kan resourceConsents være tom og completed kan være false inntil en global administrator har fullført OAuth2-tillatelsestildelingene ved å følge de neste trinn som vises av CLI.

  2. Verifiser Azure-ressurser i Azure Portal:

    Eller bruk az resource list PowerShell-kommandoen.

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

    Verifiser at følgende ressurser er opprettet:

    • Ressursgruppe:

      • Gå til Ressursgrupper>, velg ressursgruppen
      • Verifiser at den inneholder Apptjenesteabonnement og Nettapp

    • Apptjenesteabonnement:

      • Gå til App Services>App Service Plans
      • Finn planen din og verifiser at prisnivået samsvarer med konfigurasjons-SKU-en

    • Nettapp:

      • Gå til App Services>Web Apps
      • Finn nettappen din, og gå deretter til Innstillinger>Identitet>Systemtildelt
      • Bekreft at status er På
      • Merk at objekt-ID-en (sikkerhetskontohaver) samsvarer med managedIdentityPrincipalId

  3. Bekreft Microsoft Entra-programmer i Azure Portal:

    Gå til Azure Active Directory>Appregistreringer>Alle programmer:

    • Søk etter agentblåkopien ved agentBlueprintId

    • Åpne programmet og velg API-tillatelser

    • Verifiser at tillatelser er gitt med grønne avkrysningsmerker:

      • Microsoft Graph (delegerte tillatelser og programtillatelser)
      • API-tillatelser for meldingsrobot

    • Alle tillatelser viser Gitt til [leietaker]

  4. Verifiser at den genererte konfigurasjonsfilen er opprettet:

    Du skal ha en fil med navnet a365.generated.config.json som inneholder alle konfigurasjonsdata.

    Bruk PowerShell-kommandoen Test-Path for å kontrollere at filen finnes.

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

    Viktig!

    Lagre begge a365.config.json- og a365.generated.config.json-filene. Du trenger disse verdiene for utrulling og feilsøking.

  5. Verifiser at administrert identitet er aktivert for nettappen:

    Bruk az webapp identity showkommandoen til å sjekke om administrert identitet er aktivert.

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

    Forventet:

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

  6. Verifiser at agentblåkopien er registrert i Microsoft Entra:

    I administrasjonssenteret for Microsoft Entra søker du etter agentBlueprintId eller søker etter navn.

    Verifiser at:

    ✅ Appregistrering og bedriftsprogram vises
    ✅ På blåkopien for appregistrering viser fanen API-tillatelser alle tillatelser
    ✅ Status viser Tildelt til [leietakeren]

Hvis du vil ha mer hjelp, kan du se:

Agenttillatelser

Før apper og agenter kan lese eller skrive Microsoft 365-data (brukere, e-post, filer, Teams, agenter osv.), må du eksplisitt gi dem Microsoft Graph-tillatelser. Microsoft Graph-tillatelser er autorisasjonsmodellen som styrer hvilke data og handlinger en app eller tjeneste kan få tilgang til gjennom Microsoft Graph-API-er på tvers av Microsoft 365 og Microsoft Entra ID.

Finn ut mer: Oversikt over Microsoft Graph-tillatelser

For å bruke Graph-tillatelser for agentforekomster i Agent 365, må utvikleren erklære dem i agentblåkopien. Når en administrator aktiverer blåkopien i administrasjonssenteret for Microsoft 365, gjennomgår portalen blåkopiens Graph-tillatelser og ber administratoren om å gi samtykke til dem.

For å forstå og verifisere hvordan Graph-tillatelser aktiverer agenten kan du:

Tildel tillatelser til blåkopien

Bruk a365 setup permissions custom til å tildele tilpassede API-tillatelser direkte i blåkopien 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

For utfyllende informasjon om konfigurering og fjerning av egendefinerte tillatelser kan du se setup permissions custom.

Neste trinn

Distribuer agentkoden din til skyen:

Azure

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

Publiser agenten til administrasjonssenteret for Microsoft

Feilsøking

Denne delen beskriver vanlige problemer ved oppsett av agentblåkopier.

Tips

Feilsøkingsveiledning for Agent 365 inneholder anbefalinger på høyt nivå for feilsøking, anbefalte fremgangsmåter og koblinger til feilsøkingsinnhold for hver fase i utviklingssyklusen i Agent 365.

Disse problemene oppstår noen ganger under registreringen:

Feilen Utilstrekkelige tillatelser

Symptom: Feil med utilstrekkelige tillatelser under a365 setup-kommandoutførelse.

Du må ha en av følgende roller i Microsoft Entra-leietakeren:

  • Global administrator
  • Agent-ID-utvikler

Og tilgang til Azure-abonnementsbidragsytere eller -eiere.

Løsning: Kontroller at du har nødvendige tillatelser i Microsoft Entra.

Notat

Hvis du har rollen Agent-ID-administrator eller Agent-ID-utvikler (ikke Global administrator), lykkes fortsatt a365 setup all, men hopper over OAuth2-tillatelser. Etter at oppsettet er fullført, skriver CLI ut neste steg for at en global administrator skal fullføre de resterende tilskuddene. Denne arbeidsflyten forventes for organisasjoner der agentutvikleren og den globale administratoren er forskjellige personer.

Manglende Azure CLI-autentisering

Symptom: Oppsettet feiler med autentiseringsfeil.

Løsning: Sørg for at du er koblet til Azure, og verifiser kontoen og abonnementet ditt.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

Ressursen finnes allerede

Symptom: Oppsettet feiler med Resource already exists-feil for ressursgruppe, App Service-plan eller nettapp.

Løsninger: Velg en av følgende løsninger.

  • Bruk eksisterende ressurser

    Hvis ressursene finnes og du ønsker å bruke dem, må du sørge for at de stemmer overens med konfigurasjonen din. Bruk az resource list PowerShell-kommandoen.

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

  • Slett motstridende ressurser

    Slett ressursgruppen eller endre navn på ressursene i a365.config.json, og kjør oppsettet på nytt.

    Bruk az group delete PowerShell-kommandoen for å slette en ressursgruppe.

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

  • Bruk oppryddingskommandoen for å starte på nytt

    Bruk cleanup-kommandoen til å fjerne alle Agent 365-ressurser, og bruk deretter a365 setup all-kommandoen for å kjøre oppsettet på nytt.

    Advarsel!

    Å kjøre a365 cleanup er destruktivt.

    a365 cleanup
a365 setup all

Symptom: Du åpnet nettleservinduer under oppsettet, men lukket dem uten å fullføre samtykke, eller oppsettet er fullført, men OAuth2-tillatelsene mangler fortsatt.

Løsning: Velg ut fra din rolle:

  • Global administrator: Kjør a365 setup all igjen. CLI-en ber om administratorsamtykke. Fullfør samtykkeflyten i nettleservinduet som vises.

  • Agent-ID-administrator eller -utvikler: Du kan ikke fullføre OAuth2-tillatelser direkte. Kjør a365 setup all – oppsettsoppsummeringen skriver ut de neste trinnene for en global administrator, inkludert en direkte kobling eller samtykkenettadresse for å fullføre tillatelsene. Gi disse detaljene til global administrator.

Konfigurasjonsfiler mangler eller er ugyldig

Symptom: Oppsettet feiler med Finner ikke konfigurasjon eller valideringsfeil.

Løsning:

  1. Verifiser at a365.config.json-filen eksisterer.
  2. Hvis den mangler eller er ugyldig, oppretter du den manuelt eller bruk a365 setup all --agent-name <name> (bare for agenter).
# Verify a365.config.json exists
Test-Path a365.config.json

Oppsettet fullføres, men ressursene blir ikke opprettet

Symptom: Oppsettkommandoen lykkes, men Azure-ressurser eksisterer ikke.

Løsning:

  1. Kontroller opprettede ressurser ved å åpne a365.generated.config.json i arbeidskatalogen din.
  2. Kontroller at Azure-ressurser finnes ved å bruke az resource list-kommandoen.
  3. Hvis ressurser mangler, må du se etter feil i oppsettet og kjøre oppsettet på nytt ved å bruke a365 setup all-kommandoen.
# 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

Agentblåkopi er ikke registrert i Microsoft Entra

Symptom: Oppsettet fullføres, men du finner ikke agentblåkopi i administrasjonssenteret for Microsoft Entra.

Løsning:

  1. Hent blåkopi-ID fra a365.generated.config.json.

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

  2. Søk i administrasjonssenteret for Microsoft Entra:

    1. Gå til: Administrasjonssenter for Microsoft Entra.
    2. Naviger til Appregistreringer>Alle programmer.
    3. Søk etter appen agentBlueprintId.

  3. Hvis den ikke finnes, kjører du oppsettet på nytt ved å bruke a365 setup all-kommandoen.

    a365 setup all

API-tillatelser ikke gitt

Symptom: Oppsettet fullføres, men tillatelsene vises som Ikke gitt i Microsoft Entra.

Løsning:

  1. Åpne Administrasjonssenter for Microsoft Entra.

  2. Finn agentblåkopiappregistreringen.

  3. Gå til API-tillatelser.

  4. Gi administratortillatelse:

    1. Velg Gi administratorsamtykke for [leieren].
    2. Bekreft handlingen.

  5. Kontroller at alle tillatelser viser grønne haker.

Administrert identitet ikke aktivert

Symptom: Nettappen finnes, men administrert identitet er ikke aktivert.

Løsning:

  1. Sjekk status for administrert identitet ved å bruke az webapp identity show-kommandoen.
  2. Hvis det ikke er aktivert, aktiverer du det manuelt ved å bruke az webapp identity assign-kommandoen.
  3. Verifiser at det er aktivert ved å bruke az webapp identity show-kommandoen.
# 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>

Oppsettet tar for lang tid eller slutter å svare

Symptom: Oppsettskommandoen kjører i mer enn 10 minutter uten å avsluttes.

Løsning:

  1. Hvis du er logget inn som Global administrator, sjekker du om et nettleservindu venter på administratorsamtykke. Fullfør samtykkeflyten for å oppheve blokkeringen.

  2. Hvis oppsettet virkelig slutter å svare, avbryter du det (Ctrl+C) og ser hva som ble opprettet.

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

# Check Azure resources
az resource list --resource-group <your-resource-group>

  3. Rydd opp og prøv på nytt.

    a365 cleanup
a365 setup all

Rydd opp i en konfigurasjonsfri agent

Symptom: Du har opprettet en agent med a365 setup all --agent-name <name> og ønsker nå å fjerne den, men du har ikke en a365.config.json-fil.

Løsning: Bruk a365 cleanup --agent-name til å fjerne agenten uten konfigurasjonsfil. CLI-en leser ressurs-ID.er fra den globalt genererte konfigurasjonsfilen som ble skrevet under Bootstrap-oppsettet.

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

Tips

Hvis kommandoen stopper ved autentisering, faller den automatisk tilbake til enhetskodeflyten. Følg instruksjonene som vises i terminalen for å fullføre påloggingen.

Hvis du ikke lenger har den globale genererte konfigurasjonen (f.eks. etter at du har reinstallert CLI-en), bruker du a365 cleanup med en manuelt opprettet minimal a365.config.json eller fjerner ressurser direkte via Azure Portal og administrasjonssenteret for Microsoft Entra.

Kan ikke sende første melding i Teams

Symptom: Etter at en agentforekomst er opprettet, kan den ikke sende en melding til agentadministratoren som velkomstmelding.

Løsning: [Chat.Create][perm-chatcreate]-tillatelsen er nødvendig for å opprette et nytt nettpratobjekt. Hvis det allerede finnes en én-til-én-nettprat, returnerer denne operasjonen den eksisterende nettpraten og oppretter ikke en ny.

  • For å implementere dette konfigurerer du blåkopiens arvbare tillatelser slik at de inkluderer Chat.Create-omfanget.
  • Konfigurer en Teams-nettpratmelding som skal sendes når en agentforekomst er opprettet.
  • Opprett en ny agentforekomst fra blåkopien og test førstegangsmeldingen.
  • Last updated on