Nastavení podrobného plánu agenta

Podrobný plán agenta definuje identitu, oprávnění a požadavky na infrastrukturu vašeho agenta. Vytvořte každou instanci agenta z tohoto podrobného plánu agenta.

Poznámka:

Nastavení agentního blueprintu je nutné pro umožnění funkcí Register, Work IQ a AI kolegy. Viz Začínáme s vývojem Agent 365, abyste pochopili, které funkce se vztahují na vašeho agenta.

Více informací o identitě Agent 365 naleznete v Agent 365 Identity.

Předpoklady

Dříve než začnete, se ujistěte, že splňujete následující předpoklady:

  1. CLI Agent 365 - Viz instalace CLI Agent 365.

  2. Požadovaná oprávnění:

    • Platný uživatel klienta s jednou z následujících rolí:
      • Globální správce
      • ID Agenta vývojáře
    • Přístup k předplatnému Azure s oprávněními k vytváření zdrojů

    Zpropitné

    Agenti (nikoli AI spoluhráči) nepotřebují konfigurační soubor. Použijte a365 setup all --agent-name <name> a CLI automaticky určí váš klient a klientskou aplikaci. Nastavení AI spoluhráče vyžaduje ručně vytvořené a365.config.json.

Vytvořit šablonu agenta

Použijte a365 setup příkaz k vytvoření Azure zdrojů a registraci vašeho podrobného plánu agenta. Podrobný plán definuje identitu vašeho agenta, jeho oprávnění a požadavky na infrastrukturu. Tento krok vytváří základ pro nasazení a provoz vašeho agenta v Azure.

Spuštění nastavení

Spuštění příkazu nastavení:

a365 setup -h

Příkaz má různé možnosti. Celé nastavení můžete dokončit jedním příkazem pomocí a365 setup all nebo zvolit podrobnější možnosti.

Poznámka:

Příkaz a365 setup all je standardně nastaven na režim agenta blueprintu. Pro nastavení AI spoluhráče místo toho použijte --aiteammate. Pro agenty M365 (Teams, Copilot) také přidejte --m365 pro automatickou registraci koncového bodu zasílání zpráv.

Nastavení agenta (výchozí):

# With a config file
a365 setup all

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

Nastavení agenta M365 (Teams/Copilot):

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

Nastavení AI spoluhráče:

a365 setup all --aiteammate

Celý proces nastavení provádí tyto operace:

  1. Vytváří Azure infrastrukturu (pokud ještě neexistuje):

    • Skupina prostředků
    • App Service plán se specifikovaným SKU
    • Azure Web App s povolenou spravovanou identitou

  2. Registruje blueprint agenta:

    • Vytvoří blueprint agenta v klientu Microsoft Entra
    • Vytváří registrace aplikací v Microsoft Entra
    • Konfiguruje identitu agenta s požadovanými oprávněními
    • Nastavuje managerApplications na blueprintu, což je nezbytné pro správu platformy

    Důležité

    Blueprinty musí mít managerApplications nastaveno, aby byly platformou přijaty. CLI nastavuje tuto hodnotu automaticky. Pokud existuje blueprint vytvořený před zavedením tohoto požadavku, odstraňte jej a spusťte a365 setup all znovu, nebo jej manuálně upravte pomocí Graph API.

  3. Konfigurace oprávnění API:

    • Nastavuje rozsahy oprávnění Microsoft Graph API
    • Konfiguruje oprávnění pro Messaging robot API
    • Přiřazuje dědičná oprávnění instancím agentů

  4. Aktualizuje konfigurační soubory:

    • Uloží vygenerovaná ID a koncové body do nového souboru ve vašem pracovním adresáři s názvem a365.generated.config.json
    • Ukládá informace o spravované identitě a zdrojích

Poznámka:

Nastavení obvykle trvá 3–5 minut a automaticky ukládá konfiguraci do a365.generated.config.json. Pokud spustíte CLI jako globální administrátor, může se otevřít okno prohlížeče pro administrátorský souhlas - dokončete proces souhlasu, abyste mohli pokračovat. Pokud běžíte jako Agent ID Developer, neotevře se žádné okno prohlížeče; CLI vygeneruje URL pro souhlas, které může globální administrátor použít k dokončení procesu souhlasu později.

Nastavení pomocí Agent ID Developer

Pokud pracujete jako Agent ID Developer (ne globální správce), a365 setup all většinu kroků dokončí automaticky, ale udělení oprávnění OAuth2 vyžaduje samostatný krok globálního správce.

Které kroky jsou dokončeny automaticky:

  • Infrastruktura Azure (skupina zdrojů, Plán služby App Service, Webová aplikace)
  • Registrace agent blueprintu
  • Dědičná oprávnění pro instance agentů

Jaké kroky musí provést globální administrátor:

  • Udělení delegovaných oprávnění OAuth2 (AllPrincipalssouhlas) pro Microsoft Graph, Agent 365 Tools, Messaging robot API, Observability API a Power Platform API

Jak dokončit nastavení pomocí účtu bez administrátorských práv:

Krok Kdo Akce
1 Developer Spusťte a365 setup all. CLI dokončí všechny možné kroky a vytiskne další kroky, včetně URL souhlasu pro globální administrátora k otevření.
2 Developer Sdílejte souhlasnou URL z výstupu CLI se svým globálním správcem.
3 Globální správce Otevřete souhlasnou URL v prohlížeči přihlášeném jako Globální správce a udělte požadovaná oprávnění.

Spouštění příkazů:

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

Sdílejte další kroky zobrazené ve výstupu CLI se svým globálním správcem. Mohou otevřít poskytnutý odkaz nebo souhlasnou URL pro dokončení grantů OAuth2.

Ověřte nastavení

Jakmile nastavení skončí, zobrazí se shrnutí všech dokončených kroků. Ověřte vytvořené zdroje:

  1. Ověřte generovanou konfiguraci:

    Otevřete a365.generated.config.json ve svém pracovním adresáři. Nebo použijte PowerShell:

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

    Očekávaný výstup zahrnuje tyto klíčové hodnoty:

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

    Klíčová pole k ověření:

    Pole Účel Co zkontrolovat
    managedIdentityPrincipalId Ověřování pomocí spravované identity Azure Měl by být platný identifikátor GUID
    agentBlueprintId Jedinečný identifikátor vašeho agenta Používá se v Developer Portalu a centru pro správu
    agentBlueprintObjectId Microsoft Entra ID Blueprintu
    messagingEndpoint Směrování zpráv Kde Teams/Outlook posílají zprávy vašemu agentovi
    agentBlueprintClientSecret Tajný kód ověřování Mělo by existovat (hodnota je maskovaná)
    resourceConsents Oprávnění rozhraní API Mělo by obsahovat zdroje jako Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API
    completed Stav nastavení Mělo by být true

    Poznámka:

    Pokud jste provedli nastavení jako správce ID agenta nebo vývojář ID agenta, resourceConsents může být prázdné a completed může být stejné jako false, dokud globální správce nedokončí udělení oprávnění OAuth2 pomocí dalších kroků zobrazených v CLI.

  2. Ověřte prostředky Azure v Azure Portal:

    Nebo použijte az resource listpříkaz PowerShell.

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

    Ověřte, že jsou vytvořeny následující zdroje:

    • Skupina zdrojů:

      • Přejděte na Skupiny prostředků> Vyberte svou skupinu prostředků
      • Ověřte, že obsahuje váš App Service Plan a webovou aplikaci

    • Plán služby App Service:

      • Přejděte na App Services>Plány App Services
      • Najděte svůj plán a ověřte, že cenová úroveň odpovídá vašemu konfiguračnímu SKU

    • Webová aplikace:

      • Přejděte na App Services>Web Apps
      • Najděte svou webovou aplikaci a poté přejděte do Nastavení>Identita>Systémově přiřazené
      • Ověřte, že stav je Zapnuto
      • Zkontrolujte, že ID objektu (principal) odpovídá managedIdentityPrincipalId

  3. Ověřte aplikace Microsoft Entra v Azure Portal:

    Přejděte na Azure Active Directory>Registrace aplikací>Všechny aplikace:

    • Vyhledejte blueprint agenta podle agentBlueprintId

    • Otevřete aplikaci a vyberte API oprávnění

    • Ověřte, že oprávnění byla udělena a označena zelenými zatržítky:

      • Microsoft Graph (delegovaná a aplikační oprávnění)
      • Oprávnění API pro robota zasílání zpráv

    • Všechna oprávnění zobrazují "Uděleno pro [Vašeho klienta]"

  4. Ověřte, že byl vytvořen generovaný konfigurační soubor:

    Měli byste mít soubor s názvem a365.generated.config.json, který obsahuje všechna konfigurační data.

    Pomocí příkazu Test-Path v PowerShellu ověřte, že existuje.

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

    Důležité

    Uložte oba soubory: a365.config.json a a365.generated.config.json. Tyto hodnoty potřebujete pro nasazení a řešení problémů.

  5. Ověřte, zda má webová aplikace povolenou spravovanou identitu:

    Použijte az webapp identity show příkaz k ověření, zda je spravovaná identita povolená.

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

    Očekáváno:

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

  6. Ověřte, že je šablona agenta registrována v Microsoft Entra:

    V Centru pro správu Microsoft Entra vyhledejte své agentBlueprintId nebo vyhledávejte podle jména.

    Ověřte, že:

    ✅ Zobrazí se registrace aplikace a podniková aplikace
    ✅ Na blueprintu registrace aplikace záložka Oprávnění API zobrazuje všechna oprávnění
    ✅ Stav zobrazuje „Schváleno pro [váš klient]“

Další nápovědu naleznete zde:

Oprávnění agenta

Aby mohly aplikace a agenti číst nebo zapisovat data Microsoft 365 (uživatele, poštu, soubory, Teams, agenty atd.), musíte jim explicitně udělit oprávnění Microsoft Graph. Oprávnění Microsoft Graph představují autorizační model, který určuje, k jakým datům a akcím může aplikace nebo služba přistupovat prostřednictvím Microsoft Graph API napříč Microsoft 365 a Microsoft Entra ID.

Více informací: Přehled oprávnění Microsoft Graph

Aby bylo možné použít oprávnění Microsoft Graph pro instance agentů Agent 365, musí je vývojář deklarovat v blueprintu agenta. Když správce aktivuje blueprint v Centru správy Microsoft 365, portál přezkoumá Graph oprávnění blueprintu a vyzve správce k udělení souhlasu s nimi.

Abyste pochopili a ověřili, jak oprávnění Microsoft Graph umožňují využití vašeho agenta, můžete:

Aplikujte oprávnění na svůj plán

Použijte a365 setup permissions custom k aplikaci vlastních API oprávnění přímo do vašeho blueprintu v 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

Podrobné informace o konfiguraci a odebrání vlastních oprávnění najdete v setup permissions custom.

Další kroky

Nasaďte svůj kód agenta do cloudu:

Azure

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

Publikujte agenta do centra správy Microsoft

Řešení problému

Tato sekce popisuje běžné problémy při nastavování šablon agentů.

Zpropitné

Průvodce odstraňováním problémů Agent 365 obsahuje doporučení k odstraňování problémů na vysoké úrovni, osvědčené postupy a odkazy na obsah o řešení problémů pro každou část životního cyklu vývoje Agent 365.

Tyto problémy se někdy vyskytují během registrace:

Chyba Nedostatečná oprávnění

Příznak: Chyba nedostatečných oprávnění při provádění a365 setuppříkazu.

Ve vašem klientovi Microsoft Entra potřebujete jednu z následujících rolí:

  • Globální správce
  • ID Agenta vývojáře

A přístup typu přispěvatel nebo vlastník k předplatnému Azure.

Řešení: Ověřte, že máte potřebná oprávnění v Microsoft Entra.

Poznámka:

Pokud máte roli správce ID agenta nebo vývojáře ID agenta (nikoli globální administrátor), a365 setup all bude úspěšný, ale přeskočí udělení oprávnění OAuth2. Po dokončení nastavení CLI vypíše další kroky, které musí globální administrátor provést k dokončení zbývajícího udělení oprávnění. Tento postup je očekáván u organizací, kde vývojář agenta a Globální administrátor jsou různými osobami.

Chybí ověření Azure CLI

Příznak: Nastavení selže kvůli chybám při autentizaci.

Řešení: Ujistěte se, že jste připojeni k Azure a ověřte svůj účet a předplatné.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

Prostředek už existuje.

Příznak: Nastavení selže s Resource already exists chybou pro skupinu zdrojů, App Service plán nebo webovou aplikaci.

Řešení: Vyberte jedno z následujících řešení.

  • Použít existující prostředky

    Pokud existují zdroje a chcete je využít, ujistěte se, že odpovídají vaší konfiguraci. Použijte az resource listpříkaz PowerShell.

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

  • Smažte konfliktní zdroje

    Smažte skupinu zdrojů nebo přejmenujte zdroje v a365.config.json a znovu spusťte nastavení.

    Použijte az group delete příkaz PowerShell k odstranění skupiny zdrojů.

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

  • Použijte příkaz cleanup pro začít znovu

    Použijte cleanup příkaz k odstranění všech zdrojů Agent 365 a pak příkaz a365 setup all pro opětovné spuštění nastavení.

    Upozornění

    Spuštění a365 cleanup je destruktivní.

    a365 cleanup
a365 setup all

Příznak: Během nastavení byly otevřeny okna prohlížeče, ale byly zavřeny před dokončením udělení souhlasu, nebo nastavení bylo dokončeno, avšak povolení OAuth2 stále čekají na schválení.

Řešení: Vyberte podle své role:

  • Globální administrátor: Spusťte a365 setup all znovu. CLI vyzve k udělení souhlasu administrátora. Dokončete proces souhlasu v okně prohlížeče, které se objeví.

  • Správce ID agenta nebo vývojář: Nelze přímo dokončit granty OAuth2. Spusťte a365 setup all — shrnutí nastavení zobrazí další kroky pro Globálního administrátora, včetně přímého odkazu nebo souhlasové URL k dokončení udělení oprávnění. Sdílejte tyto podrobnosti se svým globálním administrátorem.

Konfigurační soubory chybí nebo jsou neplatné

Symptom: Nastavení selže s chybou "Konfigurace nenalezena" nebo s chybami ověření.

Řešení:

  1. Ověřte, že soubor a365.config.json existuje.
  2. Pokud chybí nebo je neplatný, vytvořte ho ručně nebo použijte a365 setup all --agent-name <name> (pouze pro agenty).
# Verify a365.config.json exists
Test-Path a365.config.json

Nastavení je dokončeno, ale zdroje nejsou vytvořeny

Symptom: Příkaz pro nastavení byl úspěšně proveden, ale Azure prostředky neexistují.

Řešení:

  1. Zkontrolujte vytvořené prostředky otevřením a365.generated.config.json ve svém pracovním adresáři.
  2. Ověřte existenci prostředků Azure pomocí příkazu az resource list.
  3. Pokud prostředky chybí, zkontrolujte chyby ve výstupu nastavení a znovu proveďte nastavení pomocí příkazu 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

Šablona agenta není registrována v Microsoft Entra

Symptom: Nastavení je dokončeno, ale blueprint agenta není k nalezení v Centrum pro správu Microsoft Entra.

Řešení:

  1. Získání ID blueprintu z a365.generated.config.json.

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

  2. Vyhledejte v Centru pro správu Microsoft Entra:

    1. Přejděte na Centrum pro správu Microsoft Entra.
    2. Přejděte na Registrace aplikací>Všechny aplikace.
    3. Vyhledejte agentBlueprintId.

  3. Pokud jej nenajdete, spusťte znovu nastavení pomocí a365 setup all příkazu.

    a365 setup all

Oprávnění API nebyla udělena

Symptom: Nastavení je dokončeno, ale oprávnění se zobrazují jako "Neuděleno" v Microsoft Entra.

Řešení:

  1. Otevřete Centrum pro správu Microsoft Entra.

  2. Najděte registraci aplikace blueprintu agenta ve Microsoft Entra.

  3. Přejděte na Oprávnění API.

  4. Udělit souhlas správce:

    1. Vyberte Udělit souhlas správce pro [váš klient].
    2. Potvrďte akci.

  5. Ověřte, že všechna oprávnění jsou označena zeleným zaškrtnutím.

Spravovaná identita není povolena

Symptom: Webová aplikace existuje, ale spravovaná identita není povolena.

Řešení:

  1. Zkontrolujte stav spravované identity pomocí az webapp identity show příkazu.
  2. Pokud není povolena, povolte ji ručně pomocí příkazu az webapp identity assign.
  3. Ověřte, že je povolený, pomocí příkazu az 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>

Nastavení trvá příliš dlouho nebo přestane odpovídat

Příznak: Nastavovací příkaz běží déle než 10 minut a není dokončen.

Řešení:

  1. Pokud spouštíte jako globální správce, zkontrolujte, zda okno prohlížeče čeká na souhlas správce. Dokončete proces souhlasu, abyste odblokovali nastavení.

  2. Pokud nastavení skutečně přestane reagovat, přerušte jej (Ctrl+C) a zkontrolujte, co bylo vytvořeno.

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

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

  3. Vyčistěte a zkuste znovu.

    a365 cleanup
a365 setup all

Vyčištění agenta bez konfigurace

Příznak: Nastavili jste agenta pomocí a365 setup all --agent-name <name> a nyní ho chcete odstranit, ale nemáte soubor a365.config.json.

Řešení: Použijte a365 cleanup --agent-name k odstranění agenta bez konfiguračního souboru. CLI čte ID zdrojů z globální generované konfigurace, která byla napsána při nastavení bootstrapu.

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

Zpropitné

Pokud se příkaz při autentizaci zastaví, automaticky přejde na tok kódu zařízení. Pro dokončení přihlášení postupujte podle pokynů zobrazených v terminálu.

Pokud už nemáte globální generovanou konfiguraci (například po přeinstalaci CLI), použijte a365 cleanup s ručně vytvořeným minimálním a365.config.json, nebo odstraňte zdroje přímo prostřednictvím Azure Portal a Centrum pro správu Microsoft Entra.

Nelze odeslat první zprávu v Teams

Příznak: Po nasazení instance agenta není možné odeslat zprávu správci agenta jako uvítací zprávu.

Řešení: K vytvoření nového chatu je potřeba oprávnění [Chat.Create][perm-chatcreate]. Pokud už existuje osobní chat, tato operace vrátí stávající chat a nevytvoří nový.

  • K implementaci, konfigurujte dědičná oprávnění blueprintu tak, aby zahrnovala Chat.Createscope.
  • Nakonfigurujte zprávu v Teams tak, aby se odeslala, jakmile bude instance agenta nasazena.
  • Vytvořte novou instanci agenta na základě blueprintu a otestujte zprávu při prvním spuštění.
  • Last updated on