autogen_ext.agents.web_surfer#

class MultimodalWebSurfer(name: str, model_client: ChatCompletionClient, downloads_folder: str | None = None, description: str = DEFAULT_DESCRIPTION, debug_dir: str | None = None, headless: bool = True, start_page: str | None = DEFAULT_START_PAGE, animate_actions: bool = False, to_save_screenshots: bool = False, use_ocr: bool = False, browser_channel: str | None = None, browser_data_dir: str | None = None, to_resize_viewport: bool = True, playwright: Playwright | None = None, context: BrowserContext | None = None)[source]#

Bases: BaseChatAgent, Component[MultimodalWebSurferConfig]

MultimodalWebSurfer ist ein multimodaler Agent, der als Web-Surfer fungiert und das Web durchsuchen sowie Webseiten besuchen kann.

Installation

pip install "autogen-ext[web-surfer]"

Er startet einen Chromium-Browser und ermöglicht es Playwright, mit dem Webbrowser zu interagieren und verschiedene Aktionen auszuführen. Der Browser wird beim ersten Aufruf des Agenten gestartet und für nachfolgende Aufrufe wiederverwendet.

Er muss mit einem multimodalen Modellclient verwendet werden, der Funktions-/Tool-Aufrufe unterstützt, idealerweise derzeit GPT-4o.

Wenn on_messages() oder on_messages_stream() aufgerufen wird, geschieht Folgendes:

  1. Wenn dies der erste Aufruf ist, wird der Browser initialisiert und die Seite geladen. Dies geschieht in _lazy_init(). Der Browser wird erst geschlossen, wenn close() aufgerufen wird.

  2. Die Methode _generate_reply() wird aufgerufen, die dann die endgültige Antwort wie unten beschrieben erstellt.

  3. Der Agent nimmt einen Screenshot der Seite auf, extrahiert die interaktiven Elemente und bereitet einen "Set-of-Mark"-Screenshot mit Begrenzungsrahmen um die interaktiven Elemente vor.

  4. Der Agent tätigt einen Aufruf an den model_client mit dem SOM-Screenshot, der Nachrichten-Historie und der Liste der verfügbaren Tools.

    • Wenn das Modell einen String zurückgibt, gibt der Agent den String als endgültige Antwort zurück.

    • Wenn das Modell eine Liste von Tool-Aufrufen zurückgibt, führt der Agent die Tool-Aufrufe mit _execute_tool() unter Verwendung von _playwright_controller aus.

    • Der Agent gibt eine endgültige Antwort zurück, die einen Screenshot der Seite, Metadaten der Seite, eine Beschreibung der durchgeführten Aktion und den Innertext der Webseite enthält.

  5. Wenn der Agent zu irgendeinem Zeitpunkt einen Fehler feststellt, gibt er die Fehlermeldung als endgültige Antwort zurück.

Hinweis

Bitte beachten Sie, dass die Verwendung von MultimodalWebSurfer die Interaktion mit einer für Menschen konzipierten digitalen Welt beinhaltet, was inhärente Risiken birgt. Seien Sie sich bewusst, dass Agenten gelegentlich risikoreiche Aktionen versuchen können, wie z. B. die Rekrutierung von Menschen zur Hilfe oder die Annahme von Cookie-Einwilligungen ohne menschliches Zutun. Stellen Sie immer sicher, dass Agenten überwacht werden und in einer kontrollierten Umgebung arbeiten, um unbeabsichtigte Folgen zu vermeiden. Darüber hinaus seien Sie vorsichtig, da MultimodalWebSurfer anfällig für Prompt-Injection-Angriffe von Webseiten sein kann.

Hinweis

Unter Windows muss die Event-Loop-Richtlinie auf WindowsProactorEventLoopPolicy gesetzt werden, um Probleme mit Subprozessen zu vermeiden.

import sys
import asyncio

if sys.platform == "win32":
    asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
Parameter:

  • name (str) – Der Name des Agenten.

  • model_client (ChatCompletionClient) – Der vom Agenten verwendete Modellclient. Muss multimodal sein und Funktionsaufrufe unterstützen.

  • downloads_folder (str, optional) – Der Ordner, in dem Downloads gespeichert werden. Standardmäßig None, keine Downloads werden gespeichert.

  • description (str, optional) – Die Beschreibung des Agenten. Standardmäßig MultimodalWebSurfer.DEFAULT_DESCRIPTION.

  • debug_dir (str, optional) – Das Verzeichnis, in dem Debug-Informationen gespeichert werden. Standardmäßig None.

  • headless (bool, optional) – Ob der Browser im Headless-Modus ausgeführt werden soll. Standardmäßig True.

  • start_page (str, optional) – Die Startseite für den Browser. Standardmäßig MultimodalWebSurfer.DEFAULT_START_PAGE.

  • animate_actions (bool, optional) – Ob Aktionen animiert werden sollen. Standardmäßig False.

  • to_save_screenshots (bool, optional) – Ob Screenshots gespeichert werden sollen. Standardmäßig False.

  • use_ocr (bool, optional) – Ob OCR verwendet werden soll. Standardmäßig False.

  • browser_channel (str, optional) – Der Browser-Kanal. Standardmäßig None.

  • browser_data_dir (str, optional) – Das Browser-Datenverzeichnis. Standardmäßig None.

  • to_resize_viewport (bool, optional) – Ob die Ansicht angepasst werden soll. Standardmäßig True.

  • playwright (Playwright, optional) – Die Playwright-Instanz. Standardmäßig None.

  • context (BrowserContext, optional) – Der Browser-Kontext. Standardmäßig None.

Beispielverwendung

Das folgende Beispiel zeigt, wie ein Web-Surfing-Agent mit einem Modellclient erstellt und für mehrere Durchläufe ausgeführt wird.

import asyncio
from autogen_agentchat.ui import Console
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_ext.agents.web_surfer import MultimodalWebSurfer


async def main() -> None:
    # Define an agent
    web_surfer_agent = MultimodalWebSurfer(
        name="MultimodalWebSurfer",
        model_client=OpenAIChatCompletionClient(model="gpt-4o-2024-08-06"),
    )

    # Define a team
    agent_team = RoundRobinGroupChat([web_surfer_agent], max_turns=3)

    # Run the team and stream messages to the console
    stream = agent_team.run_stream(task="Navigate to the AutoGen readme on GitHub.")
    await Console(stream)
    # Close the browser controlled by the agent
    await web_surfer_agent.close()


asyncio.run(main())
component_type: ClassVar[ComponentType] = 'agent'#

Der logische Typ der Komponente.

component_config_schema#

alias of MultimodalWebSurferConfig

component_provider_override: ClassVar[str | None] = 'autogen_ext.agents.web_surfer.MultimodalWebSurfer'#

Überschreibe den Anbieter-String für die Komponente. Dies sollte verwendet werden, um zu verhindern, dass interne Modulnamen Teil des Modulnamens werden.

DEFAULT_DESCRIPTION = '\n    Ein hilfreicher Assistent mit Zugriff auf einen Webbrowser.\n    Bitten Sie ihn, Websuchen durchzuführen, Seiten zu öffnen und mit Inhalten zu interagieren (z.B. Links anklicken, den Viewport scrollen, Formularfelder ausfüllen, usw.).\n    Er kann auch die gesamte Seite zusammenfassen oder Fragen basierend auf dem Seiteninhalt beantworten.\n    Ihm kann auch gesagt werden, zu schlafen und auf das Laden von Seiten zu warten, in Fällen, in denen die Seite noch nicht vollständig geladen zu sein scheint.\n    '#
DEFAULT_START_PAGE = 'https://www.bing.com/'#
VIEWPORT_HEIGHT = 900#
VIEWPORT_WIDTH = 1440#
MLM_HEIGHT = 765#
MLM_WIDTH = 1224#
SCREENSHOT_TOKENS = 1105#
async close() → None[source]#

Schließen Sie den Browser und die Seite. Sollte aufgerufen werden, wenn der Agent nicht mehr benötigt wird.

property produced_message_types: Sequence[type[BaseChatMessage]]#

Die Arten von Nachrichten, die der Agent im Feld Response.chat_message produziert. Sie müssen BaseChatMessage-Typen sein.

async on_reset(cancellation_token: CancellationToken) → None[source]#

Setzt den Agenten in seinen Initialzustand zurück.

async on_messages(messages: Sequence[BaseChatMessage], cancellation_token: CancellationToken) → Response[source]#

Verarbeitet eingehende Nachrichten und gibt eine Antwort zurück.

Hinweis

Agenten sind zustandsbehaftet, und die an diese Methode übergebenen Nachrichten sollten die neuen Nachrichten seit dem letzten Aufruf dieser Methode sein. Der Agent sollte seinen Zustand zwischen den Aufrufen dieser Methode beibehalten. Wenn der Agent sich beispielsweise die vorherigen Nachrichten merken muss, um auf die aktuelle Nachricht zu reagieren, sollte er die vorherigen Nachrichten im Agentenzustand speichern.

async on_messages_stream(messages: Sequence[BaseChatMessage], cancellation_token: CancellationToken) → AsyncGenerator[BaseAgentEvent | BaseChatMessage | Response, None][source]#

Verarbeitet eingehende Nachrichten und gibt einen Strom von Nachrichten zurück, wobei das letzte Element die Antwort ist. Die Basisimplementierung in BaseChatAgent ruft einfach on_messages() auf und gibt die Nachrichten in der Antwort aus.

Hinweis

Agenten sind zustandsbehaftet, und die an diese Methode übergebenen Nachrichten sollten die neuen Nachrichten seit dem letzten Aufruf dieser Methode sein. Der Agent sollte seinen Zustand zwischen den Aufrufen dieser Methode beibehalten. Wenn der Agent sich beispielsweise die vorherigen Nachrichten merken muss, um auf die aktuelle Nachricht zu reagieren, sollte er die vorherigen Nachrichten im Agentenzustand speichern.

_to_config() → MultimodalWebSurferConfig[source]#

Gib die Konfiguration aus, die erforderlich wäre, um eine neue Instanz einer Komponente zu erstellen, die der Konfiguration dieser Instanz entspricht.

Gibt zurück:

T – Die Konfiguration der Komponente.

classmethod _from_config(config: MultimodalWebSurferConfig) → Self[source]#

Erstelle eine neue Instanz der Komponente aus einem Konfigurationsobjekt.

Parameter:

config (T) – Das Konfigurationsobjekt.

Gibt zurück:

Self – Die neue Instanz der Komponente.

class PlaywrightController(downloads_folder: str | None = None, animate_actions: bool = False, viewport_width: int = 1440, viewport_height: int = 900, _download_handler: Callable[[Download], None] | None = None, to_resize_viewport: bool = True)[source]#

Basiert auf: object

Eine Hilfsklasse, die es Playwright ermöglicht, mit Webseiten zu interagieren, um Aktionen wie Klicken, Ausfüllen und Scrollen durchzuführen.

Parameter:

  • downloads_folder (str | None) – Der Ordner zum Speichern von Downloads. Wenn None, werden keine Downloads gespeichert.

  • animate_actions (bool) – Ob die Aktionen animiert werden sollen (erzeugt einen künstlichen Cursor zum Klicken).

  • viewport_width (int) – Die Breite der Ansicht.

  • viewport_height (int) – Die Höhe der Ansicht.

  • _download_handler (Optional[Callable[[Download], None]]) – Eine Funktion zur Verarbeitung von Downloads.

  • to_resize_viewport (bool) – Ob die Ansicht angepasst werden soll

async sleep(page: Page, duration: int | float) → None[source]#

Pausieren Sie die Ausführung für eine bestimmte Dauer.

Parameter:

  • page (Page) – Das Playwright-Seitenobjekt.

  • duration (Union[int, float]) – Die Dauer des Schlafes in Millisekunden.

async get_interactive_rects(page: Page) → Dict[str, InteractiveRegion][source]#

Ruft interaktive Regionen von der Webseite ab.

Parameter:

page (Page) – Das Playwright-Seitenobjekt.

Gibt zurück:

Dict[str, InteractiveRegion] – Ein Wörterbuch von interaktiven Regionen.

async get_visual_viewport(page: Page) → VisualViewport[source]#

Ruft die visuelle Ansicht der Webseite ab.

Parameter:

page (Page) – Das Playwright-Seitenobjekt.

Gibt zurück:

VisualViewport – Die visuelle Ansicht der Seite.

async get_focused_rect_id(page: Page) → str | None[source]#

Ruft die ID des aktuell fokussierten Elements ab.

Parameter:

page (Page) – Das Playwright-Seitenobjekt.

Gibt zurück:

str – Die ID des fokussierten Elements oder None, wenn kein Steuerelement den Fokus hat.

async get_page_metadata(page: Page) → Dict[str, Any][source]#

Ruft Metadaten von der Webseite ab.

Parameter:

page (Page) – Das Playwright-Seitenobjekt.

Gibt zurück:

Dict[str, Any] – Ein Wörterbuch mit Seitenmetadaten.

async on_new_page(page: Page) → None[source]#

Behandelt Aktionen, die auf einer neuen Seite ausgeführt werden sollen.

Parameter:

page (Page) – Das Playwright-Seitenobjekt.

async back(page: Page) → None[source]#

Zurück zur vorherigen Seite navigieren.

Parameter:

page (Page) – Das Playwright-Seitenobjekt.

async visit_page(page: Page, url: str) → Tuple[bool, bool][source]#

Besucht eine angegebene URL.

Parameter:

  • page (Page) – Das Playwright-Seitenobjekt.

  • url (str) – Die zu besuchende URL.

Gibt zurück:

Tuple[bool, bool] – Ein Tupel, das angibt, ob der vorherige Metadaten-Hash und der letzte Download zurückgesetzt werden sollen.

async page_down(page: Page) → None[source]#

Scrollt die Seite um die Viewport-Höhe minus 50 Pixel nach unten.

Parameter:

page (Page) – Das Playwright-Seitenobjekt.

async page_up(page: Page) → None[source]#

Scrollt die Seite um die Viewport-Höhe minus 50 Pixel nach oben.

Parameter:

page (Page) – Das Playwright-Seitenobjekt.

async gradual_cursor_animation(page: Page, start_x: float, start_y: float, end_x: float, end_y: float) → None[source]#

Animiert die Cursorbewegung allmählich von den Start- zu den Endkoordinaten.

Parameter:

  • page (Page) – Das Playwright-Seitenobjekt.

  • start_x (float) – Die Start-X-Koordinate.

  • start_y (float) – Die Start-Y-Koordinate.

  • end_x (float) – Die End-X-Koordinate.

  • end_y (float) – Die End-Y-Koordinate.

async add_cursor_box(page: Page, identifier: str) → None[source]#

Fügt einen roten Cursor-Rahmen um das Element mit der angegebenen Kennung hinzu.

Parameter:

  • page (Page) – Das Playwright-Seitenobjekt.

  • identifier (str) – Die Elementkennung.

async remove_cursor_box(page: Page, identifier: str) → None[source]#

Entfernt den roten Cursor-Rahmen um das Element mit der angegebenen Kennung.

Parameter:

  • page (Page) – Das Playwright-Seitenobjekt.

  • identifier (str) – Die Elementkennung.

async click_id(page: Page, identifier: str) → Page | None[source]#

Klickt auf das Element mit der angegebenen Kennung.

Parameter:

  • page (Page) – Das Playwright-Seitenobjekt.

  • identifier (str) – Die Elementkennung.

Gibt zurück:

Page | None – Die neue Seite, falls eine neue Seite geöffnet wird, andernfalls None.

async hover_id(page: Page, identifier: str) → None[source]#

Bewegt den Mauszeiger über das Element mit der angegebenen Kennung.

Parameter:

  • page (Page) – Das Playwright-Seitenobjekt.

  • identifier (str) – Die Elementkennung.

async fill_id(page: Page, identifier: str, value: str, press_enter: bool = True) → None[source]#

Füllt das Element mit der angegebenen Kennung mit dem angegebenen Wert.

Parameter:

  • page (Page) – Das Playwright-Seitenobjekt.

  • identifier (str) – Die Elementkennung.

  • value (str) – Der zu füllende Wert.

async scroll_id(page: Page, identifier: str, direction: str) → None[source]#

Scrollt das Element mit der angegebenen Kennung in die angegebene Richtung.

Parameter:

  • page (Page) – Das Playwright-Seitenobjekt.

  • identifier (str) – Die Elementkennung.

  • direction (str) – Die Scroll-Richtung („up“ oder „down“).

async get_webpage_text(page: Page, n_lines: int = 50) → str[source]#

Ruft den Textinhalt der Webseite ab.

Parameter:

  • page (Page) – Das Playwright-Seitenobjekt.

  • n_lines (int) – Die Anzahl der Zeilen, die aus dem inneren Text der Seite zurückgegeben werden sollen.

Gibt zurück:

str – Der Textinhalt der Seite.

async get_visible_text(page: Page) → str[source]#

Ruft den sichtbaren Textinhalt des Browser-Viewports ab (ungefähr).

Parameter:

page (Page) – Das Playwright-Seitenobjekt.

Gibt zurück:

str – Der Textinhalt der Seite.

async get_page_markdown(page: Page) → str[source]#

Ruft den Markdown-Inhalt der Webseite ab. Derzeit nicht implementiert.

Parameter:

page (Page) – Das Playwright-Seitenobjekt.

Gibt zurück:

str – Der Markdown-Inhalt der Seite.