Konfiguracja konspektu agenta

Szablon agenta definiuje tożsamość, uprawnienia i wymagania infrastrukturalne agenta. Stwórz każdą instancję agenta na podstawie tego szablonu agenta.

Notatka

Konfiguracja szablonu agenta jest wymagana, aby umożliwić funkcje Register, Work IQ oraz AI teammate. Zobacz Rozpocznij rozwój Agent 365, aby zrozumieć, które możliwości mają zastosowanie Twojego agenta.

Więcej informacji o tożsamości Agenta 365 znajdziesz w sekcji Tożsamość Agent 365.

Wymagania wstępne

Przed rozpoczęciem należy się upewnić, że są spełnione następujące wymagania wstępne:

  1. Agent 365 CLI – patrz instalacja Agent 365 CLI.

  2. Wymagane uprawnienia:

    • Uprawniony użytkownik dzierżawy z jedną z poniższych ról:
      • Globalny administrator usługi
      • Agent ID Developer
    • Dostęp do subskrypcji Azure z uprawnieniami do tworzenia zasobów

    Wskazówka

    Agenty (nie AI teammates) nie potrzebują pliku konfiguracyjnego. Użyj a365 setup all --agent-name <name>, a CLI automatycznie wykryje Twój tenant i aplikację kliencką. Konfiguracja AI teammate wymaga ręcznie utworzonego a365.config.json.

Utwórz blueprint agenta

Użyj polecenia a365 setup, aby utworzyć zasoby Azure i zarejestrować swój szablon agenta. Blueprint definiuje tożsamość agenta, jego uprawnienia oraz wymagania dotyczące infrastruktury. Ten krok stanowi podstawę do wdrożenia i uruchomienia agenta w Azure.

Uruchom setup

Uruchom polecenie instalacyjne:

a365 setup -h

Polecenie ma różne opcje. Całą konfigurację możesz wykonać jednym poleceniem (a365 setup all) lub wybrać bardziej szczegółowe opcje.

Notatka

a365 setup all domyślnie działa w trybie agenta blueprint. Aby skonfigurować agenta AI teammate zamiast tego, przekaż --aiteammate. Dla agentów M365 (Teams, Copilot) należy również przekazać --m365, aby automatycznie zarejestrować punkt końcowy wiadomości.

Konfiguracja agenta (domyślnie):

# With a config file
a365 setup all

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

Konfiguracja agenta M365 (Teams/Copilot):

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

Ustawienie drużyny AI:

a365 setup all --aiteammate

Cały proces konfiguracji wykonuje następujące operacje:

  1. Tworzy infrastrukturę Azure (jeśli jeszcze nie istnieje):

    • Grupa zasobów
    • Plan App Service z określonym SKU
    • Azure Web App z włączoną tożsamością zarządzaną

  2. Rejestruje blueprint agenta:

    • Tworzy blueprint agenta w Twoim dzierżawcy Microsoft Entra
    • Tworzy rejestracje aplikacji Microsoft Entra
    • Konfiguruje tożsamość agenta z wymaganymi uprawnieniami
    • Ustawia managerApplications w blueprintcie, co jest niezbędne do zarządzania platformą

    Ważne

    Blueprinty muszą mieć ustawiony managerApplications, aby zostały zaakceptowane przez platformę. CLI ustawia to automatycznie. Jeśli masz blueprint utworzony przed wprowadzeniem tego wymogu, usuń go i uruchom a365 setup all ponownie albo popraw go ręcznie za pomocą interfejs Graph API.

  3. Konfiguracja uprawnień API:

    • Konfiguruje zakresy API Microsoft Graph
    • Konfiguruje uprawnienia API bota wiadomości
    • Stosuje dziedziczne uprawnienia dla instancji agentów

  4. Aktualizuje pliki konfiguracyjne:

    • Wygenerowane identyfikatory i punkty końcowe są zapisywane do nowego pliku w katalogu roboczym o nazwie a365.generated.config.json
    • Rejestruje informacje o zarządzanej tożsamości i zasobach

Notatka

Konfiguracja zazwyczaj trwa 3–5 minut i automatycznie zapisuje ustawienia do a365.generated.config.json. Jeśli jesteś administratorem globalnym, CLI może otworzyć okno przeglądarki w celu uzyskania zgody administratora – dokończ proces udzielania zgody, aby kontynuować. Jeśli działasz jako Agent ID Developer, nie pojawia się okno przeglądarki; CLI generuje adresy URL zgody, które Globalny Administrator może zatwierdzić później.

Konfiguracja za pomocą Agent ID Developer

Jeśli działasz jako Agent ID Developer (nie Globalny Administrator), a365 setup all automatycznie wykonuje większość kroków, ale przyznawanie uprawnień w OAuth2 wymaga osobnego kroku Globalnego Administratora.

Które kroki wykonują się automatycznie:

  • Infrastruktura Azure (resource group, App Service Plan, Web App)
  • Rejestracja szablonu agenta
  • Dziedziczne uprawnienia dla instancji agentów

Jakie kroki wymagają globalnego administratora:

  • Przyznanie uprawnień delegowanych OAuth2 (AllPrincipalszgoda) dla Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API oraz Power Platform API

Jak zakończyć konfigurację za pomocą konta bez uprawnień administratora:

Krok Kto Akcja
1 przypada na wpłatę z zysku na rzecz budżetu państwa Deweloper Uruchom program a365 setup all. CLI wykonuje wszystkie możliwe kroki i wyświetla następne kroki, w tym URL zgody, który powinien otworzyć globalny administrator.
2 Deweloper Udostępnij URL zgody z wyjścia CLI ze swoim Globalnym Administratorem.
3 Globalny administrator Otwórz URL zgody w przeglądarce zalogowanej jako Globalny Administrator i przyznaj żądane uprawnienia.

Uruchamianie poleceń:

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

Podziel się kolejnymi krokami wydrukowanymi przez CLI ze swoim Globalnym Administratorem. Mogą otworzyć podany link lub URL zgody, aby ukończyć granty OAuth2.

Zweryfikuj instalację

Po zakończeniu konfiguracji widzisz podsumowanie pokazujące wszystkie ukończone kroki. Zweryfikuj utworzone zasoby:

  1. Zweryfikuj wygenerowaną konfigurację:

    Otwórz a365.generated.config.json w swoim katalogu roboczym. Lub użyj programu PowerShell:

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

    Oczekiwany wynik obejmuje następujące wartości krytyczne:

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

    Kluczowe pola do weryfikacji:

    Pole Przeznaczenie Co należy sprawdzić?
    managedIdentityPrincipalId Uwierzytelnianie tożsamości zarządzanej Azure Powinien to być prawidłowy identyfikator GUID
    agentBlueprintId Unikalny identyfikator twojego agenta Używane w Developer Portal oraz admin center
    agentBlueprintObjectId Microsoft Entra ID Blueprint
    messagingEndpoint Routing wiadomości Adres docelowy dla wiadomości z Teams/Outlook do Twojego agenta
    agentBlueprintClientSecret Klucz tajny uwierzytelniania Powinno istnieć (wartość jest zamaskowana)
    resourceConsents Uprawnienia aplikacji Powinien zawierać zasoby takie jak Microsoft Graph, Agent 365 Tools, API botów komunikacyjnych, API obserwacji
    completed Stan konfiguracji Powinno być true

    Notatka

    Jeśli program instalacyjny został uruchomiony z uprawnieniami administratora agenta lub programisty agenta, pole resourceConsents może być puste, a pole completed może mieć wartość false, dopóki administrator globalny nie zakończy procesu przyznawania uprawnień OAuth2, wykonując kolejne kroki wyświetlone przez interfejs CLI.

  2. Zweryfikuj zasoby Azure w Azure Portal:

    Można też użyć polecenia PowerShell az resource list.

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

    Zweryfikuj, czy zostały utworzone następujące zasoby:

    • Grupa zasobów:

      • Przejdź do Grupy zasobów> Wybierz swoją grupę zasobów
      • Sprawdź, czy zawiera App Service Plan oraz Web App

    • Plan usługi App Service:

      • Przejdź do App Services>App Service Plans
      • Znajdź swój plan i zweryfikuj, czy warstwa cenowa odpowiada twojej konfiguracji SKU

    • Aplikacja sieci web:

      • Przejdź do App Services>Web Apps
      • Znajdź swoją aplikację internetową, a następnie przejdź do Ustawienia>Tożsamość>System przypisany
      • Sprawdź, czy stan jest ustawiony na Włączony
      • Zanotuj, że identyfikator obiektu (głównego) jest zgodny z managedIdentityPrincipalId

  3. Zweryfikuj aplikacje Microsoft Entra w Azure Portal:

    Przejdź do Azure Active Directory>Rejestracje aplikacji>Wszystkie aplikacje:

    • Wyszukaj plan dla swojego agenta przy agentBlueprintId

    • Otwórz aplikację i wybierz uprawnienia API

    • Sprawdź, czy uprawnienia zostały przyznane i oznaczone zielonymi znaczkami wyboru:

      • Microsoft Graph (uprawnienia delegowane i aplikacyjne)
      • Uprawnienia API Messaging Bot

    • Wszystkie uprawnienia mają status „Przyznano dla [Twojego najemcy]”

  4. Zweryfikuj wygenerowany plik konfiguracyjny:

    Powinien być dostępny plik o nazwie a365.generated.config.json, który zawiera wszystkie dane konfiguracyjne.

    Użyj polecenia PowerShell Test-Path, aby sprawdzić, czy plik istnieje.

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

    Ważne

    Zapisz oba pliki a365.config.json i a365.generated.config.json. Te wartości są potrzebne do wdrożenia i rozwiązywania problemów.

  5. Sprawdź, czy aplikacja internetowa ma włączoną zarządzaną tożsamość:

    Użyj polecenia az webapp identity show, aby sprawdzić, czy zarządzana tożsamość jest włączona.

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

    Spodziewany:

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

  6. Sprawdź, czy szablon agenta jest zarejestrowany w Microsoft Entra:

    W centrum administracyjnym Microsoft Entra wyszukaj swojego agentBlueprintId lub po imieniu.

    Sprawdź, czy:

    ✅ Pojawiają się opcje „Rejestracja aplikacji” i „Aplikacja korporacyjna”
    ✅ W szablonie rejestracji aplikacji, zakładka „Uprawnienia API" wyświetla wszystkie uprawnienia
    ✅ Status pokazuje "Przyznano dla [Twojego Najemcy]"

Aby uzyskać więcej informacji, zobacz:

Uprawnienia agenta

Zanim aplikacje i agenci będą mogli czytać lub zapisywać dane Microsoft 365 (użytkowników, pocztę, pliki, Teams, agentów itd.), musisz im wyraźnie przyznać uprawnienia do Microsoft Graph. Uprawnienia Microsoft Graph to model autoryzacji, który kontroluje, do jakich danych i działań aplikacja lub usługa może uzyskać dostęp za pomocą API Microsoft Graph w Microsoft 365 i Microsoft Entra ID.

Dowiedz się więcej: Przegląd uprawnień Microsoft Graph

Aby korzystać z uprawnień Graph dla instancji agentów Agent 365, programista musi zadeklarować je w szablonie agenta. Gdy administrator aktywuje szablon w Centrum administracyjnym Microsoft 365, portal przegląda uprawnienia Graph zadeklarowane w szablonie i wyświetla monit administratorowi o wyrażenie zgody na nie.

Aby zrozumieć i zweryfikować, jak uprawnienia Graph umożliwiają działanie Twojego agenta, możesz:

Zastosuj uprawnienia do swojego blueprintu

Użyj a365 setup permissions custom, aby zastosować niestandardowe uprawnienia API bezpośrednio w swoim Blueprint w 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

Zobacz setup permissions custom po szczegółowe informacje dotyczące konfiguracji i usuwania niestandardowych uprawnień.

Następne kroki

Wdróż kod agenta w chmurze:

Azure

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

Opublikuj agenta w centrum administracyjnym Microsoft

Rozwiązywanie problemów

Ta sekcja opisuje typowe problemy podczas konfigurowania szablonów agentów.

Wskazówka

Przewodnik po rozwiązywaniu problemów Agent 365 zawiera wysokopoziomowe zalecenia dotyczące rozwiązywania problemów, najlepsze praktyki oraz odnośniki do treści dotyczących rozwiązywania problemów dla każdego etapu cyklu rozwoju Agent 365.

Te problemy czasami pojawiają się podczas rejestracji:

Błąd: Niewystarczające uprawnienia

Objaw: Błąd niewystarczających uprawnień podczas wykonywania a365 setuppolecenia.

Potrzebna jest jedna z następujących ról w dzierżawcy Microsoft Entra:

  • Globalny administrator usługi
  • Agent ID Developer

Oraz dostęp do subskrypcji Azure w roli Kontrybutora lub Właściciela.

Rozwiązanie: Sprawdź, czy masz wymagane uprawnienia w Microsoft Entra.

Notatka

Jeśli masz rolę Administratora ID agenta lub Programisty ID agenta (nie Administratora Globalnego), a365 setup all zostanie wykonane pomyślnie, ale pominie nadanie uprawnień OAuth2. Po zakończeniu konfiguracji CLI wyświetla kolejne kroki dla Globalnego Administratora, aby dokończyć przyznawanie pozostałych uprawnień. Ten workflow jest oczekiwany w organizacjach, gdzie agent developer i Global Administrator to różne osoby.

Brak uwierzytelniania Azure CLI

Objaw: Proces konfiguracji zakończył się niepowodzeniem z powodu błędów uwierzytelniania.

Rozwiązanie: Upewnij się, że jesteś połączony z platformą Azure i zweryfikuj swoje konto oraz subskrypcję.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

Zasób już istnieje

Symptom: Konfiguracja kończy się Resource already exists błędem dla grupy zasobów, planu App Service lub aplikacji Web.

Rozwiązania: Wybierz jedno z następujących rozwiązań.

  • Użyj istniejących zasobów platformy

    Jeśli zasoby istnieją i chcesz z nich korzystać, upewnij się, że są zgodne z twoją konfiguracją. Można też użyć polecenia PowerShell az resource list.

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

  • Usuń sprzeczne zasoby

    Usuń grupę zasobów lub zmień nazwę zasobów w a365.config.json, a następnie ponownie uruchom konfigurację.

    Użyj polecenia PowerShell az group delete, aby usunąć grupę zasobów.

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

  • Użyj polecenia cleanup, aby zacząć od nowa

    Użyj polecenia cleanup, aby usunąć wszystkie zasoby Agent 365, a następnie użyj poleceniaa365 setup all, aby ponownie przeprowadzić konfigurację.

    Ostrzeżenie

    Uruchomienie a365 cleanup jest destrukcyjne.

    a365 cleanup
a365 setup all

Objaw: Podczas konfiguracji otworzyłeś okna przeglądarki, ale zamknąłeś je bez ukończenia procesu udzielania zgody, lub konfiguracja została ukończona, lecz przyznanie uprawnień OAuth2 wciąż nie zostało przyznane.

Rozwiązanie: Wybierz na podstawie swojej roli:

  • Globalny administrator: Wykonaj a365 setup all ponownie. CLI wyświetla monit o zgodę administratora. Dokończ proces udzielania zgody w oknie przeglądarki, które się pojawi.

  • Administrator identyfikatora agenta lub deweloper: Nie możesz bezpośrednio przyznawać uprawnień OAuth2. Run a365 setup all — podsumowanie konfiguracji wyświetla kolejne kroki dla Globalnego Administratora, w tym bezpośredni link lub URL zgody na ukończenie grantów. Przekaż te informacje swojemu Global Administratorowi.

Brakujące lub nieprawidłowe pliki konfiguracyjne

Objaw: Proces konfiguracji kończy się niepowodzeniem z błędem "Konfiguracja nie znaleziona" lub błędami walidacji.

Rozwiązanie:

  1. Sprawdź, czy plik a365.config.json istnieje.
  2. Jeśli plik jest nieprawidłowy lub go brakuje, utwórz go ręcznie lub skorzystaj z a365 setup all --agent-name <name> (tylko dla agentów).
# Verify a365.config.json exists
Test-Path a365.config.json

Konfiguracja kończy się, ale zasoby nie zostały utworzone

Objaw: Polecenie setup zakończyło się sukcesem, ale zasoby Azure nie zostały utworzone.

Rozwiązanie:

  1. Sprawdź utworzone zasoby, otwierając a365.generated.config.json w swoim katalogu roboczym.
  2. Sprawdź, czy zasoby Azure istnieją, używając az resource list polecenia.
  3. Jeśli zasoby są nieobecne, sprawdź błędy w wynikach konfiguracji i ponownie uruchom konfigurację za pomocą polecenia 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

Szablon agenta nie został zarejestrowany w Microsoft Entra

Objaw: Konfiguracja zostaje zakończona, ale nie możesz znaleźć szablonu agenta w centrum administracyjnym Microsoft Entra.

Rozwiązanie:

  1. Pobierz identyfikator planu z a365.generated.config.json.

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

  2. Wyszukiwanie w centrum administracyjnym Microsoft Entra:

    1. Przejdź do Centrum administracyjne Microsoft Entra.
    2. Przejdź do Rejestracje aplikacji>Wszystkie aplikacje.
    3. Wyszukaj agentBlueprintId.

  3. Jeśli nie zostanie znaleziony, uruchom ponownie konfigurację za pomocą polecenia a365 setup all.

    a365 setup all

Nie przyznano uprawnień API

Objaw: Konfiguracja zakończona, ale uprawnienia w Microsoft Entra są oznaczone jako "Nie przyznane".

Rozwiązanie:

  1. Przejdź do Centrum administracyjne Microsoft Entra.

  2. Znajdź rejestrację aplikacji agent blueprint.

  3. Przejdź do obszaru Uprawnienia interfejsu API.

  4. Wyrażanie zgody administratora:

    1. Wybierz pozycję Wyraź zgodę administratora dla [dzierżawcy].
    2. Potwierdź akcję.

  5. Sprawdź, czy wszystkie uprawnienia mają zielone znaczniki.

Funkcja zarządzanej tożsamości nie jest włączona

Objaw: Istnieje aplikacja webowa, ale zarządzana tożsamość nie została włączona.

Rozwiązanie:

  1. Sprawdź status zarządzanej tożsamości za pomocą polecenia az webapp identity show.
  2. Jeśli nie jest włączona, włącz ją ręcznie za pomocą polecenia az webapp identity assign.
  3. Sprawdź, czy jest włączone, używając tego az webapp identity show polecenia.
# 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>

Konfiguracja trwa za długo lub nie odpowiada

Objaw: Polecenie setup działa dłużej niż 10 minut bez ukończenia.

Rozwiązanie:

  1. Jeśli działasz jako globalny administrator, sprawdź, czy okno przeglądarki oczekuje na udzielenie zgody administratora. Dokończ procedurę zgody, aby odblokować konfigurację.

  2. Jeśli konfiguracja rzeczywiście przestanie reagować, przerwij ją (Ctrl+C) i sprawdź, co zostało utworzone.

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

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

  3. Wyczyść zasoby i spróbuj ponownie.

    a365 cleanup
a365 setup all

Czyszczenie agenta bez konfiguracji

Objaw: Uruchomiłeś agenta i a365 setup all --agent-name <name> teraz chcesz go usunąć, ale nie masz pliku a365.config.json .

Rozwiązanie: Użyj a365 cleanup --agent-name do usunięcia agenta bez pliku konfiguracyjnego. CLI czyta identyfikatory zasobów z globalnej konfiguracji utworzonej podczas procesu bootstrap.

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

Wskazówka

Jeśli polecenie utknie podczas uwierzytelniania, automatycznie przełącza się na przepływ kodu urządzenia. Postępuj zgodnie z instrukcjami wyświetlonymi w terminalu, aby dokończyć logowanie.

Jeśli nie masz już globalnie generowanej konfiguracji (na przykład po ponownej instalacji CLI), użyj a365 cleanup z ręcznie utworzonym minimalnym a365.config.json, albo usuń zasoby bezpośrednio przez Azure Portal i Centrum administracyjne Microsoft Entra.

Nie można wysłać pierwszej wiadomości w Teams

Objaw: Po uruchomieniu instancji agenta nie może on wysłać wiadomości do menedżera agenta jako wiadomość powitalną.

Rozwiązanie: Wymagane jest uprawnienie [Chat.Create][perm-chatcreate] do utworzenia nowego obiektu czatu. Jeśli czat jeden na jeden już istnieje, ta operacja zwraca istniejący czat i nie tworzy nowego.

  • Aby wdrożyć, skonfiguruj dziedziczone uprawnienia blueprintu tak, aby obejmowały zakres Chat.Create.
  • Skonfiguruj wiadomość czatu Teams do wysłania po utworzeniu instancji agenta.
  • Utwórz nową instancję agenta na podstawie blueprintu i przetestuj wiadomość pierwszego uruchomienia.
  • Last updated on