Udostępnij przez

Testowanie agentów przy użyciu zestawu MICROSOFT Agent 365 SDK

Ważne

Aby uzyskać wczesny dostęp do programu Microsoft Agent 365, musisz być częścią programu Frontier w wersji zapoznawczej. Usługa Frontier łączy Cię bezpośrednio z najnowszymi innowacjami firmy Microsoft dotyczącymi sztucznej inteligencji. Wersje zapoznawcze platformy Frontier podlegają istniejącym warunkom obowiązywania wersji zapoznawczej umów klienta. Ponieważ te funkcje są nadal opracowywane, ich dostępność i możliwości mogą ulec zmianie w miarę upływu czasu.

Testowanie agenta lokalnie w środowisku testowym agentów W tym przewodniku opisano konfigurowanie środowiska deweloperskiego, konfigurowanie uwierzytelniania i weryfikowanie funkcjonalności agenta za pomocą narzędzia do testowania placu zabaw agentów.

Gdy agent działa lokalnie, możesz wdrożyć go i opublikować w celu przetestowania w aplikacjach platformy Microsoft 365, takich jak Teams.

Wymagania wstępne

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

Typowe wymagania wstępne

Wymagania wstępne specyficzne dla języka

Konfigurowanie środowiska testowego agenta

W tej sekcji opisano ustawianie zmiennych środowiskowych, uwierzytelnianie środowiska deweloperskiego i przygotowywanie agenta obsługiwanego przez agenta 365 do testowania.

Konfigurowanie środowiska testowego agenta jest zgodne z sekwencyjnym przepływem pracy:

  1. Konfigurowanie środowiska — tworzenie lub aktualizowanie pliku konfiguracji środowiska

  2. Konfiguracja usługi LLM — uzyskiwanie kluczy interfejsu API i konfigurowanie ustawień interfejsu OpenAI lub Azure OpenAI

  3. Konfigurowanie uwierzytelniania — konfigurowanie uwierzytelniania agenta

  4. Dokumentacja zmiennych środowiskowych — konfigurowanie wymaganych zmiennych środowiskowych:

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

Po wykonaniu tych kroków możesz rozpocząć testowanie agenta na placu zabaw agenta.

Krok 5: konfigurowanie środowiska

Skonfiguruj plik konfiguracji:

cp .env.template .env

Notatka

Zapoznaj się z przykładami zestawu MICROSOFT Agent 365 SDK, aby znaleźć szablony konfiguracji z wymaganymi polami.

Krok 2. Konfiguracja usługi LLM

Skonfiguruj ustawienia openAI lub Azure OpenAI na potrzeby testowania lokalnego. Dodaj klucze interfejsu API i punkty końcowe usługi uzyskane z wymagań wstępnych do pliku konfiguracji wraz z dowolnymi parametrami modelu.

Dodaj do .env pliku:

# 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 języka Python LLM

Zmienna Podpis Wymagania Przykład
OPENAI_API_KEY Klucz interfejsu API dla usługi OpenAI W przypadku interfejsu OpenAI sk-proj-...
AZURE_OPENAI_API_KEY Klucz interfejsu API dla usługi Azure OpenAI W przypadku usługi Azure OpenAI: uruchamianie a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT Adres URL punktu końcowego usługi Azure OpenAI W przypadku usługi Azure OpenAI: uruchamianie https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Nazwa wdrożenia w usłudze Azure OpenAI W przypadku usługi Azure OpenAI: uruchamianie gpt-4
AZURE_OPENAI_API_VERSION Wersja interfejsu API dla usługi Azure OpenAI W przypadku usługi Azure OpenAI: uruchamianie 2024-02-15-preview

Krok 3. Konfigurowanie wartości uwierzytelniania na potrzeby uwierzytelniania tożsamości agenta

Użyj polecenia interfejsu wiersza polecenia a365 config display A365, aby pobrać poświadczenia strategii agenta.

a365 config display -g

To polecenie wyświetla konfigurację strategii agenta. Ustaw następujące wartości:

Wartość Podpis
agentBlueprintId Identyfikator klienta agenta
agentBlueprintClientSecret Klucz tajny klienta agenta
tenantId Identyfikator dzierżawy Tożsamości Microsoft Entra.

Użyj tych wartości, aby skonfigurować uwierzytelnianie agenta w agencie:

Dodaj następujące ustawienia do .env pliku, zastępując wartości symboli zastępczych 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łączanie trybu uwierzytelniania agenta Tak true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID Identyfikator klienta strategii agenta z a365 config display -g Tak 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Wpis tajny klienta strategii agenta z a365 config display -g Tak abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID Identyfikator dzierżawy firmy Microsoft Entra z a365 config display -g Tak adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

Notatka

W przypadku platformy .NET upewnij się również, że USE_AGENTIC_AUTH=true ustawiono wartość w launchSettings.json elemencie (zobacz Krok 4: odwołanie do zmiennych środowiskowych)

Krok 2: Zmienne środowiskowe

Wykonaj konfigurację środowiska, konfigurując następujące wymagane zmienne środowiskowe:

  • Zmienne uwierzytelniania — wymagane ustawienia uwierzytelniania agenta
  • Konfiguracja punktu końcowego MCP — określanie punktu końcowego platformy Agent 365
  • Zmienne obserwacji — włączanie rejestrowania i śledzenia rozproszonego
  • Konfiguracja serwera aplikacji agenta — konfigurowanie portu, na którym działa serwer agenta

Zmienne uwierzytelniania

Skonfiguruj ustawienia programu obsługi uwierzytelniania wymagane do prawidłowego działania uwierzytelniania agenta.

Dodaj do .env pliku:

# 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 procedury obsługi uwierzytelniania Tak
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Zakresy uwierzytelniania dla programu Microsoft Graph Tak
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Nazwa połączenia alternatywnej strategii Tak
CONNECTIONSMAP_0_SERVICEURL Wzorzec adresu URL usługi na potrzeby mapowania połączeń Tak
CONNECTIONSMAP_0_CONNECTION Nazwa połączenia do mapowania Tak

Zweryfikuj konfigurację punktu końcowego:

Konfiguracja punktu końcowego MCP (Model Context Protocol) jest wymagana do określenia punktu końcowego platformy Agent 365, z którym agent powinien nawiązać połączenie. Podczas generowania manifestu narzędzi definiującego serwery narzędzi dla agenta należy określić punkt końcowy platformy MCP. Ten punkt końcowy określa, z którym środowiskiem (wstępnie, testem lub produkcją) serwery narzędzi MCP łączą się z usługą Microsoft 365 w celu uzyskania możliwości integracji z platformą Microsoft 365.

Dodaj do .env pliku:

# 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 Data zakończenia produkcji

Ważne: jeśli MCP_PLATFORM_ENDPOINT nie zostanie określony, zostanie on domyślnie ustawiony na produkcyjny punkt końcowy.

Zmienne obserwowania

Skonfiguruj te wymagane zmienne, aby włączyć rejestrowanie i rozproszone śledzenie agenta. Dowiedz się więcej o funkcjach obserwacji i najlepszych rozwiązaniach

Notatka

Konfiguracja obserwacji jest taka sama we wszystkich językach.

Zmienna Podpis Wartość domyślna Przykład
ENABLE_A365_OBSERVABILITY Włączanie/wyłączanie możliwości obserwacji false true
ENABLE_A365_OBSERVABILITY_EXPORTER Eksportowanie śladów w celu obserwowania usługi false true
OBSERVABILITY_SERVICE_NAME Nazwa usługi do śledzenia Nazwa agenta my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE Przestrzeń nazw Service Bus agent365-samples my-company-agents

Konfiguracja serwera aplikacji agenta

Skonfiguruj port, na którym działa serwer aplikacji agenta. Jest to opcjonalne i dotyczy agentów python i JavaScript.

Dodaj do .env pliku:

# 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

Instalowanie zależności i uruchamianie serwera aplikacji agenta

Po skonfigurowaniu środowiska należy zainstalować wymagane zależności i uruchomić serwer aplikacji agenta lokalnie na potrzeby testowania.

Instalacja zależności:

uv pip install -e .

To polecenie odczytuje zależności pakietu zdefiniowane w pliku pyproject.toml i instaluje je z PyPI. Podczas tworzenia aplikacji agenta od podstaw należy utworzyć pyproject.toml plik w celu zdefiniowania zależności. Przykładowi agenci z repozytorium przykładów mają już zdefiniowane te pakiety. W razie konieczności można zaktualizować, dodać lub usunąć wiersze.

Uruchamianie serwera aplikacji agenta

python <main.py>

Zastąp <main.py> ciąg nazwą głównego pliku języka Python, który zawiera punkt wejścia dla aplikacji agenta (na przykład , start_with_generic_host.py, app.pylub main.py).

Lub przy użyciu uv:

uv run python <main.py>

Serwer agenta powinien być teraz uruchomiony i gotowy do odbierania żądań z aplikacji Agent Playground lub Microsoft 365.

Agent testowy na placu zabaw agentów

Agents Playground to lokalne narzędzie do testowania, które symuluje środowisko platformy Microsoft 365 bez konieczności pełnej konfiguracji dzierżawy. Jest to najszybszy sposób weryfikacji wywołań logiki i narzędzi agenta. Aby uzyskać więcej informacji, zobacz Test with Agents Playground (Testowanie za pomocą agentów plac zabaw).

Otwórz nowy terminal (program PowerShell w systemie Windows) i uruchom narzędzie Agents Playground:

agentsplayground

Spowoduje to otwarcie przeglądarki internetowej z interfejsem Placu zabaw agentów. Narzędzie wyświetla interfejs czatu, w którym można wysyłać wiadomości do agenta.

Podstawowe testy

Zacznij od sprawdzenia, czy agent jest prawidłowo skonfigurowany. Wyślij wiadomość do agenta:

What can you do?

Agent powinien odpowiedzieć na instrukcje, z których jest skonfigurowany, na podstawie monitu systemowego i możliwości agenta. Potwierdza to, że:

  • Agent działa poprawnie
  • Agent może przetwarzać komunikaty i odpowiadać
  • Komunikacja między agentami placem zabaw i agentem działa

Wywołania narzędzi do testowania

Po skonfigurowaniu serwerów narzędzi MCP w programie toolingManifest.json (zobacz Narzędzia , aby uzyskać instrukcje dotyczące konfiguracji), wywołania narzędzi testowych z przykładami takimi jak:

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

List all tools I have access to

Następnie przetestuj wywołania określonych narzędzi:

Narzędzia poczty

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

Oczekiwana odpowiedź: agent wysyła wiadomość e-mail przy użyciu serwera MCP poczty i potwierdza, że wiadomość została wysłana.

Narzędzia kalendarza

List my calendar events for today

Oczekiwana odpowiedź: agent pobierze i wyświetli zdarzenia kalendarza dla bieżącego dnia.

Narzędzia programu SharePoint

List all SharePoint sites I have access to

Oczekiwana odpowiedź: agent wysyła zapytanie do programu SharePoint i zwraca listę witryn, do których masz dostęp.

Wywołania narzędzi można wyświetlić w:

  • Okno czatu — zobacz odpowiedź agenta i wszystkie wywołania narzędzi
  • Panel Dziennik — zobacz szczegółowe informacje o działaniu, w tym parametry narzędzia i odpowiedzi

Testowanie za pomocą działań powiadomień

Podczas programowania lokalnego można przetestować scenariusze powiadomień, symulując niestandardowe działania na placu zabaw agentów. Dzięki temu można zweryfikować obsługę powiadomień agenta przed wdrożeniem go w środowisku produkcyjnym.

Przed rozpoczęciem testowania działań powiadomień upewnij się, że masz:

Powiadomienia wymagają poprawnej konfiguracji narzędzia i konfiguracji powiadomień. Scenariusze, takie jak powiadomienia e-mail lub komentarze programu Word, można przetestować przy użyciu niestandardowej funkcji działania.

Aby wysłać działania niestandardowe:

  1. Uruchamianie agenta i agentów plac zabaw
  2. W obszarze Agent Playground przejdź do obszaru Pozorowanie działania niestandardowego działania>
  3. Skopiuj element conversationId z działania (identyfikator konwersacji zmienia się za każdym razem, gdy agentów plac zabaw jest uruchamiany ponownie)
  4. Wklej niestandardowy kod JSON działania i zaktualizuj personal-chat-id pole przy użyciu skopiowanego identyfikatora konwersacji. Zapoznaj się z przykładem powiadomienia e-mail
  5. Wybierz Dodaj działanie.
  6. Wyświetlanie wyniku zarówno konwersacji czatu, jak i panelu dziennika

Powiadomienie e-mail

Symuluje to wiadomość e-mail wysłaną do agenta. Zastąp wartości symboli zastępczych rzeczywistymi szczegółami agenta:

{
  "type": "message",
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "timestamp": "2025-09-24T17:40:19+00:00",
  "serviceUrl": "http://localhost:56150/_connector",
  "channelId": "agents",
  "name": "emailNotification",
  "from": {
    "id": "manager@contoso.com",
    "name": "Agent Manager",
    "role": "user"
  },
  "recipient": {
    "id": "agent@contoso.com",
    "name": "Agent",
    "agenticUserId": "<your-agentic-user-id>",
    "agenticAppId": "<your-agent-app-id>",
    "tenantId": "<your-tenant-id>"
  },
  "conversation": {
    "conversationType": "personal",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "id": "personal-chat-id"
  },
  "membersAdded": [],
  "membersRemoved": [],
  "reactionsAdded": [],
  "reactionsRemoved": [],
  "locale": "en-US",
  "attachments": [],
  "entities": [
    {
      "id": "email",
      "type": "productInfo"
    },
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "type": "emailNotification",
      "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "conversationId": "personal-chat-id",
      "htmlBody": "<body dir=\"ltr\">\n<div class=\"elementToProof\" style=\"font-family: Aptos, Aptos_EmbeddedFont, Aptos_MSFontService, Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\">\nYour email message content here</div>\n\n\n</body>"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
    }
  },
  "listenFor": [],
  "textHighlights": []
}

Wyświetlanie dzienników obserwacji

Aby wyświetlić dzienniki obserwacji podczas programowania lokalnego, instrumentuj agenta za pomocą kodu obserwowalnego (zobacz Możliwość obserwowania przykładów kodu) i skonfiguruj zmienne środowiskowe zgodnie z opisem w temacie Zmienne obserwacji. Po skonfigurowaniu ślady w czasie rzeczywistym są wyświetlane w konsoli z wyświetlonymi elementami:

  • Ślady wywołania agenta
  • Szczegóły wykonania
  • Wywołania wnioskowania w usłudze LLM
  • Komunikaty wejściowe i wyjściowe
  • Użycie tokenu
  • Czasy reakcji
  • Informacje o błędzie

Te dzienniki ułatwiają debugowanie problemów, zrozumienie zachowania agenta i optymalizowanie wydajności.

Rozwiązywanie problemów

Ta sekcja zawiera rozwiązania typowych problemów, które mogą wystąpić podczas lokalnego testowania agenta.

Problemy z połączeniem i środowiskiem

Te problemy dotyczą łączności sieciowej, konfliktów portów i problemów z konfiguracją środowiska, które mogą uniemożliwić agentowi prawidłową komunikację.

Problemy z połączeniem z placem zabaw agentów

Objaw: Agenci — plac zabaw nie może nawiązać połączenia z agentem

### Rozwiązanie:

  • Sprawdź, czy serwer agenta jest uruchomiony
  • Sprawdź, czy numery portów są zgodne między agentem a placem zabaw agentów
  • Upewnij się, że żadne reguły zapory sieciowej nie blokują dostępu do kontenera obiektów blob.
  • Spróbuj ponownie uruchomić agenta i agenta playground

Nieaktualna wersja placu zabaw agentów

Objaw: Nieoczekiwane błędy lub brakujące funkcje na placu zabaw agentów

Rozwiązanie: Odinstaluj i zainstaluj ponownie agentów Plac zabaw:

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 wystąpienia agenta
  • Zmienianie portu w konfiguracji
  • Zabij wszystkie procesy przy użyciu portu:
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

Nie można dodać serwera DeveloperMCPServer

Objaw: Błąd podczas próby dodania serwera DeveloperMCPServer w programie VS Code

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

Problemy z uwierzytelnianiem

Te problemy występują, gdy agent nie może prawidłowo uwierzytelnić się w usługach platformy Microsoft 365 lub gdy poświadczenia wygasły lub nieprawidłowo skonfigurowane.

Token elementu nośnego wygasł

Objaw: Błędy uwierzytelniania lub 401 Nieautoryzowane odpowiedzi

Rozwiązanie: tokeny elementu nośnego wygasają po około 1 godzinie. Uzyskaj nowy token i zaktualizuj konfigurację.

Błędy uwierzytelniania agenta w języku Python

Objaw: Błąd podczas uzyskiwania tokenu wystąpienia agenta

Rozwiązanie: Sprawdź ALT_BLUEPRINT_NAME ustawienie w pliku .env:

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

Znane problemy i powiadomienia

Te problemy obejmują problemy z wywołaniami narzędzi, interakcjami z serwerem MCP i dostarczaniem powiadomień.

Nie odebrano wiadomości e-mail

Objaw: Agent wskazuje, że wiadomość e-mail została wysłana, ale nie otrzymasz jej

### Rozwiązanie:

  • Sprawdź, czy wiadomość e-mail nie trafiła do folderu spamu/wiadomości-śmieci.
  • Dostarczanie wiadomości e-mail może być opóźnione o kilka minut — poczekaj do 5 minut
  • Sprawdź, czy adres e-mail jest poprawny.
  • Sprawdzanie dzienników agenta pod kątem błędów podczas wysyłania wiadomości e-mail

Odpowiedzi komentarza programu Word nie działają

Znany problem: usługa powiadomień obecnie nie może odpowiedzieć bezpośrednio na komentarze programu Word. Ta funkcja jest opracowywana.

Uzyskiwanie pomocy

Jeśli napotkasz problemy, które nie zostały omówione w tej sekcji rozwiązywania problemów, zapoznaj się z następującymi zasobami:

Repozytoria zestawu MICROSOFT Agent 365 SDK

Więcej pomocy technicznej

Następne kroki

Po pomyślnym przetestowaniu agenta lokalnie możesz przystąpić do wdrażania go na platformie Azure i publikowania go na platformie Microsoft 365:

  • Wdrażanie i publikowanie agentów: dowiedz się, jak wdrożyć agenta w aplikacji internetowej platformy Azure i opublikować go w Centrum administracyjnym firmy Microsoft, udostępniając go organizacji w celu odnajdywania i zatrudniania na platformie Microsoft 365.
  • Last updated on