Automatyzacja przeglądarek za pomocą zdalnego serwera MCP Playwright Workspaces

Important

Zdalny serwer protokołu Model Context Protocol (MCP) dla Playwright Workspaces jest dostępny w wersji zapoznawczej. Funkcje w wersji zapoznawczej nie są objęte umową SLA i nie są zalecane w obciążeniach produkcyjnych. Funkcje, ograniczenia i dostępność mogą się zmieniać.

Zdalny serwer MCP Playwright Workspaces zapewnia agentom AI zarządzaną zdalną przeglądarkę oraz zestaw narzędzi do automatyzacji przeglądarki. Agent może otworzyć sesję przeglądarki, nawigować po stronach, znaleźć i wchodzić w interakcje z elementami, sprawdzać aktywność przeglądarki, robić zrzuty ekranu i zamykać sesję. Nie musisz instalować Playwrighta ani przeglądarki w środowisku agenta.

Serwer korzysta z Model Context Protocol zamiast Streamable HTTP. Współpracuje z klientami MCP obsługującymi zdalne serwery HTTP oraz niestandardowe nagłówki uwierzytelniania, w tym Microsoft Foundry Agent Service oraz Visual Studio Code.

W tym artykule dowiesz się, jak:

  • Zbuduj endpoint MCP dla przestrzeni roboczej Playwright.
  • Połącz serwer z usługą Microsoft Foundry Agent Service lub Visual Studio Code.
  • Uruchamiaj kompletne przepływy automatyzacji przeglądarki opartych na agentach.
  • Wybierz i bezpiecznie korzystaj z dostępnych narzędzi przeglądarkowych.

Wymagania wstępne

Przed rozpoczęciem upewnij się, że masz następujące elementy:

  • Konto platformy Azure z aktywną subskrypcją.
  • Identyfikator przestrzeni roboczej i region platformy Azure tej przestrzeni roboczej.
  • Token dostępu do przestrzeni roboczej, którego właściciel ma uprawnienia do tworzenia i korzystania z sesji przeglądarki.
  • Dla Microsoft Foundry, projekt Foundry oraz uprawnienia do tworzenia połączeń projektów i konfigurowania agentów.
  • W przypadku programu Visual Studio Code: aktualna wersja programu Visual Studio Code z dostępem do GitHub Copilot i włączoną obsługą MCP.

Caution

Microsoft Entra ID to zalecana metoda uwierzytelniania dla Playwright Workspaces. Ten artykuł podglądowy wykorzystuje uwierzytelnianie tokenów dostępu w przestrzeni roboczej dla klientów, którzy potrzebują niestandardowego nagłówka. Tokeny dostępu są mniej bezpieczne i domyślnie wyłączone. Traktuj token dostępu jak hasło. Nigdy nie zatwierdzaj tego w systemie kontroli wersji, nie umieszczaj tego w prompcie ani nie zapisuj tego w logach.

Aby utworzyć token dostępu do przestrzeni roboczej, zobacz Zarządzaj tokenami dostępu do przestrzeni roboczej.

Zbuduj zdalny punkt końcowy MCP

Punkt końcowy jest ograniczony do jednej przestrzeni roboczej i regionu:

https://<region>.mcp.playwright.microsoft.com/playwrightworkspaces/<workspace-id>/mcp

Replace:

  • "region" z regionem Azure w przestrzeni roboczej.
  • "workspace-id" z identyfikatorem workspace wyświetlanym w portalu Azure.

Przykład:

https://eastus.mcp.playwright.microsoft.com/playwrightworkspaces/00000000-0000-0000-0000-000000000000/mcp

Wartość w nagłówku żądania klucza x-API musi być tokenem dostępu utworzonym dla tej samej przestrzeni roboczej co "workspace-id". Użyj punktu końcowego dla regionu przestrzeni roboczej, a nie regionu najbliższego klientowi MCP.

Zrozum cykl życia sesji przeglądarki

Przepływ automatyzacji przeglądarki składa się z trzech etapów:

  1. Zadzwoń do create_browser_session. Wynik zawiera niejawny browserSessionId i może zawierać adres URL widoku na żywo.
  2. Przekaż to browserSessionId każdemu narzędziu przeglądarki używanemu w tym przepływie.
  3. Wywołaj close_browser_session w kroku czyszczenia, nawet jeśli przepływ się nie powiedzie.

Transport HTTP MCP nie zachowuje stanu przeglądarki. browserSessionId identyfikuje zdalną przeglądarkę w ramach oddzielnych wywołań narzędzia. Zachowaj to w tajemnicy i używaj tylko z przestrzenią roboczą i tożsamością, która ją stworzyła.

Obecne zachowanie podglądu obejmuje następujące ograniczenia:

  • Sesja należy do jej twórcy i nie może być współdzielona z innym podmiotem.
  • Połączenia na jedną sesję są przetwarzane w kolejności. Nie wnosz jednoczesnych działań przeciwko tej samej sesji.
  • Nieaktywna sesja jest sprzątana po 15 minutach, jeśli wyraźnie nie jest zamknięta.
  • Zamknięta lub wygasła sesja nie może zostać ponownie otworzyta.
  • Utrata połączenia jest kluczowa dla sesji. Stwórz nową sesję, aby kontynuować.
  • Wynik może zawierać element liveViewUrl. Dostępność trybu na żywo zależy od sesji.

Połącz się z usługą agenta Microsoft Foundry

Użyj połączenia projektu Foundry do przechowywania tokena dostępu. Nie umieszczaj tokena w instrukcjach agenta ani kodzie aplikacji.

Utwórz połączenie projektu

  1. Otwórz swój projekt w portalu Microsoft Foundry.
  2. Otwórz doświadczenie zarządzania projektem, a następnie wybierz Połączone zasoby.
  3. Utwórz połączenie typu Klucze niestandardowe.
  4. Wprowadź opisową nazwę połączenia, taką jak playwright-mcp-connection.
  5. Dodaj klucz o nazwie x-api-key i ustaw jego wartość na token dostępu do przestrzeni roboczej Playwright.
  6. Zapisz połączenie.

Dodaj zdalne narzędzie MCP

  1. Stwórz lub otwórz agenta w portalu Foundry.

  2. Dodaj zdalny serwer MCP lub narzędzie MCP.

  3. Użyj następujących ustawień:

    Setting Value
    Etykieta serwera Unikalna etykieta, taka jak playwrightWorkspace
    Adres URL serwera Zdalny punkt końcowy MCP w zakresie obszaru roboczego
    Połączenie projektu Wcześniej utworzone połączenie kluczy niestandardowych
    Approval Wymagaj zatwierdzenia każdego połączenia podczas oceny integracji
    Dozwolone narzędzia Zacznij tylko od narzędzi potrzebnych do przepływu

  4. Zapisz konfigurację agenta.

  5. W instrukcjach agenta wymaga, aby agent utworzył jedną sesję, ponownie użył swojego browserSessionId i zamknął sesję po zakończeniu zadania.

Minimalna lista dozwolonych narzędzi dla przepływu nawigacji ukierunkowanego na odczyt to:

  • create_browser_session
  • browser_navigate
  • migawka_przeglądarki
  • browser_find
  • browser_zrób_zrzut_ekranu
  • close_browser_session

Narzędzia interakcji, takie jak browser_click czy browser_type, dodaj tylko wtedy, gdy sytuacja ich wymaga. Nie włączaj browser_evaluate ani browser_run_code domyślnie.

Informacje o bieżących polach połączeń usługi Foundry, obsłudze zatwierdzania, przykładach SDK oraz limitach klientów można znaleźć w artykule Łączenie agentów z punktami końcowymi serwera MCP.

Note

Wywołania narzędzi MCP w Foundry, które nie korzystają ze strumieniowania, mają obecnie 100-sekundowy limit czasu po stronie klienta. Niektóre operacje w Playwright mają dłuższy limit czasu po stronie usługi. Utrzymuj ukierunkowane operacje Foundry i dziel długie procesy na kilka wywołań narzędzi.

Zaprojektuj przepływ automatyzacji agentycznej

Zamiast prosić agenta o wykonanie długiej sekwencji bez sprawdzania stanu strony, stosuj pętlę obserwacji-działaj-weryfikuj.

  1. Utwórz: Wywołaj create_browser_session i zachowaj jego browserSessionId.
  2. Nawigacja: Zadzwoń browser_navigate za pomocą wyraźnego, zatwierdzonego adresu URL.
  3. Zwróć uwagę: Użyj browser_find, aby przeprowadzić ukierunkowane wyszukiwanie, lub browser_snapshot, aby uzyskać szerszy przegląd dostępności.
  4. Działanie: Użyj odwołania do migawki lub unikalnego selektora za pomocą narzędzia interakcji.
  5. Czekaj: Wywołaj browser_wait_for na oczekiwany tekst, znikający tekst lub ograniczone opóźnienie.
  6. Sprawdź: Zrób kolejne zdjęcie lub sprawdź aktywność konsoli i sieci.
  7. Obsługa gałęzi: Obsługa dialogu, przełączanie zakładek lub przesyłanie plików tylko wtedy, gdy stan strony tego wymaga.
  8. Zbierz dowody: Wywołaj browser_take_screenshot, jeśli wynik wizualny jest przydatny. Nie używaj zrzutów ekranu do wybierania celów akcji.
  9. Czyszczenie: Wywołaj close_browser_session w ścieżce czyszczenia typu finally.

Wybierz stabilne cele akcji

Preferuj odniesienia zwracane przez browser_snapshot lub browser_find. Opisują one dostępne elementy strony i zmniejszają zależność od znaczników specyficznych dla implementacji. Używaj unikalnego selektora, gdy stabilna referencja migawki nie jest dostępna.

Odśwież zrzut po nawigacji lub po wykonaniu działania zmieniającego stronę. Wcześniej zwrócony element docelowy może stać się nieaktualny, gdy strona jest renderowana ponownie.

Bezpiecznie obsługuj dialogi

Akcja może zwrócić wynik dialog-opened po uprzedniej zmianie stanu strony. Ten rezultat nie jest typową porażką działania.

  1. Nie powtarzaj oryginalnej akcji.
  2. Wywołaj browser_handle_dialog, ustawiając accept na true lub false.
  3. W dialogu promptowym dodaj tylko promptText podczas jego przyjmowania.
  4. Przed kontynuacją jeszcze raz obejrzyj stronę.

Radzenie sobie z niejednoznacznymi błędami

Przekroczenie limitu czasu lub rozłączenie przez dzwoniącego nie dowodzi, że dane działanie nie odniosło skutku. Przed ponownym podjęciem próby operacji nieidempotentnej, takiej jak kliknięcie, wysłanie formularza, przesłanie czy wykonanie kodu:

  1. Uruchom browser_snapshot, browser_find lub inne narzędzie do obserwacji, jeśli sesja jest nadal dostępna.
  2. Określ, czy nastąpiła oczekiwana zmiana stanu.
  3. Spróbuj ponownie tylko wtedy, gdy powtarzanie czynności jest bezpieczne.
  4. Jeśli sesja wygasła, utwórz nową sesję i zrestartuj od znanego stanu aplikacji.

Dokumentacja narzędzia

Wszystkie narzędzia ograniczone do przeglądarki wymagają browserSessionId. Pokazane tutaj limity dla ciągów i kolekcji to bieżące limity wersji zapoznawczej.

Narzędzia sesyjne

Tool Parameters Użyj
create_browser_session Żadne Tworzy zdalną przeglądarkę i zwraca browserSessionId oraz opcjonalnie liveViewUrl.
close_browser_session browserSessionId Zamyka zdalną sesję przeglądarki. Zgłoszcie to podczas sprzątania.
Tool Parameters Zastosowanie i ważne zachowania
browser_navigate browserSessionId, url Przechodzi do adresu URL. URL może zawierać do 16 KiB znaków.
browser_navigate_back browserSessionId Przechodzi do poprzedniego wpisu w historii strony.
browser_snapshot browserSessionId; opcjonalnie target, depthboxes Zwraca zrzut stanu dostępności. Cel akceptuje referencję migawkową lub unikalny selektor. Głębokość to 1-100. Pola zawierają dane ramek ograniczających, jeśli jest to obsługiwane. Tekst migawki jest skracany do 64 KiB i oznaczony jako obcięty.
browser_find browserSessionId, text Wykonuje wyszukiwanie fragmentów tekstu w migawce dostępności bez rozróżniania wielkości liter i zwraca pasujące fragmenty. Tekst może zawierać do 4 096 znaków.
browser_wait_for browserSessionId; dokładnie jeden z text, textGone, lub time Czeka na tekst, czeka, aż tekst zniknie, albo czeka od 0 do 180 sekund.
browser_take_screenshot browserSessionId; opcjonalnie target, type, fullPagescale Zwraca osadzony obraz PNG lub JPEG. Typ to png lub jpeg. FullPage przechwytuje całą stronę zamiast domyślnego viewportu. Skala: CSS lub device. Użyj migawki, a nie obrazu, aby wybrać cele.
browser_console_messages browserSessionId Zwraca ograniczone komunikaty konsolowe przechwycone dla aktywnej strony.
browser_network_requests browserSessionId Zwraca ograniczone informacje o żądaniu sieciowym przechwycone dla aktywnej strony.

Narzędzia interakcji

Tool Parameters Zastosowanie i ważne zachowania
browser_click browserSessionId, target; opcjonalnie button, doubleClick, modifiers Klika w cel. Przycisk jest lewy, prawy lub środkowy. Akceptuje do pięciu modyfikatorów od Alt, Control, ControlOrMeta, Meta i Shift. Nie ponawiaj bezrefleksyjnie kliknięcia, które przekroczyło limit czasu.
browser_type browserSessionId, target, ; textopcjonalnie submit, slowly Wprowadza tekst w elementie edytowalnym. Po naciśnięciu „Submit” naciśnij następnie klawisz Enter. Powoli pisze sekwencyjnie.
browser_fill_form browserSessionId, fields Wypełnia od 1 do 50 pól. Każde pole zawiera cel, ciąg lub wartość boolowską oraz opcjonalną nazwę i typ. Awaria może pozostawić wcześniejsze pola zaktualizowane.
browser_press_key browserSessionId, key Naciska deskryptor klawisza Playwright, taki jak Enter, ArrowLeft lub Control+C.
browser_select_option browserSessionId, target, values Wybiera wartości opcji od 1 do 100. Każda wartość może zawierać do 4 096 znaków.
browser_hover browserSessionId, target Najeżdża na element docelowy, co może wyświetlić menu lub etykietki narzędzi.
browser_handle_dialog browserSessionId, accept; opcjonalnie promptText Akceptuje lub zamyka aktualnie blokujące okno dialogowe przeglądarki.
browser_drag browserSessionId, startTarget, endTarget Przeciąganie z jednego elementu docelowego do drugiego. Oba cele muszą się rozstrzygnąć na aktywnej stronie.

Zakładki, pliki i narzędzia do kodowania

Tool Parameters Zastosowanie i ważne zachowania
browser_tabs browserSessionId, action; opcjonalnie index, url Listuje, tworzy, wybiera lub zamyka zakładki. action jest list, new, select lub close. index jest wymagane w przypadku select; w przypadku close pominięcie oznacza aktywną kartę. Indeksy są numerowane od zera.
browser_file_upload browserSessionId, files; opcjonalnie target Przesyła od 1 do 20 plików zakodowanych w formacie base64 za pośrednictwem docelowego pola wyboru pliku lub oczekującego okna wyboru plików. Zobacz limity przesyłania plików.
browser_evaluate browserSessionId, function; opcjonalnie target Ocenia funkcję JavaScript na stronie lub w odniesieniu do celu. Może odczytać lub zmieniać stan strony.
browser_run_code browserSessionId, code Uruchamia funkcję Playwright JavaScript z dostępem do strony. To narzędzie ma najwyższe przywileje i może powodować dowolne skutki uboczne.

Czyszczenie

Po każdym etapie automatyzacji:

  1. Połącz close_browser_session używając aktywnego browserSessionId.
  2. Usuń agentów testowych lub powiązania projektów, których nie potrzebujesz.
  3. Cofnij tymczasowe tokeny dostępu do przestrzeni roboczej.
  4. W Visual Studio Code zatrzymaj lub usuń serwer MCP, jeśli połączenie już nie jest potrzebne.

Zamknięcie sesji szybko zwalnia pojemność przeglądarki i zmniejsza ryzyko nieoczekiwanej aktywności lub wykorzystania limitów.

Treści powiązane

  • Last updated on