Testuj agentów za pomocą Microsoft Agent 365 SDK

Przed wdrożeniem przetestuj swojego agenta lokalnie, korzystając z Agents Playground. Ten przewodnik obejmuje konfigurację środowiska programistycznego, konfigurację uwierzytelniania oraz weryfikację funkcjonalności agenta za pomocą narzędzia testowego Agents Playground.

Gdy Twój agent działa lokalnie, postępuj zgodnie z cyklem rozwoju Agent 365, aby testować swojego agenta w aplikacjach Microsoft 365, takich jak Teams, Word i Outlook.

Wymagania wstępne

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

Wspólne wymagania wstępne

Wymagania wstępne dla poszczególnych języków

  • Python 3.11 lub nowszy: pobierz z python.org lub Microsoft Store
  • menedżer pakietów uv: Zainstaluj uv za pomocą pip install uv
  • Sprawdzanie instalacji: python --version

Konfiguracja środowiska testowania agentów

Ta sekcja opisuje, jak ustawić zmienne środowiskowe, uwierzytelnić środowisko deweloperskie oraz przygotować agenta opartego na Agent 365 do testowania.

Konfiguracja środowiska testowania agentów według poniższego sekwencyjnego przepływu pracy:

  1. Konfiguracja środowiska — stwórz lub zaktualizuj plik konfiguracyjny środowiska.

  2. Konfiguracja LLM – Pobierz klucze API i skonfiguruj ustawienia OpenAI lub Azure OpenAI.

  3. Konfiguracja uwierzytelniania – ustawienie uwierzytelniania agentowego.

  4. Zmienne środowiskowe – referencja - Skonfiguruj wymagane zmienne środowiskowe:

    1. Zmienne uwierzytelniania
    2. Konfiguracja punktu końcowego MCP
    3. Zmienne obserwowalności
    4. Konfiguracja serwera aplikacji agenta

Po ukończeniu tych kroków jesteś gotowy, aby rozpocząć testowanie agenta w Agents Playground.

Krok 1: konfigurowanie środowiska

Przygotuj plik konfiguracyjny:

cp .env.template .env

Notatka

Aby uzyskać szablony konfiguracji z wymaganymi polami, zobacz przykłady SDK Microsoft Agent 365.

Krok 2: Konfiguracja LLM

Skonfiguruj ustawienia OpenAI lub Azure OpenAI do testów lokalnych. Dodaj do pliku konfiguracyjnego swoje klucze API, punkty końcowe usługi z sekcji wymagań wstępnych oraz parametry modelu.

Dodawanie bota do pliku .env:

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

Zmienne środowiskowe Python LLM — często zadawane pytania

Zmienna Podpis Wymagania Przykład
OPENAI_API_KEY Klucz API dla usługi OpenAI Dla OpenAI sk-proj-...
AZURE_OPENAI_API_KEY Klucz API z usługą Azure OpenAI Dla usługi Azure OpenAI a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT Punkt końcowy URL z usługą Azure OpenAI Dla usługi Azure OpenAI https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Nazwa wdrożenia w Azure OpenAI Dla usługi Azure OpenAI gpt-4
AZURE_OPENAI_API_VERSION Wersja API dla Azure OpenAI Dla usługi Azure OpenAI 2024-02-15-preview

Krok 3: Konfigurowanie uwierzytelniania dla agenta

Wybierz jedną z poniższych metod uwierzytelniania dla swojego agenta:

  • Uwierzytelnianie agentic - używane w środowiskach produkcyjnych, gdy dostępna jest tożsamość użytkownika typu agentic.
  • (W imieniu) uwierzytelnianie OBO – Używaj w scenariuszach produkcyjnych, gdy potrzebujesz uprawnień użytkownika delegowanego bez tożsamości użytkownika agentic.
  • Uwierzytelnianie Bearer token – używaj wyłącznie we wczesnych fazach rozwoju i testowania, zanim zostanie skonfigurowane uwierzytelnianie produkcyjne.

Uwierzytelnianie agenta

Otwórz a365.generated.config.json w swoim katalogu roboczym, aby uzyskać dane uwierzytelniające blueprintu agenta. Skopiuj następujące wartości:

Value Podpis
agentBlueprintId Identyfikator klienta twojego agenta
agentBlueprintClientSecret Sekret klienta twojego agenta
tenantId Identyfikator dzierżawy Microsoft Entra ID

Użyj tych wartości do skonfigurowania uwierzytelniania agentycznego w swoim agencie:

Dodaj poniższe ustawienia do pliku .env, zastępując wartości zastępcze swoimi rzeczywistymi poświadczeniami:

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
Zmienna Podpis Wymagania Przykład
USE_AGENTIC_AUTH Włącz tryb uwierzytelniania agentic Tak true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID ID klienta Agent Blueprint z a365.generated.config.json Tak 11112222-bbbb-3333-cccc-4444dddd5555
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Sekret klienta Agent Blueprint z a365.generated.config.json Tak abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID Identyfikator dzierżawy Microsoft Entra ID z a365.generated.config.json Tak 22223333-cccc-4444-dddd-5555eeee6666

Uwierzytelnianie OBO

Dzięki uwierzytelnianiu On-Behalf-Of (OBO), Twój agent może uzyskać dostęp do narzędzi serwera MCP za pomocą delegowanych uprawnień, bez konieczności posiadania tożsamości użytkownika agenta. W tym procesie agent otrzymuje przekazany token użytkownika i zamienia go na token umożliwiający wykonywanie działań w imieniu użytkownika.

Uwierzytelnianie OBO jest odpowiednie dla scenariuszy produkcyjnych, w których:

  • Twój agent nie posiada tożsamości użytkownika agenta.
  • Musisz uzyskać dostęp do zasobów z uprawnieniami specyficznymi dla użytkownika.
  • Chcesz, aby agent działał w imieniu uwierzytelnionego użytkownika.

Aby uzyskać szczegółowe informacje o działaniu przepływu OBO, zobacz Przepływy uwierzytelniania. Pełny przykład implementacji znajdziesz w przykładzie autoryzacji OBO w Zestaw SDK agentów usługi Microsoft 365.

Uwierzytelnianie tokena elementu nośnego

W scenariuszach wczesnego rozwoju i testowania, gdy uwierzytelnianie produkcyjne nie jest skonfigurowane, użyj uwierzytelniania za pomocą tokena typu bearer, aby przetestować swojego agenta. Ta metoda wykorzystuje interaktywne uwierzytelnianie przez przeglądarkę do uzyskania delegowanego tokenu dostępu. Korzystając z tego tokena, Twój agent może wywoływać narzędzia MCP Server za pomocą Twoich uprawnień użytkownika. To podejście symuluje sposób, w jaki użytkownik agenta uzyskuje dostęp do zasobów w środowisku produkcyjnym bez konieczności posiadania rzeczywistej instancji agenta.

Najpierw użyj a365 develop add-permissions aby dodać wymagane uprawnienia serwera MCP do swojej aplikacji:

a365 develop add-permissions

Następnie użyj a365 develop get-token do pobrania i skonfigurowania tokenów dostępowych:

a365 develop get-token

Polecenie automatycznie get-token :

  • Odczytuje ToolingManifest.json w celu wykrycia wszystkich skonfigurowanych serwerów MCP.
  • Pobierany jest jeden token dla każdego odbiorcy – serwery MCP otrzymują token przypisany do ich konkretnego ID aplikacji; wspólne serwery ATG otrzymują token przypisany do wspólnego ID aplikacji Agent Tools Gateway (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1).
  • Zapisuje tokeny do plików konfiguracyjnych projektu:
    • Tokeny dla poszczególnych serwerów: BEARER_TOKEN_<SERVER_NAME> (na przykład BEARER_TOKEN_MCP_MAILTOOLS)
    • Współdzielony token ATG: BEARER_TOKEN

Przed uruchomieniem get-token dodaj wpisy zastępcze do pliku konfiguracyjnego projektu:

  • .NET: Dodaj "BEARER_TOKEN": "" i/lub "BEARER_TOKEN_<SERVER_NAME>": "" do environmentVariables w każdym profilu w Properties/launchSettings.json. Polecenie aktualizuje tylko profile, które już mają te klucze zdefiniowane.
  • Python/Node.js: Utwórz plik .env z BEARER_TOKEN= i/lub BEARER_TOKEN_<SERVER_NAME>= przed uruchomieniem. Jeśli pliku brakuje, polecenie pomija zapisywanie i pokazuje wskazówki.

Notatka

Jeśli uruchomisz a365 develop get-token --app-id <id> bez pliku a365.config.json, tokeny nie zapisują się automatycznie. Skopiuj i wklej je ręcznie do pliku Properties/launchSettings.json (dla .NET) lub do pliku .env (dla Python/Node.js).

Tokeny bearer tracą ważność po około godzinie. Użyj a365 develop get-token aby odświeżyć wygasłe tokeny.

Krok 4: Odwoływanie się do zmiennych Środowiskowych

Skonfiguruj następujące wymagane zmienne środowiskowe, aby zakończyć konfigurację środowiska.

Zmienne uwierzytelniania

Skonfiguruj ustawienia obsługi uwierzytelniania wymagane, aby autentykacja agentowa działała prawidłowo.

Dodawanie bota do pliku .env:

# Agentic Authentication Settings
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE=AgenticUserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES=https://graph.microsoft.com/.default
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME=service_connection

# Connection Mapping
CONNECTIONSMAP_0_SERVICEURL=*
CONNECTIONSMAP_0_CONNECTION=SERVICE_CONNECTION
Zmienna Podpis Wymagania
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Typ obsługi uwierzytelniania Tak
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Zakresy dostępu dla Microsoft Graph Tak
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Alternatywna nazwa połączenia szablonu Tak
CONNECTIONSMAP_0_SERVICEURL Wzorzec adresu URL usługi do mapowania połączeń Tak
CONNECTIONSMAP_0_CONNECTION Nazwa połączenia do mapowania Tak

Zmienne tokenów typu bearer (tylko dla środowiska lokalnego)

Zmienna Podpis Wymagania
BEARER_TOKEN Współdzielony token uwierzytelniający typu bearer dla współdzielonych serwerów ATG MCP. Polecenie a365 develop get-token automatycznie zapisuje ten token. Dla wspólnego lokalnego dewelopera ATG
BEARER_TOKEN_<SERVER_NAME> Token typu bearer przypisany do serwera. SDK tworzy nazwę poprzez zamianę mcpServerName na wielkie litery z ToolingManifest.json (na przykład: mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS). Polecenie a365 develop get-token automatycznie zapisuje ten token. Dla lokalnego dewelopera na serwerze
SKIP_TOOLING_ON_ERRORS Ustaw na true, aby przejść na sam LLM, jeśli narzędzia MCP nie zostaną załadowane. Honorowany tylko wtedy, gdy ASPNETCORE_ENVIRONMENT lub ENVIRONMENT jest .Development Nie

Ważne

Tokeny na okaziciela są przeznaczone wyłącznie do lokalnego środowiska developerskiego. Nigdy nie ustawiaj BEARER_TOKEN ani BEARER_TOKEN_<SERVER_NAME> w produkcyjnych wdrożeniach.

Konfiguracja punktu końcowego MCP

Określ punkt końcowy platformy Agent 365, do którego łączy się twój agent. Gdy generujesz manifest narzędziowy definiujący serwery narzędzi dla swojego agenta, określ punkt końcowy platformy MCP. Ten punkt końcowy określa, z którym środowiskiem (preprod, test lub produkcja) serwery narzędzi MCP łączą się w celu integracji z Microsoft 365.

Dodawanie bota do pliku .env:

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
Zmienna Podpis Wymagani Wartość domyślna Przykład
MCP_PLATFORM_ENDPOINT Adres URL punktu końcowego platformy MCP (preprod, test lub prod) Nie Punkt końcowy produkcji

Ważne: Jeśli nie określisz MCP_PLATFORM_ENDPOINT, aplikacja użyje endpointu produkcyjnego.

Notatka

Jeśli korzystasz z mock tooling servera z CLI, ustaw endpoint na http://localhost:<port>, podając numer portu, którego używasz. Port domyślny to 5309.

Zmienne obserwowalności

Skonfiguruj te wymagane zmienne, aby umożliwić logowanie i rozproszone śledzenie dla swojego agenta. Pełną listę zmiennych środowiskowych, opcji konfiguracji i przykładów kodu można znaleźć w Agent observability.

Notatka

Konfiguracja obserwowalności jest taka sama we wszystkich językach. Zobacz temat Konfiguracja, aby poznać więcej szczegółów.

Zmienna Podpis Wartość domyślna Przykład
ENABLE_A365_OBSERVABILITY_EXPORTER Eksportuj ślady do usługi obserwowalności. Gdy false, eksport przechodzi na konsolę. false true
A365_OBSERVABILITY_LOG_LEVEL Wewnętrzny poziom logowania w SDK obserwowalności. Przydatne do debugowania problemów z eksportem podczas testów. none info, warn, error, debug

Konfiguracja serwera aplikacji agenta

Skonfiguruj port, na którym działa serwer aplikacji agenta. To ustawienie jest opcjonalne i dotyczy agentów Pythona i JavaScript.

Dodawanie bota do pliku .env:

# Server Configuration
PORT=3978
Zmienna Podpis Wymagani Wartość domyślna Przykład
PORT Numer portu, na którym działa serwer agenta Nie 3978 3978

Zainstaluj zależności i uruchom serwer aplikacji agenta

Po skonfigurowaniu środowiska zainstaluj wymagane zależności i uruchom lokalnie serwer aplikacji agenta do testów.

Zainstaluj zależności

uv pip install -e .

To polecenie odczytuje zależności pakietów zdefiniowane w pyproject.toml i instaluje je z PyPI. Tworząc aplikację agenta od zera, utwórz plik pyproject.toml do definiowania zależności. Przykładowe agenty z samples repository mają już zdefiniowane te pakiety. W razie konieczności można zaktualizować w razie potrzeby.

Uruchom serwer aplikacji agenta

python <main.py>

Zastąp <main.py> nazwą głównego pliku Pythona, który zawiera punkt wejścia dla Twojej aplikacji agenta (na przykład start_with_generic_host.py, app.py lub main.py).

Lub użyj uv:

uv run python <main.py>

Serwer agenta jest teraz uruchomiony i gotowy do przyjmowania żądań z aplikacji Agents Playground lub aplikacji Microsoft 365.

Przetestuj agenta w Agents Playground

Agents Playground to lokalne narzędzie testowe, które symuluje środowisko Microsoft 365 bez konieczności posiadania w pełni skonfigurowanego dzierżawcy. To najszybszy sposób, aby zweryfikować logikę i wywołania narzędzi Twojego agenta. Aby uzyskać więcej informacji, zobacz Test with Agents Playground.

Skonfiguruj Agents Playground dla uwierzytelniania agentowego

Notatka

Ta konfiguracja jest wymagana tylko przy użyciu uwierzytelniania agentycznego. Jeśli używasz uwierzytelniania za pomocą tokenu typu bearer, możesz pominąć tę sekcję i przejść bezpośrednio do testu podstawowego.

Korzystając z uwierzytelniania agentycznego, skonfiguruj plik YAML Agents Playground z danymi swojego agenta:

  1. Skonfiguruj plik konfiguracyjny: utwórz lub zaktualizuj .m365agentsplayground.yml plik w folderze, w którym uruchamiasz Agents Playground. Szczegółowe instrukcje konfiguracji: zobacz Dostosuj kontekst Teams.

  2. Zaktualizuj konfigurację bota: Dodaj poniższe szczegóły bota do .m365agentsplayground.ymlpliku, zastępując wartości przykładowe rzeczywistymi poświadczeniami agenta.

    bot:
  id: <your-agent-email>@<your-tenant>.onmicrosoft.com
  name: <Your Agent Name>
  role: agenticUser
  agenticUserId: <your-agentic-user-id>
  agenticAppId: <your-agentic-app-id>
    Właściwość Opis Wymagania
    id Adres e-mail użytkownika agenta w formacie agentusername@tenant.onmicrosoft.com Tak
    name Nazwa wyświetlana dla użytkownika agenta Tak
    role Musi być ustawione na agenticUser dla uwierzytelniania agentowego Tak
    agenticUserId Nazwa identyfikatora obiektu użytkownika agenta. Znajdź tę wartość w centrum administracyjnym Microsoft Entra w profilu użytkownika agenta. Tak
    agenticAppId Nazwa identyfikatora agenta użytkownika agenta. Znajdź tę wartość w centrum administracyjnym Microsoft Entra w profilu użytkownika agenta. Tak

Otwórz nowy terminal (PowerShell na Windows) i uruchom Agents Playground:

agentsplayground

To polecenie otwiera przeglądarkę internetową z interfejsem Agents Playground. Narzędzie wyświetla interfejs czatu, na którym możesz wysyłać wiadomości do swojego agenta.

Test podstawowy

Zacznij od sprawdzenia, czy Twój agent jest poprawnie skonfigurowany. Wyślij wiadomość do agenta:

What can you do?

Agent odpowiada instrukcjami, z którymi został skonfigurowany, na podstawie systemowego polecenia i swoich możliwości. Ta odpowiedź potwierdza:

  • Twój agent działa poprawnie.
  • Agent może przetwarzać wiadomości i odpowiadać.
  • Komunikacja między Agents Playground a Twoim agentem działa.

Wywołania narzędzi testowych

Po skonfigurowaniu serwerów narzędzi MCP w toolingManifest.json (zobacz Narzędzia w celu uzyskania instrukcji konfiguracji), przetestuj wywołania narzędzi, korzystając z poniższych przykładów:

Po pierwsze, sprawdź, które narzędzia są dostępne:

List all tools I have access to

Następnie przetestuj wywołania konkretnych narzędzi:

Narzędzia mailowe

Send email to your-email@example.com with subject "Test" and message "Hello from my agent"

Oczekiwana odpowiedź: Agent wysyła wiadomość e-mail przez serwer Mail MCP i potwierdza, że wiadomość została wysłana.

Narzędzia kalendarzowe

List my calendar events for today

Oczekiwana odpowiedź: Agent pobiera i wyświetla wydarzenia z kalendarza na dziś.

Narzędzia SharePoint

List all SharePoint sites I have access to

Oczekiwana odpowiedź: Agent zapytuje SharePoint i zwraca listę witryn, do których masz dostęp.

Możesz zobaczyć wywołania narzędzi w:

  • Okno czatu – zobacz odpowiedź agenta i wywołania narzędzi.
  • Panel logów – zobacz szczegółowe informacje o aktywnościach, w tym parametry narzędzi i odpowiedzi.

Testuj aktywności powiadomień

Podczas lokalnych testów, testuj scenariusze powiadomień, korzystając z wbudowanych wyzwalaczy powiadomień w Agents Playground.

Zrzut ekranu przedstawia interfejs Agents Playground z rozwiniętym menu Mock an Activity, pokazującym opcje Trigger Notification Activity, takie jak Wyślij e-mail i Wzmianka w Word.

Przed przetestowaniem działań powiadamiających upewnij się, żeby:

Testu powiadomienia e-mail

Aby przetestować obsługę powiadomień e-mailowych:

  1. Uruchom swojego agenta oraz Agents Playground.
  2. W Agents Playground, przejdź do Symuluj działanie>Wyzwól powiadomienie o aktywności.
  3. Wybierz pozycję Wyślij wiadomość e-mail.
  4. W oknie dialogowym zaktualizuj szczegóły symulowanego e-maila, takie jak nazwa nadawcy i treść wiadomości e-mail, według potrzeb.
  5. Wybierz Wyślij aktywność.
  6. Sprawdź wynik zarówno w rozmowie na czacie, jak i w panelu logów.

Agent otrzymuje symulowane powiadomienie e-mail i przetwarza je zgodnie z Twoją logiką obsługi powiadomień. Aby uzyskać szczegółowe informacje o strukturze payloadu powiadomienia e-mail, zobacz Payload powiadomienia e-mail.

Przetestuj powiadomienia o wzmiankach w dokumentach Word

Aby przetestować powiadomienia o wzmiankach w dokumentach Word:

  1. Uruchom swojego agenta oraz Agents Playground.
  2. W Agents Playground, przejdź do Symuluj działanie>Wyzwól powiadomienie o aktywności.
  3. Wybierz Wzmianka w Word.
  4. W oknie dialogowym payloadu zaktualizuj szczegóły przykładowego komentarza, takie jak ID dokumentu i treść komentarza, w razie potrzeby.
  5. Wybierz Wyślij aktywność.
  6. Sprawdź wynik zarówno w rozmowie na czacie, jak i w panelu logów.

Agent otrzymuje testowe powiadomienie o wzmiance w Wordzie i odpowiada zgodnie z Twoją logiką obsługi powiadomień. Szczegółowe informacje o strukturze payloadu powiadomienia o komentarzu w Wordzie znajdziesz w Dokumentacja payloadu powiadomienia o komentarzu.

Przetestuj zdarzenia instalacji i odinstalowania agenta

Gdy Agents Playground łączy się z Twoim agentem, automatycznie wysyła aktywność InstallationUpdate z akcją add. Jeśli zaimplementujesz obsługę zdarzenia instalacji, wiadomość powitalna od twojego agenta pojawi się na czacie natychmiast po ustanowieniu połączenia.

Aby przetestować obsługę zdarzenia instalacji:

  1. Uruchom serwer agenta.
  2. Otwórz Agents Playground. Playground łączy się z twoim agentem i automatycznie wywołuje zdarzenie instalacji.
  3. Potwierdź, że wiadomość powitalna pojawia się w rozmowie na czacie.

Zrzut ekranu przedstawiający interfejs Agents Playground z wyświetloną w rozmowie na czacie oraz w panelu logów wiadomością powitalną agenta: „Dziękuję za zatrudnienie mnie! Nie mogę się doczekać, aby pomóc Ci w Twojej zawodowej podróży!” po automatycznym wywołaniu zdarzenia instalacji.

Szczegóły dotyczące implementacji obsługi znajdziesz w Obsługa zdarzeń instalacji i odinstalowania agenta.

Wyświetl logi obserwowalności

Aby przeglądać logi obserwowalności podczas lokalnej pracy, zinstrumentuj swojego agenta kodem obserwowalności (zobacz Obserwowalność, aby uzyskać przykłady kodu) i skonfiguruj zmienne środowiskowe zgodnie z opisem w Zmienne obserwowalności. Aby uzyskać instrukcje walidacji krok po kroku oraz oczekiwane wyniki logów, zobacz Walidacja lokalna. Po skonfigurowaniu w konsoli pojawiają się w czasie rzeczywistym ślady, które pokazują:

  • Ślady wywołania agenta
  • Szczegóły wykonywania narzędzia
  • Wywołania inferencji LLM
  • Wiadomości wejściowe i wyjściowe
  • Wykorzystanie tokenów
  • Czasy reakcji
  • Informacje o błędzie

Te dzienniki pomagają debugować problemy, zrozumieć zachowanie agenta oraz zoptymalizować wydajność. Przed publikacją skorzystaj z Validate for store publishing, aby zweryfikować, czy wszystkie wymagane atrybuty zostały uwzględnione.

Następne kroki

Po lokalnym przetestowaniu agenta wdroż go na Azure i opublikuj w Microsoft 365.

Aby przetestować swojego agenta w aplikacjach Microsoft 365, takich jak Teams, Word i Outlook, zobacz cykl życia Agent 365.

Rozwiązywanie problemów

Ta sekcja zawiera rozwiązania typowych problemów, na które możesz napotkać podczas testowania agenta lokalnie.

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.

Problemy z połączeniem i środowiskiem

Problemy te dotyczą łączności sieciowej, konfliktów portów oraz konfiguracji środowiska, które uniemożliwiają agentowi prawidłową komunikację.

Problemy z połączeniem z Agents Playground

Objaw: Agents Playground nie może połączyć się z Twoim agentem.

Rozwiązania:

  • Sprawdź, czy serwer agenta działa.
  • Sprawdź, czy numery portów są zgodne między agentem a Agents Playground.
  • Upewnij się, że żadne reguły zapory nie blokują połączeń lokalnych.
  • Spróbuj zrestartować zarówno agenta, jak i Agents Playground.

Nieaktualna wersja Agents Playground

Objaw: Nieoczekiwane błędy lub brakujące funkcje w Agents Playground.

Rozwiązanie: Odinstaluj i zainstaluj ponownie Agents Playground.

winget uninstall agentsplayground
winget install agentsplayground

Konflikty portów

Objaw: Błąd wskazujący, że port jest już używany.

Rozwiązanie:

  • Zatrzymaj wszystkie inne instancje swojego agenta.
  • Zmień port w swojej konfiguracji.
  • Zakończ wszystkie procesy korzystające z portu.
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

Nie można dodać DeveloperMCPServer

Objaw problemu: Błąd podczas próby dodania DeveloperMCPServer w Visual Studio Code.

Rozwiązanie: Zamknij i ponownie otwórz Visual Studio Code, a następnie spróbuj ponownie dodać serwer.

Problemy z uwierzytelnianiem i tokenami

Te problemy występują, gdy Twój agent nie może poprawnie uwierzytelnić się wobec usług Microsoft 365 lub gdy poświadczenia wygasły albo są nieprawidłowo skonfigurowane.

Objawy:

  • Błędy 401 "Nieautoryzowany"
  • Komunikaty: „Token typu bearer wygasł”
  • Błędy uwierzytelniania agentów

Główna przyczyna:

  • Tokeny wygasają po około godzinie
  • Błędna konfiguracja uwierzytelniania
  • Brakujące lub nieprawidłowe poświadczenia

Rozwiązania:

  • W przypadku wygaśnięcia tokena typu bearer

    Odśwież token i zaktualizuj zmienne środowiskowe.

    # Get a new token
a365 develop get-token

# Update your .env file with the new token

  • Dla niepowodzeń tokenów nosiciela na serwerze

    Zweryfikuj, czy plik konfiguracyjny zawiera zastępcze wpisy dla każdego serwera (BEARER_TOKEN_<SERVER_NAME>), a następnie ponownie uruchom a365 develop get-token, aby je wypełnić. SDK wyprowadza nazwę zmiennej przez zamianę liter na wielkie w mcpServerName w ToolingManifest.json oraz zastąpienie łączników podkreśleniami (na przykład, mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS).

  • W przypadku błędów uwierzytelniania agentycznego (Python)

    Sprawdź swoje zasoby pliku .env:

    # Should be (with underscore):
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

# Not:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

  • W przypadku brakujących poświadczeń

    Upewnij się, że wymagane poświadczenia są dostępne przed testowaniem.

    Upewnij się, że .env lub appsettings.json zawiera:

    • Klucze API i sekrety
    • Identyfikator dzierżawy
    • Identyfikator klienta
    • Identyfikator Blueprinta (jeśli używasz uwierzytelniania agentycznego)

    Weryfikacja:

    Przetestuj proste żądanie w Agents Playground. Należy otrzymać odpowiedź bez błędu 401.

  • Problemy z narzędziami i powiadomieniami

    Problemy te obejmują kwestie związane z wywołaniami narzędzi, interakcjami z serwerem MCP oraz dostarczaniem powiadomień.

Wiadomość e-mail nie została odebrana

Objaw: Agent wskazuje, że e-mail został wysłany, ale go nie otrzymujesz

Rozwiązania:

  • Sprawdź folder Spam lub Niechciane.
  • Dostarczenie wiadomości e-mail może być opóźnione o kilka minut. Poczekaj maksymalnie pięć minut.
  • Sprawdź, czy adres e-mail odbiorcy jest poprawny.
  • Sprawdź dzienniki agenta pod kątem błędów podczas wysyłania wiadomości e-mail.

Odpowiedzi na komentarze w Wordzie nie działają

Znany problem: Usługa powiadomień nie obsługuje bezpośrednich odpowiedzi na komentarze w Word. Ta funkcjonalność jest w trakcie opracowywania.

Wiadomości nie docierają do agenta

Objaw: Twoja aplikacja agenta nie otrzymuje wiadomości wysyłanych do niej w Teams.

Możliwe przyczyny:

  • Portal deweloperski nie jest skonfigurowany za pomocą blueprintu agenta.
  • Problemy z aplikacją internetową Azure (niepowodzenia wdrożenia, nieuruchomienie aplikacji, błędy konfiguracyjne).
  • Instancja agenta nie jest poprawnie tworzona w Teams.

Rozwiązania:

  • Zweryfikuj konfigurację Portalu Deweloperskiego:

    Upewnij się, że ukończyłeś konfigurację blueprintu agenta w Developer Portal. Dowiedz się, jak skonfigurować blueprint agenta w Developer Portal

  • Sprawdź stan aplikacji Azure Web App:

    Jeśli wdrażasz swojego agenta na Azure, sprawdź, czy aplikacja webowa działa poprawnie:

    1. Przejdź do portalu Azure Portal.
    2. Przejdź do swojego zasobu aplikacji webowej.
    3. Sprawdź sekcję Przegląd>Status(powinien wskazywać „Uruchomiono”).
    4. Sprawdź Strumień logów w sekcji Monitorowanie pod kątem błędów w czasie działania.
    5. Przejrzyj logi Centrum wdrożeń, aby potwierdzić, że wdrożenie się powiodło.
    6. Zweryfikuj, że Konfiguracja>Ustawienia aplikacji zawierają wszystkie wymagane zmienne środowiskowe.

  • Zweryfikuj utworzenie instancji agenta:

    Upewnij się, że instancja agenta jest poprawnie utworzona w Microsoft Teams:

    1. Otwórz Microsoft Teams.
    2. Przejdź do Apps i wyszukaj swojego agenta.
    3. Zweryfikuj, czy agent pojawia się w wynikach wyszukiwania.
    4. Jeśli agent nie został znaleziony, upewnij się, że został opublikowany w Centrum administracyjnym platformy Microsoft 365 – Agenci.
    5. Utwórz nową instancję, wybierając opcję Dodaj dla swojego agenta.
    6. Szczegółowe instrukcje znajdziesz w sekcji Wprowadzenie agentów.

Rozwiązywanie problemów z dziennikami obserwowalności

Jeśli dzienniki obserwowalności twojego agenta nie pojawiają się zgodnie z oczekiwaniami, zobacz Rozwiązywanie problemów w przewodniku po obserwowalności.

  • Last updated on