Automatisera webbläsare med Arbetsutrymmen för dramatiker fjärrservern MCP

Arbetsutrymmen för dramatiker fjärrservern MCP ger AI-agenter en hanterad fjärrwebbläsare och en uppsättning verktyg för webbläsarautomatisering. En agent kan öppna en webbläsarsession, navigera bland sidor, hitta och interagera med element, inspektera webbläsaraktivitet, ta skärmdumpar och stänga sessionen. Du behöver inte installera Playwright eller en webbläsare i agentmiljön.

Servern använder Model Context Protocol över strömbärbar HTTP. Den stöder Microsoft Entra ID-autentisering och åtkomsttoken för arbetsutrymmen. Den fungerar med fjärrklienter för MCP, inklusive Microsoft Foundry Agent Service och Visual Studio Code.

I den här artikeln lär du dig att:

• Bygg MCP-endpointen för en Playwright-arbetsyta.
• Autentisera genom att använda Microsoft Entra ID eller en åtkomsttoken för arbetsområdet.
• Koppla servern till Microsoft Foundry Agent Service eller Visual Studio Code.
• Kör kompletta agentiska webbläsarautomatiseringsflöden.
• Välj och använd säkert de tillgängliga webbläsarverktygen.
• Hantera utgångna sessioner, tidsgränser och andra vanliga fel.

Förutsättningar

Innan du kan börja bör du kontrollera att du har:

• Ett Azure-konto med en aktiv prenumeration.
• Ett Playwright-arbetsområde som har tillgång till den fjärrstyrda MCP-förhandsvisningen.
• Arbetsområdets ID och Azure-region.
• En identitet med behörighet att skapa och använda webbläsarsessioner i arbetsytan.
• För Microsoft Foundry, ett Foundry-projekt och behörighet att skapa projektanslutningar och konfigurera agenter.
• För Visual Studio Code, en aktuell version av Visual Studio Code med GitHub Copilot-åtkomst och MCP-stöd aktiverat.

Välj en autentiseringsmetod

Använd Microsoft Entra ID när din MCP-klient stödjer OAuth eller managed identity. Den fjärrstyrda MCP-servern använder denna resursidentifierare och delegerade omfattning:

Resource: https://mcp.playwright.microsoft.com
Scope: https://mcp.playwright.microsoft.com/Playwright.Mcp.Tools

Servern publicerar OAuth-metadata för skyddade resurser. Klienter som har stöd för OAuth-identifiering, inklusive Visual Studio Code, kan identifiera auktorisationsservern och det nödvändiga behörighetsomfånget från den arbetsyteavgränsade MCP-slutpunkten. Den inloggade identiteten måste ha tillgång till Playwrights arbetsyta via Azure rollbaserad åtkomstkontroll (RBAC).

Skapa en åtkomsttoken för arbetsområdet för kompatibilitet

Hoppa över denna sektion när du använder Microsoft Entra ID. Om åtkomsttoken-autentisering inte redan är aktiverad för arbetsytan:

1. Logga in på Azure-portalen.
2. Öppna din Playwright-arbetsplats.
3. Under Inställningar, välj Åtkomsthantering.
4. Aktivera Playwright Service Access Token.
5. Välj Generera token.
6. Ange ett namn och utgångsdatum och generera sedan token.
7. Kopiera token omedelbart. Du kan inte återfå dess värde senare.

Lagra token i en hanterad hemlig lagring eller i den säkra inloggningsfunktionen som tillhandahålls av din MCP-klient. Återkalla och ersätta den om den kan ha varit exponerad. För att skapa en åtkomsttoken för arbetsytan, se Hantera åtkomsttoken för arbetsytan.

Bygg den fjärrstyrda MCP-endpointen

Slutpunkten är begränsad till en arbetsyta och region:

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

Replace:

• <region> med arbetsytans Azure-region.
• <workspace-id> med det arbetsyte-ID som visas i Azure-portalen.

Ett exempel:

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

Värdet i begärandehuvudet x-api-key måste vara en åtkomsttoken som har skapats för samma arbetsyta som <workspace-id>. Använd endpointen för arbetsytans region, inte den region som ligger närmast MCP-klienten.

Förstå webbläsarens sessionslivscykel

Ett webbläsarautomatiseringsflöde har tre steg:

1. Ringa create_browser_session. Resultatet innehåller en ogenomskinlig browserSessionId och kan innehålla en live-view-URL.
2. Skicka det browserSessionId till alla webbläsarverktyg som används i flödet.
3. Anropa close_browser_session i ett rensningssteg, även om flödet misslyckas.

MCP HTTP-transporten bevarar inte webbläsarens tillstånd. browserSessionId identifierar fjärrwebbläsaren mellan separata verktygsanrop. Håll det privat och använd det endast med den arbetsyta och identitet som skapade det.

Nuvarande förhandsgranskningsbeteende inkluderar dessa begränsningar:

• En session tillhör sin skapare och kan inte delas med en annan rektor.
• Samtal i en session behandlas i ordning. Vidta inte samtidiga åtgärder mot samma session.
• En inaktiv session städas upp efter 15 minuter. Tydlig sanering krävs.
• En sluten eller utgången session kan inte öppnas igen.
• Om anslutningen bryts avslutas sessionen. Skapa en ny session för att fortsätta.
• Ett resultat kan innehålla en liveViewUrl. Tillgängligheten för live-visning beror på sessionen.

Koppla upp dig från Microsoft Foundry Agent Service

Använd Microsoft Entra Agent Identity för att autentisera agenten med Foundry-projektets hanterade identitet. Ge den identiteten tillgång till Playwright-arbetsytan innan du kopplar in MCP-verktyget.

Skapa projektanslutningen

1. Öppna ditt projekt i Microsoft Foundry-portalen.
2. Öppna projektets hanteringsvy och välj sedan Anslutna resurser.
3. Skapa en anslutning för en fjärr-MCP-server.
4. Ange ett beskrivande kopplingsnamn, såsom playwright-mcp-connection.
5. Välj Microsoft Entra Agent Identity som autentiseringsmetod.
6. Ange https://mcp.playwright.microsoft.com som målgrupp.
7. Spara anslutningen.

Projektets hanterade identitet måste ha en roll som tillåter webbläsarsessionsoperationer på det målinriktade Playwright-arbetsytet. Använd inte en identitetstoken från ett projekt som en delad hemlighet i ett annat projekt.

Om Microsoft Entra Agent Identity inte är tillgänglig för klienten eller miljön, skapa en Custom Keys-anslutning med en nyckel som heter x-api-key och en åtkomsttoken för arbetsområdet som dess värde.

Lägg till fjärr-MCP-verktyget

1. Skapa eller öppna en agent i Foundry-portalen.

2. Lägg till en fjärr-MCP-server eller MCP-verktyg.

3. Använd följande inställningar:

   Setting	Value
   Serveretikett	En unik etikett, såsom playwrightWorkspace
   Server-URL	Den arbetsytespecifika fjärr-MCP-ändpunkten
   Projektanslutning	Microsoft Entra Agent Identity-anslutningen som skapades tidigare
   Approval	Kräv godkännande för varje samtal när du utvärderar integrationen
   Tillåtna verktyg	Börja med bara de verktyg som behövs för flödet

4. Spara agentkonfigurationen.

5. I agentinstruktionerna krävs att agenten skapar en session, återanvänder dess browserSessionId, och stänger sessionen när uppgiften är klar.

En minimal verktygslista för tillåtelse av ett läsorienterat navigeringsflöde är:

create_browser_session
browser_navigate
browser_snapshot
browser_find
browser_take_screenshot
close_browser_session

Lägg till interaktionsverktyg som browser_click eller browser_type endast när scenariot kräver det. Aktivera inte browser_evaluate eller browser_run_code som standard.

Testa gjuteriets flöde

Använd en prompt som anger målet och saneringskravet. Ett exempel:

Create a browser session, open https://example.com, inspect the page snapshot,
report the main heading and destination URL, and close the browser session.
Always close the session, including when a browser step fails.

När agenten begär godkännande:

1. Verifiera att serveretiketten är den konfigurerade Playwright-servern.
2. Gå igenom verktygets namn och alla argument, särskilt URL:er, väljare, text, uppladdad data och kod.
3. Godkänn endast den förväntade operationen.
4. Kontrollera att det slutgiltiga svaret baseras på sidresultatet.
5. Bekräfta att flödet kallades close_browser_session.

För aktuella Foundry-anslutningsfält, godkännandehantering, SDK-exempel och klientgränser, se Koppla agenter till MCP-serverns ändpunkter.

Ansluta från Visual Studio Code

Visual Studio Code kan upptäcka fjärrserverns OAuth-konfiguration och logga in dig med Microsoft Entra ID. Konfigurationen behöver endast den arbetsytsbegränsade ändpunkten.

1. I Visual Studio Code, kör MCP: Open User Configuration från kommandopaletten.
2. Lägg till följande konfiguration och byt ut slutpunktsplatshållarna.

{
  "servers": {
    "playwrightWorkspace": {
      "type": "http",
      "url": "https://<region>.mcp.playwright.microsoft.com/playwrightworkspaces/<workspace-id>/mcp"
    }
  }
}

3. Starta servern från konfigurationsredigeraren eller kör MCP: List Servers.
4. När du blir tillfrågad, logga in med det Microsoft Entra-konto som har tillgång till Playwrights arbetsyta.
5. Godkänn det begärda Playwright.Mcp.Tools tillståndet om samtycke krävs för din hyresgäst.
6. Gå igenom serverns URL och konfiguration, och bekräfta sedan att du litar på servern.
7. Öppna chatten och välj Konfigurera verktyg. Aktivera endast de verktyg som dramatikern behöver för uppgiften.
8. Kör exempelprompten från föregående Foundry-sektion.
9. Gå igenom verktygsbekräftelser och verifiera att sessionen är avslutad i slutet.

Använd en användarkonfiguration när anslutningen är personlig. En arbetsytskonfiguration som endast innehåller slutpunkten kan delas. Visual Studio Code cachar OAuth-uppgifterna säkert och kan återanvända dem vid återanslutning.

Om Microsoft Entra-autentisering inte är tillgänglig i klientmiljön konfigurerar du ett x-api-key-huvud med skyddad indata enligt beskrivningen i MCP-konfigurationsindata. Sätt aldrig workspace access-token-värdet direkt i mcp.json.

För konfigurationsplatser, hemliga indata, serverförtroende och diagnostik, se Add and manage MCP-servrar i Visual Studio Code och MCP-konfigurationsreferensen.

Designa ett agentiskt automationsflöde

Använd en observera–agera–verifiera-loop i stället för att be agenten utföra en lång sekvens utan att kontrollera sidans tillstånd.

1. Skapa: Anropa create_browser_session och behåll dess browserSessionId.
2. Navigera: Ringbrowser_navigate med en explicit, godkänd URL.
3. Observera: Kräv browser_find en fokuserad sökning eller browser_snapshot en bredare tillgänglighetsbild.
4. Agera: Använd en snapshot-referens eller unik väljare med ett interaktionsverktyg.
5. Vänta: Anropa browser_wait_for för förväntad text, försvinnande text eller en begränsad fördröjning.
6. Verifiera: Ta en annan ögonblicksbild eller inspektera konsol- och nätverksaktivitet.
7. Hantera förgreningar: Hantera en dialog, byt flik eller ladda upp filer endast när sidans tillstånd kräver det.
8. Fånga bevis: Ring browser_take_screenshot om ett visuellt resultat är användbart. Använd inte skärmdumpar för att välja actionmål.
9. Rensa upp: Anropa close_browser_session i en rensningssökväg av finally-typ.

Välj stabila aktionsmål

Föredra referenser som returneras av browser_snapshot eller browser_find. De beskriver tillgängliga sidelement och minskar beroendet av implementationsspecifik markering. Använd en unik selector när en stabil snapshot-referens inte finns tillgänglig.

Uppdatera ögonblicksbilden efter navigering eller efter en åtgärd som ändrar sidan. Ett tidigare returnerat målobjekt kan bli inaktuellt när sidan renderas om.

Hantera dialoger säkert

En åtgärd kan returnera ett dialog-opened utfall efter att den redan har ändrat sidtillståndet. Det här resultatet är inte ett vanligt åtgärdsfel.

1. Upprepa inte den ursprungliga handlingen.
2. Ring browser_handle_dialog med accept inställd på true eller false.
3. För en promptdialog, inkludera promptText endast när du accepterar den.
4. Titta på sidan igen innan du fortsätter.

Hantera otydliga fel

En timeout eller en frånkopplad uppringare bevisar inte att en åtgärd inte hade någon effekt. Innan du försöker igen en icke-idempotent operation som klick, formulärinlämning, uppladdning eller kodexekvering:

1. Använd browser_snapshot, browser_find eller något annat observationsverktyg om sessionen fortfarande är tillgänglig.
2. Ta reda på om den förväntade statusändringen har inträffat.
3. Försök om endast om det är säkert att upprepa handlingen.
4. Om sessionen har gått ut, skapa en ny session och starta om från ett känt applikationstillstånd.

Verktygsreferens

Alla webbläsarbaserade verktyg kräver browserSessionId. Sträng- och samlingsgränser som visas här är aktuella förhandsgranskningsgränser.

Sessionsverktyg

Navigations- och observationsverktyg

Interaktionsverktyg

Flikar, filer och kodverktyg

Efter varje automatiseringsarbetsflöde anropar du close_browser_session med den aktiva browserSessionId.

Formfältets form

Varje browser_fill_form fält har denna form:

{
  "target": "<snapshot-reference-or-selector>",
  "value": "<string-or-boolean>",
  "name": "<optional-display-name>",
  "type": "<optional-field-type>"
}

Strängvärdet för ett fält kan innehålla högst 100 KiB tecken. name kan innehålla högst 1 024 tecken och type kan innehålla högst 128 tecken.

Filuppladdningsform

Varje browser_file_upload fil använder denna form:

{
  "name": "example.txt",
  "data": "SGVsbG8sIHdvcmxkIQ==",
  "mimeType": "text/plain"
}

mimeType är valfritt och standardvärdet application/octet-streamär .

Filuppladdningsbegränsningar

• 1–20 filer per verktygsanrop.
• 10 MiB maximal avkodad storlek för varje fil.
• 50 MiB maximal sammanlagd avkodad storlek.
• Filnamn på maximalt 4 096 tecken.
• 1 024 tecken maximal MIME-typ.
• Giltig base64-data krävs.

JavaScript-verktygsformer

För browser_evaluate, ange ett funktionsuttryck:

() => document.title

När du tillhandahåller target, får funktionen det matchande elementet:

element => element.textContent

För browser_run_code, pass-satser som utgör funktionskroppen i en asynkron funktion med en Playwright-sida som page-parameter. Returnera endast data som kan serialiseras med JSON och håll det inom gränsen för inline-svar.

Gränser och nuvarande beteende

Svaren returneras infogade. Denna förhandsversion tillhandahåller inte MCP-resurser eller beständig lagring av artefakter för stora ögonblicksbilder, skärmdumpar eller nedladdningar. Webbläsare, operativsystem, viewport, lokal- och användaragent-överskrivningar exponeras inte som sessionsskapandeparametrar.

Felhantering

Ett verktygsfel inkluderar en stabil felkod, ett kundsäkert meddelande, ett retryable värde och korrelationsinformation. Använd det returnerade retryable värdet som primär signal, tillsammans med operationens bieffekter.

Hantera vanliga problem

MCP-klienten rapporterar obehörig åtkomst

• Bekräfta att autentisering av access-token är aktiverad för arbetsområdet.
• Bekräfta att tokenet inte har gått ut eller är återkallat.
• Använd det råa tokenvärdet som x-api-key värde. Lägg inte till något Bearer prefix.
• Kontrollera att tokenen och slutpunkten tillhör samma arbetsyta.
• Om du kopierade en hemlighet fel, skapa en ny token eftersom du inte kan hämta befintliga värden från portalen.

MCP-klienten rapporterar Förbjudet

• Bekräfta att användaren som är kopplad till tokenen fortfarande har behörighet att skapa webbläsarsessioner.
• Använd samma projektanslutning eller token för alla anrop i en webbläsarsession.
• Skicka inte a browserSessionId mellan användare, agenter som använder olika inloggningsuppgifter eller arbetsytor.

Verktyg upptäcks inte

• Verifiera hela slutpunkten, inklusive /playwrightworkspaces/<workspace-id>/mcp.
• Kontrollera att regionen för slutpunkten överensstämmer med arbetsytans region.
• Bekräfta att klienten använder en HTTP MCP-transport och skickar x-api-key under upptäckt och verktygsanrop.
• I Visual Studio Code, kör MCP: List Servers, välj servern och välj sedan Visa utdata.
• Starta om MCP-anslutningen eller återställ cachade verktyg efter att ha bytt endpoint.

Agenten anropar inte ett webbläsarverktyg

• Säg uttryckligen till agenten att använda den konfigurerade Playwright MCP-servern.
• Kontrollera att det nödvändiga verktyget finns med i klientens lista över aktiverade eller tillåtna verktyg.
• Inkludera livscykeln skapa-använda-stäng i agentinstruktionerna.
• Använd en fokuserad första uppgift med ett navigationsmål och ett förväntat resultat.

Ett mål fungerar inte längre

Sidan kan ha navigerat eller renderats om. Ring browser_snapshot eller browser_find igen och använd en aktuell referens. Undvik selektorer kopplade till genererade klasser eller ändrade dokumentstrukturer.

Ett verktyg som tog ut tiden

Anta inte att åtgärden misslyckades utan någon tillståndsändring. Om sessionen är aktiv, inspektera den aktuella sidan innan du försöker igen. Om sessionen har gått ut, skapa en ny session och returnera applikationen till ett känt tillstånd.

En skärmdump är för stor

Använd type: "jpeg", fånga endast vyrutan eller ange ett mål för en elementnivåskärmdump. Använd browser_snapshot när målet är att identifiera ett element snarare än att bevara visuella bevis.

Sessionen avslutades under ett flöde

Skapa en ny webbläsarsession. Sessioner återansluter inte efter förlust av webbläsaranslutning, förlust av tjänsteägaren, explicit stängning eller rensning vid inaktivitet. Designa flödet så att det kan starta om från en känd URL och applikationsstatus.

Säkerhetsrekommendationer

• Tillåt endast de verktyg som krävs för agentens uppgift.
• Kräv mänskligt godkännande för tillståndsändande, fil- och kodverktyg.
• Behandla sidinnehåll, tillgänglighetsögonblick, konsolutdata och nätverksutdata som opålitliga. En sida kan innehålla instruktioner för promptinjektion.
• Håll systeminstruktionerna åtskilda från sidbaserad text. Låt inte sidinnehållet ändra säkerhetspolicy eller godkännanderegler.
• Validera destinations-URL:er mot en tillåtslista när känsliga applikationer automatiseras.
• Gå igenom text, selektorer, filinnehåll och kod innan du godkänner ett verktygsanrop.
• Använd inte åtkomsttokens i prompts, källfiler, skärmdumpar, uppladdade filer eller JavaScript-utdrag.
• Använd kortlivade tokens, rotera dem regelbundet och återkalla oanvända anslutningar.
• Använd en dedikerad arbetsyta och en identitet med minsta möjliga behörighet för varje förtroendegräns.
• Logga godkännanden och verktygsnamn för granskning, men logga inte inloggningsuppgifter, uppladdat innehåll eller känslig siddata.

Regional tillgänglighet

Arbetsutrymmen för dramatiker finns tillgängligt i följande Azure-regioner:

Relaterat innehåll

• Hantera åtkomsttoken för arbetsytor
• Hantera åtkomst till en Playwright-arbetsyta
• Koppla Microsoft Foundry-agenter till MCP:s serverändpunkter
• Lägg till och hantera MCP-servrar i Visual Studio Code
• Dokumentation om Model Context Protocol