Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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:
- Melden Sie sich im Azure-Portal an.
- Öffnen Sie Ihren Playwright-Arbeitsbereich.
- Wählen Sie unter EinstellungenZugriffsverwaltung aus.
- Aktivieren Sie Playwright Service Access Token.
- Wählen Sie "Token generieren" aus.
- Geben Sie einen Namen und ein Ablaufdatum ein und generieren Sie dann das Token.
- 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:
- Rufen Sie
create_browser_sessionauf. Das Ergebnis enthält eine undurchsichtigebrowserSessionIdund könnte eine Live-View-URL enthalten. - Gib das
browserSessionIdan jedes im Flow verwendete Browser-Tool weiter. - Rufen Sie
close_browser_sessionin 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
liveViewUrlenthalten. 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
- Öffnen Sie Ihr Projekt im Microsoft Foundry Portal.
- Öffnen Sie die Management-Erfahrung des Projekts und wählen Sie dann Verbundene Ressourcen aus.
- Stellen Sie eine Verbindung für einen entfernten MCP-Server her.
- Geben Sie einen beschreibenden Verbindungsnamen ein, wie zum Beispiel
playwright-mcp-connection. - Wählen Sie Microsoft Entra Agent Identity als Authentifizierungsmethode aus.
- Geben Sie
https://mcp.playwright.microsoft.comals Zielgruppe ein. - 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
Erstelle oder eröffne einen Agenten im Foundry-Portal.
Fügen Sie einen entfernten MCP-Server oder MCP-Tool hinzu.
Verwenden Sie folgende Einstellungen:
Setting Wert Serverbezeichnung Ein einzigartiges Etikett, wie zum Beispiel playwrightWorkspaceServeradresse 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 Speichern Sie die Agentkonfiguration.
Fordern Sie in den Agentenanweisungen, dass der Agent eine einzige Sitzung erstellt,
browserSessionIdwiederverwendet 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:
- Überprüfen Sie, dass das Server-Label der konfigurierte Playwright-Server ist.
- Überprüfen Sie den Werkzeugnamen und alle Argumente, insbesondere URLs, Selektoren, Text, hochgeladene Daten und Code.
- Genehmigen Sie nur die erwartete Operation.
- Überprüfen Sie, dass die endgültige Antwort auf dem Seitenergebnis basiert.
- Bestätigen Sie, dass der Flow
close_browser_sessionheiß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.
- Führe in Visual Studio Code MCP: Open User Configuration aus der Command Palette aus.
- 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"
}
}
}
- Starte den Server über den Konfigurationseditor oder starte MCP: List Servers.
- Wenn Sie aufgefordert werden, melden Sie sich mit dem Microsoft Entra-Konto an, das Zugriff auf den Playwright-Arbeitsbereich hat.
- Genehmigen Sie die beantragte
Playwright.Mcp.ToolsErlaubnis, wenn Ihre Zustimmung für Ihren Mieter erforderlich ist. - Überprüfen Sie die Server-URL und Konfiguration und bestätigen Sie dann, dass Sie dem Server vertrauen.
- Öffne den Chat und wähle Werkzeuge konfigurieren. Aktiviere nur die für die Aufgabe benötigten Werkzeuge des Dramatikers.
- Führe den Beispielprompt aus dem vorherigen Foundry-Abschnitt aus.
- Ü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.
-
Erstellen: Rufen Sie
create_browser_sessionauf und behalten Sie dasbrowserSessionId. -
Navigieren: Rufen Sie
browser_navigatemit einer expliziten, genehmigten URL auf. -
Hinweis: Wählen Sie
browser_findfür eine gezielte Suche oderbrowser_snapshotfür eine umfassendere Ansicht zur Barrierefreiheit. - Handeln: Verwenden Sie eine Snapshot-Referenz oder einen eindeutigen Selektor mit einem Interaktionstool.
-
Warten: Rufen Sie
browser_wait_forfür erwarteten Text, verschwindenden Text oder eine begrenzte Verzögerung auf. - Verifizieren: Erfassen Sie einen weiteren Schnappschuss oder inspizieren Sie die Konsolen- und Netzwerkaktivitäten.
- Verzweigungen verwalten: Dialoge verwalten, Tabs wechseln oder Dateien nur hochladen, wenn der Seitenstatus es erfordert.
-
Beweise erfassen: Rufen Sie an
browser_take_screenshot, wenn ein visuelles Ergebnis nützlich ist. Verwenden Sie keine Screenshots, um Aktionsziele auszuwählen. -
Aufräumen: Rufen Sie
close_browser_sessionin 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.
- Wiederhole nicht die ursprüngliche Handlung.
- Rufen Sie
browser_handle_dialogauf, wobeiacceptauffalseodertruegesetzt ist. - Füge bei einem Prompt-Dialog
promptTextnur ein, wenn du ihn akzeptierst. - 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:
- Rufen Sie
browser_snapshot,browser_findoder ein anderes Überwachungstool auf, wenn die Sitzung noch verfügbar ist. - Bestimmen Sie, ob die erwartete Zustandsänderung stattgefunden hat.
- Versuchen Sie es nur erneut, wenn es sicher ist, die Aktion zu wiederholen.
- 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. |
Navigations- und Beobachtungswerkzeuge
| 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 hinzuBearer. - 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
browserSessionIdnicht 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-keysendet. - 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 |