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

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

• Edytor kodu: dowolny wybrany edytor kodu. Zalecany jest program Visual Studio Code
• Plac zabaw dla agentów: Zainstaluj agentów plac zabaw przy użyciu jednej z następujących metod:
  • Windows: winget install agentsplayground
  • npm
• Interfejs wiersza polecenia A365: wymagany do wdrożenia agenta i zarządzania nim. Instalowanie interfejsu wiersza polecenia agenta 365
• Dostęp do interfejsu API LLM: wybierz odpowiednią usługę na podstawie konfiguracji agenta lub preferowanego dostawcy modelu:
  • Klucz interfejsu API interfejsu OpenAI: uzyskiwanie klucza interfejsu API OpenAI
  • Azure OpenAI: tworzenie i wdrażanie zasobu usługi Azure OpenAI w celu uzyskania klucza interfejsu API i punktu końcowego

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

cp .env.template .env

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.

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

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

{
  "AIServices": {
    "AzureOpenAI": {
      "DeploymentName": "", // Deployment (as opposed to model) name of the Azure OpenAI model
      "Endpoint": "", // Endpoint of the Azure OpenAI model deployment
      "ApiKey": "" // API Key of the Azure OpenAI model deployment
    },
    "OpenAI": {
      "ModelId": "", // Model ID of the OpenAI model
      "ApiKey": "" // API Key of the OpenAI model
    },
    "UseAzureOpenAI": true // Flag to use Azure OpenAI vs OpenAI
  }
}

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:

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

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>

USE_AGENTIC_AUTH=true
connections__service_connection__settings__clientId=<agentBlueprintId>
connections__service_connection__settings__clientSecret=<agentBlueprintClientSecret>
connections__service_connection__settings__tenantId=<your-tenant-id>

{
  "AgentBluePrint": {
    "Settings": {
      "ClientId": "<agentBlueprintId>",
      "ClientSecret": "<agentBlueprintClientSecret>",
      "TenantId": "<your-tenant-id>"
    }
  }
}

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.

# 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

# Agentic Authentication Options
agentic_type=agentic
agentic_altBlueprintConnectionName=service_connection
agentic_scopes=ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/.default

# Set service connection as default
connectionsMap__0__serviceUrl=*
connectionsMap__0__connection=service_connection

{
  "AgentApplication": {
    "StartTypingTimer": false,
    "RemoveRecipientMention": false,
    "NormalizeMentions": false,
    "UserAuthorization": {
      "AutoSignin": false,
      "Handlers": {
        "agentic": {
          "Type": "AgenticUserAuthorization",
          "Settings": {
            "Scopes": [
              "https://graph.microsoft.com/.default"
            ]
          }
        }
      }
    }
  },
  "ConnectionsMap": [
    {
      "ServiceUrl": "*",
      "Connection": "ServiceConnection"
    }
  ]
}

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.

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>

{
  "profiles": {
    "Sample Agent with MCP Platform": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "USE_AGENTIC_AUTH": "false",
        "MCP_PLATFORM_ENDPOINT": "<MCP endpoint>"
      },
      "applicationUrl": "https://localhost:64896;http://localhost:64897"
    }
  }
}

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

Konfiguracja serwera aplikacji agenta

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

# Server Configuration
PORT=3978

# Server Configuration
PORT=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 .

python <main.py>

uv run python <main.py>

npm install

npm run dev

dotnet restore

dotnet build

dotnet run --launch-profile "Sample Agent with MCP Platform"

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:

• Skonfigurowano wymagane serwery narzędzi MCP w systemie toolingManifest.json. Dowiedz się więcej o narzędziach
• Powiadomienia włączone dla agenta Dowiedz się, jak skonfigurować powiadomienie

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

• Zestaw SDK programu Microsoft Agent 365 — repozytorium C# /.NET
• Zestaw MICROSOFT Agent 365 SDK — repozytorium języka Python
• Microsoft Agent 365 SDK — repozytorium Node.js/TypeScript
• Repozytorium przykładów zestawu MICROSOFT Agent 365 SDK

Więcej pomocy technicznej

• Przejrzyj przykładowy kod i dokumentację w repozytoriach zestawu MICROSOFT Agent 365 SDK
• Przesyłanie problemów za pośrednictwem usługi GitHub Issues w odpowiednim repozytorium

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.