Automatisieren Sie Browser mit dem entfernten MCP-Server von Arbeitsbereiche für Dramatiker

Important

Der Arbeitsbereiche für Dramatiker-Remote-Model-Context-Protocol-(MCP)-Server ist als Vorschau verfügbar. Vorschaufunktionen haben keine Service-Level-Vereinbarung und werden für Produktionsworkloads nicht empfohlen. Funktionen, Limits und Verfügbarkeit können sich ändern.

Der Arbeitsbereiche für Dramatiker Remote MCP-Server bietet KI-Agenten einen verwalteten Remote-Browser und eine Reihe von Browser-Automatisierungstools. Ein Agent kann eine Browsersitzung öffnen, Seiten durchsuchen, Elemente finden und mit ihnen interagieren, Browseraktivitäten inspizieren, Screenshots machen und die Sitzung schließen. Du musst Playwright oder einen Browser nicht in der Agentenumgebung installieren.

Der Server verwendet Model Context Protocol über Streamable HTTP. Es unterstützt Microsoft Entra ID-Authentifizierung und Arbeitsbereichszugriffstoken. Es arbeitet mit entfernten MCP-Kunden, darunter Microsoft Foundry Agent Service und Visual Studio Code.

In diesem Artikel erfahren Sie, wie Sie:

  • Baue den MCP-Endpunkt für einen Playwright-Arbeitsbereich.
  • Authentifizieren Sie sich mit der Microsoft Entra ID oder einem Arbeitsbereichs-Zugriffstoken.
  • Verbinden Sie den Server mit dem Microsoft Foundry Agent Service oder Visual Studio Code.
  • Führe vollständige agentische Browser-Automatisierungsflows aus.
  • Wählen Sie die verfügbaren Browser-Tools aus und nutzen Sie sie sicher.
  • Behandle den Ablauf von Sitzungen, Zeitüberschreitungen und andere häufige Fehler.

Voraussetzungen

Bevor Sie beginnen, sollten Sie sicherstellen, dass Sie über Folgendes verfügen:

  • Ein Azure-Konto mit einem aktiven Abonnement.
  • Ein Playwright-Workspace, der Zugriff auf die Remote-MCP-Vorschau hat.
  • Die Arbeitsbereich-ID und die Azure-Region des Arbeitsbereichs.
  • Eine Identität mit der Berechtigung, Browsersitzungen im Arbeitsbereich zu erstellen und zu verwenden.
  • Bei Microsoft Foundry: ein Foundry-Projekt und die Berechtigung, Projektverbindungen zu erstellen und Agenten zu konfigurieren.
  • Für Visual Studio Code eine aktuelle Version von Visual Studio Code mit aktiviertem GitHub Copilot-Zugriff und MCP-Unterstützung.

Auswählen einer Authentifizierungsmethode

Verwenden Sie Microsoft Entra ID, wenn Ihr MCP-Client OAuth oder Managed Identity unterstützt. Der entfernte MCP-Server verwendet diese Ressourcenkennung und den delegierten Umfang:

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

Der Server veröffentlicht OAuth-Metadaten für geschützte Ressourcen. Clients, die OAuth-Erkennung unterstützen, einschließlich Visual Studio Code, können den Autorisierungsserver und den erforderlichen Scope über den arbeitsbereichsspezifischen MCP-Endpunkt ermitteln. Die angemeldete Identität muss über Azure Role-Based Access Control (RBAC) Zugriff auf den Playwright-Arbeitsbereich haben.

Warning

Verwenden Sie nur dann ein Workspace-Zugriffstoken, wenn der MCP-Client sich nicht mit Microsoft Entra ID authentifizieren kann. Zugriffstoken sind weniger sicher und standardmäßig deaktiviert.

Erstelle ein Workspace-Zugriffstoken zur Kompatibilität

Überspringen Sie diesen Abschnitt, wenn Sie Microsoft Entra ID verwenden. Wenn die Zugangstoken-Authentifizierung für den Arbeitsbereich noch nicht aktiviert ist:

  1. Melden Sie sich im Azure-Portal an.
  2. Öffnen Sie Ihren Playwright-Arbeitsbereich.
  3. Wählen Sie unter EinstellungenZugriffsverwaltung aus.
  4. Aktivieren Sie Playwright Service Access Token.
  5. Wählen Sie "Token generieren" aus.
  6. Geben Sie einen Namen und ein Ablaufdatum ein und generieren Sie dann das Token.
  7. Kopieren Sie das Token sofort. Man kann seinen Wert später nicht mehr zurückholen.

Speichern Sie das Token in einem verwalteten Geheimspeicher oder in der sicheren Zugangsmöglichkeit, die Ihr MCP-Client bereitstellt. Widerrufen Sie es und ersetzen Sie es, falls es kompromittiert worden sein könnte. Um einen Arbeitsbereich-Zugriffstoken zu erstellen, siehe Arbeitsbereich-Zugriffstoken verwalten.

Caution

Behandle einen Arbeitsbereichs-Zugriffstoken wie ein Passwort. Niemals in die Quellcode-Kontrolle einbinden, in einen Prompt einfügen oder in Logs schreiben.

Baue den entfernten MCP-Endpunkt

Der Endpunkt ist auf einen Arbeitsbereich und eine Region beschränkt:

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

Ersetzen Sie:

  • <region> mit der Azure-Region des Arbeitsbereichs.
  • <workspace-id> mit der Workspace-ID, die im Azure-Portal angezeigt wird.

Beispiel:

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

Der Wert im x-api-key Request-Header muss ein Zugriffstoken sein, der für denselben Arbeitsbereich wie <workspace-id>erstellt wurde. Verwenden Sie den Endpunkt für die Region des Arbeitsbereichs, nicht die Region, die dem MCP-Client am nächsten liegt.

Verstehen Sie den Browser-Sitzungszyklus

Ein Browser-Automatisierungsfluss besteht aus drei Stufen:

  1. Rufen Sie create_browser_sessionauf. Das Ergebnis enthält eine undurchsichtige browserSessionId und könnte eine Live-View-URL enthalten.
  2. Gib das browserSessionId an jedes im Flow verwendete Browser-Tool weiter.
  3. Rufen Sie close_browser_session in einem Bereinigungsschritt auf, auch wenn der Ablauf fehlschlägt.

Der MCP-HTTP-Transport bewahrt den Browser-Status nicht auf. browserSessionId identifiziert den Remote-Browser über mehrere separate Tool-Aufrufe hinweg. Halte es privat und verwende es nur mit dem Arbeitsbereich und der Identität, mit denen es erstellt wurde.

Das aktuelle Vorschauverhalten umfasst folgende Einschränkungen:

  • Eine Sitzung gehört ihrem Schöpfer und kann nicht mit einem anderen Schulleiter geteilt werden.
  • Anrufe für eine Sitzung werden der Reihe nach bearbeitet. Ergreifen Sie keine gleichzeitigen Maßnahmen gegen dieselbe Sitzung.
  • Eine inaktive Sitzung wird nach 15 Minuten beseitigt. Eine explizite Reinigung ist erforderlich.
  • Eine geschlossene oder abgelaufene Sitzung kann nicht wieder eröffnet werden.
  • Ein Verbindungsverlust beendet die Sitzung. Erstelle eine neue Sitzung, um fortzufahren.
  • Ein Ergebnis könnte ein liveViewUrl enthalten. Die Verfügbarkeit des Live-Views hängt von der jeweiligen Sitzung ab.

Verbinden Sie sich über den Microsoft Foundry Agent Service

Verwenden Sie Microsoft Entra Agent Identity, um den Agenten mit der verwalteten Identität des Foundry-Projekts zu authentifizieren. Gewähren Sie dieser Identität Zugriff auf den Playwright-Arbeitsbereich, bevor Sie das MCP-Tool verbinden.

Erstellen der Projektverbindung

  1. Öffnen Sie Ihr Projekt im Microsoft Foundry Portal.
  2. Öffnen Sie die Management-Erfahrung des Projekts und wählen Sie dann Verbundene Ressourcen aus.
  3. Stellen Sie eine Verbindung für einen entfernten MCP-Server her.
  4. Geben Sie einen beschreibenden Verbindungsnamen ein, wie zum Beispiel playwright-mcp-connection.
  5. Wählen Sie Microsoft Entra Agent Identity als Authentifizierungsmethode aus.
  6. Geben Sie https://mcp.playwright.microsoft.com als Zielgruppe ein.
  7. Speichern Sie die Verbindung.

Die verwaltete Identität des Projekts muss eine Rolle haben, die Browsersitzungsoperationen auf dem Ziel-Playwright-Arbeitsbereich erlaubt. Verwenden Sie kein Identitätstoken von einem Projekt als gemeinsames Geheimnis in einem anderen Projekt.

Wenn die Microsoft Entra Agent-Identität für den Client oder die Umgebung nicht verfügbar ist, erstellen Sie eine Custom-Keys-Verbindung mit einem Schlüssel und einem Workspace-Zugriffstoken x-api-key als Wert.

Fügen Sie das Remote MCP-Tool hinzu

  1. Erstelle oder eröffne einen Agenten im Foundry-Portal.

  2. Fügen Sie einen entfernten MCP-Server oder MCP-Tool hinzu.

  3. Verwenden Sie folgende Einstellungen:

    Setting Wert
    Serverbezeichnung Ein einzigartiges Etikett, wie zum Beispiel playwrightWorkspace
    Serveradresse Der auf den Arbeitsbereich bezogene Remote-MCP-Endpunkt
    Projektverbindung Die zuvor erstellte Microsoft Entra Agent Identity-Verbindung
    Genehmigung Fordern Sie für jeden Anruf eine Genehmigung bei der Bewertung der Integration
    Zulässige Tools Fang nur mit den Werkzeugen an, die für den Flow nötig sind
  4. Speichern Sie die Agentkonfiguration.

  5. Fordern Sie in den Agentenanweisungen, dass der Agent eine einzige Sitzung erstellt, browserSessionId wiederverwendet und die Sitzung schließt, wenn die Aufgabe abgeschlossen ist.

Eine minimale Werkzeug-Erlaubnisliste für einen leseorientierten Navigationsfluss ist:

create_browser_session
browser_navigate
browser_snapshot
browser_find
browser_take_screenshot
close_browser_session

Füge Interaktionswerkzeuge wie browser_click oder browser_type nur dann hinzu, wenn das Szenario sie erfordert. Aktivieren Sie browser_evaluate oder browser_run_code nicht standardmäßig.

Teste den Fluss der Gießerei

Verwenden Sie einen Prompt, der das Ziel und die Aufräumanforderung angibt. Beispiel:

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.

Wenn der Agent eine Genehmigung beantragt:

  1. Überprüfen Sie, dass das Server-Label der konfigurierte Playwright-Server ist.
  2. Überprüfen Sie den Werkzeugnamen und alle Argumente, insbesondere URLs, Selektoren, Text, hochgeladene Daten und Code.
  3. Genehmigen Sie nur die erwartete Operation.
  4. Überprüfen Sie, dass die endgültige Antwort auf dem Seitenergebnis basiert.
  5. Bestätigen Sie, dass der Flow close_browser_session heißt.

Für aktuelle Foundry-Verbindungsfelder, Genehmigungsverwaltung, SDK-Beispiele und Clientbeschränkungen siehe Agents mit MCP-Serverendpunkten verbinden.

Note

Aufrufe von Foundry-MCP-Tools ohne Streaming haben derzeit ein Client-Timeout von 100 Sekunden. Einige Playwright-Betriebe haben eine längere Auszeit auf der Serviceseite. Halte die Foundry-Abläufe fokussiert und teile lange Arbeitsabläufe in mehrere Tool-Calls auf.

Herstellen einer Verbindung mit Visual Studio Code

Visual Studio Code kann die OAuth-Konfiguration des entfernten Servers entdecken und dich mit der Microsoft Entra ID anmelden. Die Konfiguration benötigt nur den auf den Arbeitsbereich beschränkten Endpunkt.

  1. Führe in Visual Studio Code MCP: Open User Configuration aus der Command Palette aus.
  2. Fügen Sie die folgende Konfiguration hinzu und ersetzen Sie die Endpunkt-Platzhalter.
{
  "servers": {
    "playwrightWorkspace": {
      "type": "http",
      "url": "https://<region>.mcp.playwright.microsoft.com/playwrightworkspaces/<workspace-id>/mcp"
    }
  }
}
  1. Starte den Server über den Konfigurationseditor oder starte MCP: List Servers.
  2. Wenn Sie aufgefordert werden, melden Sie sich mit dem Microsoft Entra-Konto an, das Zugriff auf den Playwright-Arbeitsbereich hat.
  3. Genehmigen Sie die beantragte Playwright.Mcp.Tools Erlaubnis, wenn Ihre Zustimmung für Ihren Mieter erforderlich ist.
  4. Überprüfen Sie die Server-URL und Konfiguration und bestätigen Sie dann, dass Sie dem Server vertrauen.
  5. Öffne den Chat und wähle Werkzeuge konfigurieren. Aktiviere nur die für die Aufgabe benötigten Werkzeuge des Dramatikers.
  6. Führe den Beispielprompt aus dem vorherigen Foundry-Abschnitt aus.
  7. Überprüfen Sie die Bestätigungen des Tools und vergewissern Sie sich, dass die Sitzung am Ende geschlossen wird.

Verwenden Sie eine Benutzerkonfiguration, wenn die Verbindung persönlich ist. Eine Arbeitsbereichskonfiguration, die nur den Endpunkt enthält, kann geteilt werden. Visual Studio Code speichert die OAuth-Zugangsdaten sicher und kann sie beim erneuten Verbinden wiederverwenden.

Wenn die Microsoft Entra-Authentifizierung in der Client-Umgebung nicht verfügbar ist, konfigurieren Sie einen x-api-key Header mit einem geschützten Eingang, wie in den MCP-Konfigurationseingängen beschrieben. Geben Sie niemals den Workspace Access-Token-Wert direkt in mcp.json.

Für Konfigurationsstandorte, geheime Eingaben, Serververtrauen und Diagnostik siehe Add and manage MCP-Server in Visual Studio Code und die MCP-Konfigurationsreferenz.

Entwerfen Sie einen agentischen Automatisierungsfluss

Verwenden Sie eine Observe-Act-Verify-Schleife, anstatt den Agenten zu bitten, eine lange Sequenz durchzuführen, ohne den Seitenstatus zu überprüfen.

  1. Erstellen: Rufen Sie create_browser_session auf und behalten Sie das browserSessionId.
  2. Navigieren: Rufen Sie browser_navigate mit einer expliziten, genehmigten URL auf.
  3. Hinweis: Wählen Sie browser_find für eine gezielte Suche oder browser_snapshot für eine umfassendere Ansicht zur Barrierefreiheit.
  4. Handeln: Verwenden Sie eine Snapshot-Referenz oder einen eindeutigen Selektor mit einem Interaktionstool.
  5. Warten: Rufen Sie browser_wait_for für erwarteten Text, verschwindenden Text oder eine begrenzte Verzögerung auf.
  6. Verifizieren: Erfassen Sie einen weiteren Schnappschuss oder inspizieren Sie die Konsolen- und Netzwerkaktivitäten.
  7. Verzweigungen verwalten: Dialoge verwalten, Tabs wechseln oder Dateien nur hochladen, wenn der Seitenstatus es erfordert.
  8. Beweise erfassen: Rufen Sie an browser_take_screenshot , wenn ein visuelles Ergebnis nützlich ist. Verwenden Sie keine Screenshots, um Aktionsziele auszuwählen.
  9. Aufräumen: Rufen Sie close_browser_session in einem Cleanup-Pfad im Stil eines finally-Blocks auf.

Wählen Sie stabile Aktionsziele

Bevorzugen Sie Referenzen, die von browser_find oder browser_snapshot zurückgegeben werden. Sie beschreiben zugängliche Seitenelemente und verringern die Abhängigkeit von implementierungsspezifischem Markup. Verwenden Sie einen eindeutigen Selektor, wenn keine stabile Snapshot-Referenz verfügbar ist.

Aktualisieren Sie den Schnappschuss nach der Navigation oder nach einer Seitenänderung. Ein zuvor zurückgegebenes Ziel kann veraltet sein, wenn die Seite neu gerendert wird.

Dialoge sicher verwalten

Eine Aktion kann ein dialog-opened Ergebnis zurückgeben, nachdem sie bereits den Seitenzustand geändert hat. Dieses Ergebnis ist kein normales Versagen einer Aktion.

  1. Wiederhole nicht die ursprüngliche Handlung.
  2. Rufen Sie browser_handle_dialog auf, wobei accept auf false oder true gesetzt ist.
  3. Füge bei einem Prompt-Dialog promptText nur ein, wenn du ihn akzeptierst.
  4. Beobachten Sie die Seite noch einmal, bevor Sie fortfahren.

Mehrdeutige Fehler behandeln

Eine Auszeit oder ein unterbrochener Anrufer beweist nicht, dass eine Aktion keine Wirkung hatte. Bevor Sie eine nicht-idempotente Operation wie Klick, Formulareinreichung, Hochladen oder Codeausführung erneut versuchen:

  1. Rufen Sie browser_snapshot, browser_find oder ein anderes Überwachungstool auf, wenn die Sitzung noch verfügbar ist.
  2. Bestimmen Sie, ob die erwartete Zustandsänderung stattgefunden hat.
  3. Versuchen Sie es nur erneut, wenn es sicher ist, die Aktion zu wiederholen.
  4. Wenn die Sitzung abgelaufen ist, erstelle eine neue Sitzung und starte von einem bekannten Anwendungszustand aus.

Toolreferenz

Alle auf den Browser beschränkten Tools benötigen browserSessionId. Die hier gezeigten Grenzwerte für Zeichenfolgen und Sammlungen sind die derzeitigen Grenzwerte der Vorschau.

Sitzungswerkzeuge

Tool Parameter Verwendung
create_browser_session None Erstellt einen Remote-Browser und gibt liveViewUrl sowie optional browserSessionId zurück.
close_browser_session browserSessionId Schließt die Remote-Browser-Sitzung. Ruf es während der Reinigung an.
Tool Parameter Nutzung und wichtiges Verhalten
browser_navigate browserSessionId, url Navigiert zu einer URL. Die URL kann bis zu 16 KiB Zeichen enthalten.
browser_navigate_back browserSessionId Navigiert zum vorherigen Eintrag im Seitenverlauf.
browser_snapshot browserSessionId; optional target, depth, boxes Gibt einen Barrierefreiheitssnapshot zurück. target akzeptiert eine Snapshot-Referenz oder einen eindeutigen Selektor. Depth ist 1-100. Boxes enthält Bounding-Box-Daten, sofern unterstützt. Der Text der Momentaufnahme wird bei 64 KiB gekürzt und als gekürzt markiert.
browser_find browserSessionId, text Führt im Accessibility-Snapshot eine Suche nach Teilzeichenfolgen ohne Berücksichtigung der Groß-/Kleinschreibung durch und liefert übereinstimmende Snippets. Text kann bis zu 4.096 Zeichen enthalten.
browser_wait_for browserSessionId; Genau eins von text, textGone, oder time Wartet auf Text, wartet darauf, dass der Text verschwindet, oder wartet von 0 bis 180 Sekunden.
browser_take_screenshot browserSessionId; optional target, type, fullPage, scale Gibt ein Inline-PNG oder JPEG zurück. Type ist png oder jpeg. FullPage nimmt die gesamte Seite statt des standardmäßigen Viewports auf. Scale ist css oder device. Verwenden Sie einen Schnappschuss, nicht das Bild, um Ziele auszuwählen.
browser_console_messages browserSessionId Gibt begrenzte Konsolenmeldungen zurück, die für die aktive Seite erfasst wurden.
browser_network_requests browserSessionId Gibt begrenzte Netzwerkanforderungsinformationen zurück, die für die aktive Seite erfasst wurden.

Interaktionstools

Tool Parameter Nutzung und wichtiges Verhalten
browser_click browserSessionId, target; optional button, doubleClick, modifiers Klickt auf ein Ziel. Button ist left, right, oder middle. Akzeptiert bis zu fünf Modifikatoren aus Alt, Control, , ControlOrMeta, Metaund Shift. Versuchen Sie nicht blindlings einen Klick, der ein Timeout verursacht hat, erneut.
browser_type browserSessionId, target, text; optional submit, slowly Gibt Text in einem bearbeitbaren Element ein. Submit drückt danach Enter. Slowly tippt nacheinander.
browser_fill_form browserSessionId, fields Füllt 1-50 Felder. Jedes Feld enthält target, eine Zeichenkette oder einen Booleschen Wert value sowie optional name und type. Ein Fehler kann dazu führen, dass frühere Felder aktualisiert werden.
browser_press_key browserSessionId, key Drückt einen Playwright-Tastenbezeichner wie Enter, ArrowLeft oder Control+C.
browser_select_option browserSessionId, target, values Wählt 1-100 Optionswerte. Jeder Wert kann bis zu 4.096 Zeichen enthalten.
browser_hover browserSessionId, target Mit der Maus über ein Ziel, das Menüs oder Tooltips zeigen kann.
browser_handle_dialog browserSessionId, accept; optional promptText Akzeptiert oder verwirft den derzeit blockierenden Browser-Dialog.
browser_drag browserSessionId, startTarget, endTarget Zieht von einem Ziel zum nächsten. Beide Ziele müssen auf der aktiven Seite aufgelöst werden.

Tabs, Dateien und Code-Tools

Tool Parameter Nutzung und wichtiges Verhalten
browser_tabs browserSessionId, action; optional index, url Listet, erstellt, wählt oder schließt Tabs. action ist list, select, close oder new. index ist für select erforderlich; für close bedeutet das Weglassen den aktiven Tab. Indizes sind nullbasiert.
browser_file_upload browserSessionId, files; optional target Lädt 1–20 Base64-kodierte Dateien über ein Zieldatei-Eingabefeld oder einen offenen Dateiauswahldialog hoch. Siehe Datei-Upload-Limits.
browser_evaluate browserSessionId, function; optional target Bewertet eine JavaScript-Funktion auf der Seite oder gegen ein Ziel. Es kann den Seitenstatus lesen oder ändern.
browser_run_code browserSessionId, code Führt einen Playwright-JavaScript-Funktionskörper mit Zugriff auf die Seite aus. Dieses Werkzeug hat das höchste Privileg und kann willkürliche Nebenwirkungen verursachen.

Nach jedem Automatisierungs-Workflow rufen Sie das close_browser_session mit dem aktiven browserSessionId auf.

Form des Formularfelds

Jedes browser_fill_form Feld hat diese Form:

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

Der Zeichenkettenwert für ein Feld kann höchstens 100 KiB Zeichen enthalten. name kann höchstens 1.024 Zeichen enthalten und type höchstens 128 Zeichen.

Form des Datei-Uploads

Jede browser_file_upload Datei verwendet diese Form:

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

mimeType ist optional und standardmäßig auf application/octet-stream festgelegt.

Beschränkungen für Datei-Uploads

  • 1 bis 20 Dateien pro Werkzeugaufruf.
  • Maximal 10 MiB dekodierte Größe pro Datei.
  • 50 MiB maximale kombinierte Größe nach dem Dekodieren.
  • Dateiname mit maximal 4.096 Zeichen.
  • MIME-Typ mit maximal 1.024 Zeichen.
  • Gültige Base64-Daten sind erforderlich.

JavaScript-Werkzeugformen

Für browser_evaluate, übergebe einen Funktionsausdruck:

() => document.title

Wenn Sie angeben target, erhält die Funktion das passende Element:

element => element.textContent

Übergeben Sie für browser_run_code Anweisungen, die den Rumpf einer asynchronen Funktion bilden, deren Parameter page eine Playwright-Seite ist. Geben Sie nur JSON-serialisierbare Daten zurück und halten Sie sie innerhalb des Inline-Antwortlimits.

Warning

browser_evaluate und browser_run_code kann Seitendaten offenlegen, den Anwendungsstatus ändern und Netzwerkanfragen stellen. browser_run_code entspricht der Ausführung beliebiger Code innerhalb der isolierten Browserumgebung. Deaktiviere diese Werkzeuge, es sei denn, ein überprüftes Szenario erfordert sie. Geben Sie niemals Geheimnisse im Code weiter und geben Sie keine sensiblen Seitendaten an ein nicht vertrauenswürdiges Modell zurück.

Grenzen und aktuelles Verhalten

Limit Aktueller Wert Empfohlene Maßnahme
Inaktive Browsersitzung 15 Minuten Schließen Sie die Sitzungen explizit und erstellen Sie nach Ablauf eine neue Sitzung.
Angeforderte Wartezeit 180 Sekunden Bevorzuge bundesstaatliche Wartezeiten gegenüber festen Verzögerungen.
Dienstkommando-Timeout 3 Minuten 30 Sekunden Beachten Sie den Seitenstatus, bevor Sie eine Aktion wiederholen. Die Timeouts der Kunden können kürzer sein.
Inline-Antwort 1 MiB Geben Sie nur die für den nächsten Schritt benötigten Daten zurück oder fordern Sie sie an.
Text der Barrierefreiheits-Momentaufnahme 64 KiB Verwenden Sie browser_find, einen Zielunterbaum oder eine geringere Tiefe, wenn die Ausgabe gekürzt wird.
Base64-Daten für Inline-Screenshot 768 KiB Verwenden Sie JPEG, Sichtfensteraufnahme oder ein Elementziel, wenn ein Screenshot zu groß ist.
URL-Parameter 16 KiB-Zeichen Verwenden Sie eine gültige absolute Ziel-URL.
Ziel oder Selektor 4.096 Zeichen Bevorzuge prägnante Snapshot-Referenzen oder eindeutige Selektoren.
JavaScript-Funktion oder -code 1 MiB-Charaktere Halte den Code klein, überprüft und eng gefasst.
Browser-Sitzungs-ID 256 Zeichen Übergeben Sie den von create_browser_session zurückgegebenen Wert unverändert.

Antworten werden direkt zurückgegeben. Diese Vorschau bietet keinen Zugriff auf MCP-Ressourcen und keine persistente Speicherung von Artefakten für große Momentaufnahmen, Screenshots oder Downloads. Browser-, Betriebssystem-, Viewport-, Locale- und User-Agent-Overrides werden nicht als Parameter zur Sitzungserstellung bereitgestellt.

Fehlerbehandlung

Ein Werkzeugfehler umfasst einen stabilen Fehlercode, eine kundensichere Nachricht, einen retryable Wert und Korrelationsinformationen. Verwenden Sie den zurückgegebenen retryable Wert als Primärsignal zusammen mit den Nebenwirkungen der Operation.

Fehlercode Bedeutung Action
Unauthorized Der Zugriffstoken fehlt, ist ungültig, abgelaufen, deaktiviert oder gilt für einen anderen Arbeitsbereich. Überprüfen Sie x-api-key, die Aktivierung des Workspace-Zugriffstokens, den Tokenablauf und die Workspace-ID des Endpunkts. Versuchen Sie es nicht erneut mit derselben ungültigen Berechtigung.
Forbidden Dem Token-Besitzer fehlt die Erlaubnis, oder der Anrufer besitzt die Sitzung nicht. Verifizieren Sie den Zugriff auf den Arbeitsbereich und verwenden Sie während der gesamten Sitzung dieselbe Zugangsberechtigung.
SessionNotFound Die Sitzung existiert nicht. Erstellen Sie eine neue Sitzung.
SessionClosed Die Sitzung war geschlossen. Erstelle eine neue Sitzung, falls mehr Arbeit nötig ist.
SessionExpired Die Sitzung oder ihre Browserverbindung ist nicht mehr verfügbar. Eine neue Sitzung erstellen und von einem bekannten Zustand neu starten.
BrowserUnavailable Die Browserkapazität oder der entfernte Browser ist vorübergehend nicht verfügbar. Wiederhole die Sitzungserstellung nach einer Wartezeit, wenn retryable wahr ist.
DependencyUnavailable Ein erforderlicher Dienst ist vorübergehend nicht verfügbar. Versuchen Sie es mit exponentiellem Backoff erneut, falls retryable zutrifft.
InvalidArgument Ein Parameter fehlt, ist fehlgebildet, ist gegenseitig inkompatibel oder liegt außerhalb seiner Grenzen. Korrigiere die Argumente. Versuchen Sie es nicht erneut, ohne Änderungen vorzunehmen.
UnsupportedOperation Der angeforderte Vorgang wird nicht unterstützt. Verwenden Sie ein unterstütztes Tool oder einen Argumentwert.
OutputTooLarge Das Ergebnis überschreitet die Grenze für die Inline-Antwort. Fordern Sie einen kleineren Schnappschuss oder ein kleineres Ergebnis an. Für Screenshots verwenden Sie JPEG oder ein kleineres Ziel.
ToolTimeout Der Betrieb überschritt seine Einsatzfrist. Wenn die Sitzung noch verfügbar ist, beobachten Sie die Seite, bevor Sie entscheiden, ob Sie es erneut versuchen möchten.
NavigationFailed Die Navigation konnte nicht abgeschlossen werden. Überprüfe die URL, die Netzwerkzugänglichkeit und das Seitenverhalten. Beobachte die aktuelle Seite, bevor du es erneut versuchst.
ElementNotFound Das Ziel stimmt nicht mit einem Element überein. Aktualisieren Sie den Snapshot und verwenden Sie eine aktuelle Referenz oder einen eindeutigen Selektor.
ActionFailed Die Seite wurde abgelehnt oder konnte eine Aktion nicht abschließen. Inspizieren Sie den Seitenstatus. Das Element kann verborgen, deaktiviert, getrennt oder durch einen Dialog blockiert sein.
Busy Der Browser führt eine weitere Operation durch oder entleert eine vorherige Antwort. Warte kurz und versuche es nur, wenn es sicher ist, die Operation zu wiederholen.
QuotaExceeded Der Arbeitsbereich oder das Konto erreichte eine Browser-Session-Quote. Schließen Sie ungenutzte Sitzungen und überprüfen Sie das Arbeitsbereichskontingent.
RateLimited Die Anfragen kommen viel zu schnell ein. Verwende exponentielles Backoff und reduziere die Parallelität.
InternalError Der Dienst trat auf einen unerwarteten Fehler. Versuchen Sie es nur wieder, wenn es angezeigt wird. Fügen Sie die Korrelations-ID an, wenn Sie den Support kontaktieren.

Behandeln gängiger Probleme

Der MCP-Client meldet „Nicht autorisiert“

  • Bestätigen Sie, dass die Zugangstoken-Authentifizierung für den Arbeitsbereich aktiviert ist.
  • Bestätigen Sie, dass das Token nicht abgelaufen oder widerrufen ist.
  • Verwenden Sie den rohen Tokenwert als Wert x-api-key . Füge kein Präfix hinzu Bearer .
  • Bestätigen Sie, dass Token und Endpunkt zum selben Arbeitsbereich gehören.
  • Wenn du ein Geheimnis falsch kopiert hast, erstelle ein neues Token, weil du bestehende Werte nicht aus dem Portal abrufen kannst.

Der MCP-Client meldet „Zugriff verweigert“

  • Bestätigen Sie, dass der mit dem Token verknüpfte Benutzer weiterhin die Berechtigung hat, Browsersitzungen zu erstellen.
  • Verwenden Sie für alle Aufrufe in einer Browsersitzung dieselbe Projektverbindung oder denselben Token.
  • Geben Sie ein browserSessionId nicht zwischen Benutzern, Agenten mit unterschiedlichen Zugangsdaten oder Arbeitsbereichen weiter.

Werkzeuge werden nicht entdeckt

  • Überprüfen Sie den vollständigen Endpunkt, einschließlich /playwrightworkspaces/<workspace-id>/mcp.
  • Überprüfen Sie, ob die Endpunktregion mit der Arbeitsbereichsregion übereinstimmt.
  • Bestätigen Sie, dass der Client einen HTTP-MCP-Transport verwendet und während der Erkennung und bei Toolaufrufen x-api-key sendet.
  • In Visual Studio Code starten Sie MCP: List Servers, wählen Sie den Server aus und wählen Sie dann Show Output.
  • Starte die MCP-Verbindung neu oder setze zwischengespeicherte Werkzeuge zurück, nachdem du den Endpunkt geändert hast.

Der Agent ruft kein Browser-Tool an

  • Sag dem Agenten ausdrücklich, er solle den konfigurierten Playwright MCP-Server verwenden.
  • Überprüfen Sie, dass das erforderliche Tool in der Liste der aktivierten oder erlaubten Werkzeuge des Kunden erscheint.
  • Fügen Sie den Lebenszyklus „Erstellen, Verwenden, Schließen“ in die Anweisungen für den Agenten ein.
  • Verwenden Sie eine fokussierte erste Aufgabe mit einem Navigationsziel und einem erwarteten Ergebnis.

Ein Ziel funktioniert nicht mehr

Auf der Seite wurde möglicherweise navigiert oder sie wurde neu gerendert. Ruf an browser_snapshot oder browser_find nochmal und verwende eine aktuelle Referenz. Vermeiden Sie Selektoren, die an generierte Klassen gebunden sind oder die Dokumentstruktur ändern.

Ein Werkzeug, das zeitlich abgelaufen ist

Gehen Sie nicht davon aus, dass die Aktion fehlgeschlagen ist, ohne den Zustand zu ändern. Wenn die Sitzung aktiv ist, inspiziere die aktuelle Seite, bevor du es erneut versuchst. Wenn die Sitzung abgelaufen ist, erstelle eine neue Sitzung und setze die Anwendung in einen bekannten Zustand zurück.

Ein Screenshot ist zu groß

Verwenden Sie type: "jpeg", erfassen Sie nur das Ansichtsfenster, oder geben Sie ein Ziel für einen Screenshot auf Elementebene an. Verwenden browser_snapshot Sie, wenn das Ziel ist, ein Element zu identifizieren, anstatt visuelle Beweise zu bewahren.

Die Sitzung ist während eines Flows abgelaufen.

Erstelle eine neue Browsersitzung. Sitzungen verbinden sich nicht erneut, nachdem die Browserverbindung unterbrochen wurde, nach Verlust des Dienstinhabers, nach expliziter Schließung oder nach einer Bereinigung aufgrund von Inaktivität. Legen Sie den Ablauf so aus, dass er von einer bekannten URL und einem bekannten Anwendungszustand aus neu gestartet werden kann.

Sicherheitsempfehlungen

  • Lassen Sie nur die Werkzeuge zu, die für die Aufgabe des Agenten benötigt werden.
  • Benötigen Genehmigungen von Personen für Statusänderungs-, Dateibearbeitungs- und Code-Tools.
  • Behandeln Sie Seiteninhalte, Zugänglichkeits-Snapshots, Konsolenausgabe und Netzwerkausgabe als vertrauenslos. Eine Seite kann Anweisungen zur Prompt-Injektion enthalten.
  • Halte die Systemanweisungen vom seitenbasierten Text getrennt. Lassen Sie nicht zu, dass Seiteninhalte die Sicherheitsrichtlinien oder Genehmigungsregeln ändern.
  • Überprüfen Sie Ziel-URLs anhand einer Erlaubnisliste bei der Automatisierung sensibler Anwendungen.
  • Überprüfen Sie Text, Selektoren, Dateiinhalte und Code, bevor Sie einen Toolaufruf genehmigen.
  • Verwenden Sie keine Zugriffstoken in Prompts, Quellcode-Dateien, Screenshots, hochgeladenen Dateien oder JavaScript-Ausschnitten.
  • Nutze kurzlebige Token, rotiere sie regelmäßig und widerrufe ungenutzte Verbindungen.
  • Verwenden Sie für jede Vertrauensgrenze einen eigenen Arbeitsbereich und eine Identität nach dem Least-Privilege-Prinzip.
  • Protokolliere Genehmigungen und Werkzeugnamen für Audits, aber protokolliere keine Zugangsdaten, hochgeladene Inhalte oder sensible Seitendaten.

Regionale Verfügbarkeit

Arbeitsbereiche für Dramatiker ist in den folgenden Azure-Regionen verfügbar:

Region Available
Australia East ✅ Ja
East Asia ✅ Ja
East US ✅ Ja
Japan East ✅ Ja
Switzerland North ✅ Ja
West Europe ✅ Ja
Westliches USA 3 ✅ Ja