autogen_ext.agents.web_surfer#

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

基类：BaseChatAgent, Component[MultimodalWebSurferConfig]

MultimodalWebSurfer是一个多模态代理，它扮演着网页浏览者的角色，可以搜索网页并访问网页。

安装：

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

它启动一个chromium浏览器，并允许playwright与网页浏览器进行交互，可以执行多种操作。浏览器在第一次调用代理时启动，并在后续调用中重复使用。

必须与支持函数/工具调用的多模态模型客户端一起使用，目前理想的选择是GPT-4o。

When on_messages() or on_messages_stream() is called, the following occurs:

  1. 如果是第一次调用，浏览器将被初始化并加载页面。这将在_lazy_init()中完成。浏览器只有在调用close()时才会关闭。

  2. 调用了方法 _generate_reply()，然后生成了如下所示的最终响应。

  3. 该代理会截取页面的屏幕截图，提取交互元素，并准备一个带交互元素边界框的标记集截图。

  4. The agent makes a call to the model_client with the SOM screenshot, history of messages, and the list of available tools.

    • 如果模型返回一个字符串，代理将该字符串作为最终响应返回。

    • 如果模型返回了一个工具调用列表，代理将使用 _playwright_controller 通过 _execute_tool() 执行这些工具调用。

    • 代理返回一个最终响应，其中包括页面的屏幕截图、页面元数据、所采取操作的描述以及网页的内部文本。

  5. 如果代理在任何时候遇到错误，它将返回错误信息作为最终响应。

注意

请注意，使用MultimodalWebSurfer涉及与为人类设计的数字世界互动，这具有固有的风险。 请注意，代理有时可能会尝试风险操作，例如在没有人类参与的情况下招募人类帮助或接受cookie协议。始终确保代理在受控环境中进行监控和操作，以防止意外的后果。 此外，请注意MultimodalWebSurfer可能容易受到网页的提示注入攻击。

注意

在Windows上，事件循环策略必须设置为WindowsProactorEventLoopPolicy，以避免子进程出现问题。

import sys
import asyncio

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

  • name (str) – 代理的名称。

  • model_client (ChatCompletionClient) – 代理使用的模型客户端。必须支持多模态并且支持函数调用。

  • downloads_folder (str, optional) – 下载文件保存的文件夹。默认值为None，表示不保存下载内容。

  • 描述 (str, 可选) – 代理的描述。默认值为 MultimodalWebSurfer.DEFAULT_DESCRIPTION。

  • debug_dir (str, optional) – 保存调试信息的目录。默认为 None。

  • headless (bool, 可选) – 浏览器是否应为无头模式。默认为 True。

  • start_page (str, optional) – 浏览器的起始页面。默认为 MultimodalWebSurfer.DEFAULT_START_PAGE。

  • animate_actions (bool, 可选) – 是否对操作进行动画处理。默认为 False。

  • to_save_screenshots (bool, optional) – 是否保存截图。默认为 False。

  • use_ocr (bool, optional) – 是否使用OCR。默认为 False。

  • browser_channel (str, 可选) – 浏览器通道。默认为 None。

  • browser_data_dir (str, optional) – 浏览器数据目录。默认为 None。

  • to_resize_viewport (bool, optional) – 是否调整视口大小。默认为 True。

  • playwright (Playwright, 可选) – Playwright 实例。默认为 None。

  • context (BrowserContext, optional) – 浏览器上下文。默认值为None。

示例用法：

以下示例展示了如何使用模型客户端创建一个网页浏览代理并运行多个回合。

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())
DEFAULT_DESCRIPTION = '\n    A helpful assistant with access to a web browser.\n    Ask them to perform web searches, open pages, and interact with content (e.g., clicking links, scrolling the viewport, filling in form fields, etc.).\n    It can also summarize the entire page, or answer questions based on the content of the page.\n    It can also be asked to sleep and wait for pages to load, in cases where the page seems not yet fully loaded.\n    '#
DEFAULT_START_PAGE = 'https://www.bing.com/'#
MLM_HEIGHT = 765#
MLM_WIDTH = 1224#
SCREENSHOT_TOKENS = 1105#
VIEWPORT_HEIGHT = 900#
VIEWPORT_WIDTH = 1440#
classmethod _from_config(config: MultimodalWebSurferConfig) → 自我[源代码]#

从配置对象创建组件的新实例。

Parameters:

config (T) – 配置对象。

Returns:

Self – 组件的新实例。

_to_config() → MultimodalWebSurferConfig[源代码]#

导出配置，该配置将用于创建一个与此实例配置相匹配的组件新实例。

Returns:

T – 组件的配置。

async close() → 无[源代码]#

关闭浏览器和页面。 当不再需要代理时，应调用此操作。

component_config_schema#

别名MultimodalWebSurferConfig

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

覆盖组件的提供商字符串。这应用于防止内部模块名称成为模块名称的一部分。

component_type: ClassVar[ComponentType] = 'agent'#

组件的逻辑类型。

async on_messages(messages: Sequence[Annotated[TextMessage | MultiModalMessage | StopMessage | 工具调用摘要信息 | HandoffMessage, FieldInfo(annotation=NoneType, required=True, discriminator='type')]], cancellation_token: CancellationToken) → 响应[源代码]#

处理传入的消息并返回响应。

注意

代理是有状态的，传递给此方法的消息应该是自上次调用此方法以来的新消息。代理应该在调用此方法之间保持其状态。例如，如果代理需要记住先前的消息以响应当前消息，它应将先前的消息存储在代理状态中。

async on_messages_stream(messages: Sequence[Annotated[TextMessage | MultiModalMessage | StopMessage | 工具调用摘要信息 | HandoffMessage, FieldInfo(annotation=NoneType, required=True, discriminator='type')]], cancellation_token: CancellationToken) → AsyncGenerator[Annotated[ToolCallRequestEvent | ToolCallExecutionEvent | MemoryQueryEvent | UserInputRequestedEvent | ModelClientStreamingChunkEvent | ThoughtEvent, FieldInfo(annotation=NoneType, required=True, discriminator='type')] | Annotated[TextMessage | MultiModalMessage | StopMessage | 工具调用摘要信息 | HandoffMessage, FieldInfo(annotation=NoneType, required=True, discriminator='type')] | 响应, 无][源代码]#

处理传入的消息并返回消息流，最后一项是响应。在BaseChatAgent中的基本实现只是调用on_messages()并生成响应中的消息。

注意

代理是有状态的，传递给此方法的消息应该是自上次调用此方法以来的新消息。代理应该在调用此方法之间保持其状态。例如，如果代理需要记住之前的消息以响应当前消息，它应该将之前的消息存储在代理状态中。

async on_reset(cancellation_token: CancellationToken) → 无[源代码]#

将代理重置为其初始化状态。

property produced_message_types: Sequence[类型[Annotated[TextMessage | MultiModalMessage | StopMessage | 工具调用摘要信息 | HandoffMessage, FieldInfo(annotation=NoneType, required=True, discriminator='type')]]]#

代理在Response.chat_message字段中生成的消息类型。它们必须是ChatMessage类型。

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

基础: object

一个帮助类，允许 Playwright 与网页交互以执行诸如点击、填写和滚动等操作。

Parameters:

  • downloads_folder (str | None) – 保存下载文件的文件夹。如果为None，则下载不会被保存。

  • animate_actions (bool) – 是否动画化操作（创建假的光标来点击）。

  • viewport_width (int) – 视口的宽度。

  • viewport_height (int) – 视口的高度。

  • _download_handler (Optional[Callable[[Download], None]]) – 一个用于处理下载的函数。

  • to_resize_viewport (bool) – 是否调整视口大小

async add_cursor_box(page: Page, identifier: str) → 无[源代码]#

在具有给定标识符的元素周围添加红色光标框。

Parameters:

  • page (Page) – Playwright 页面对象。

  • identifier (str) – 元素标识符。

async back(page: Page) → 无[源代码]#

返回上一页。

Parameters:

页面 (页面) – Playwright 页面对象。

async click_id(page: Page, identifier: str) → Page | 无[源代码]#

点击具有给定标识符的元素。

Parameters:

  • page (Page) – Playwright 页面对象。

  • identifier (str) – 元素标识符。

Returns:

页面 | 无 – 如果打开了新页面，则为新页面，否则为无。

async fill_id(page: Page, identifier: str, value: str, press_enter: bool = True) → 无[源代码]#

用指定的值填充具有给定标识符的元素。

Parameters:

  • page (Page) – Playwright 页面对象。

  • identifier (str) – 元素标识符。

  • value (str) – 要填充的值。

async get_focused_rect_id(page: Page) → str | 无[源代码]#

获取当前聚焦元素的ID。

Parameters:

页面 (页面) – Playwright 页面对象。

Returns:

str – 获取焦点元素的ID，如果没有控件获得焦点，则为None。

async get_interactive_rects(page: Page) → 字典[str, InteractiveRegion][源代码]#

从网页中检索交互区域。

Parameters:

页面 (页面) – Playwright 页面对象。

Returns:

Dict[str, InteractiveRegion] – 交互区域的字典。

async get_page_markdown(page: Page) → str[源代码]#

检索网页的markdown内容。 目前未实现。

Parameters:

页面 (页面) – Playwright 页面对象。

Returns:

str – 页面的Markdown内容。

async get_page_metadata(page: Page) → 字典[str, 任何][源代码]#

从网页中检索元数据。

Parameters:

页面 (页面) – Playwright 页面对象。

Returns:

Dict[str, Any] – 页面元数据的字典。

async get_visible_text(page: Page) → str[源代码]#

获取浏览器视口的文本内容（大约）。

Parameters:

页面 (页面) – Playwright 页面对象。

Returns:

str – 页面的文本内容。

async get_visual_viewport(page: Page) → VisualViewport[源代码]#

检索网页的视觉视口。

Parameters:

页面 (页面) – Playwright 页面对象。

Returns:

VisualViewport – 页面的可视视口。

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

获取网页的文本内容。

Parameters:

  • page (Page) – Playwright 页面对象。

  • n_lines (int) – 从页面内部文本返回的行数。

Returns:

str – 页面的文本内容。

async gradual_cursor_animation(page: Page, start_x: float, start_y: float, end_x: float, end_y: float) → 无[源代码]#

将光标移动从起始坐标逐渐动画到结束坐标。

Parameters:

  • page (Page) – Playwright 页面对象。

  • start_x (float) – 初始的x坐标。

  • start_y (float) – 起始 y 坐标。

  • end_x (float) – 结束的x坐标。

  • end_y (float) – 结束的y坐标。

async hover_id(page: Page, identifier: str) → 无[源代码]#

将鼠标悬停在使用给定标识符的元素上。

Parameters:

  • page (Page) – Playwright 页面对象。

  • identifier (str) – 元素标识符。

async on_new_page(page: Page) → 无[源代码]#

处理在新页面上执行的操作。

Parameters:

页面 (页面) – Playwright 页面对象。

async page_down(page: Page) → 无[源代码]#

将页面向下滚动一个视口高度减去50像素。

Parameters:

页面 (页面) – Playwright 页面对象。

async page_up(page: Page) → 无[源代码]#

将页面向上滚动一个视口高度减去50像素。

Parameters:

页面 (页面) – Playwright 页面对象。

async remove_cursor_box(page: Page, identifier: str) → 无[源代码]#

移除具有给定标识符的元素周围的红色光标框。

Parameters:

  • page (Page) – Playwright 页面对象。

  • identifier (str) – 元素标识符。

async scroll_id(page: Page, identifier: str, direction: str) → 无[源代码]#

滚动具有给定标识符的元素在指定方向。

Parameters:

  • page (Page) – Playwright 页面对象。

  • identifier (str) – 元素标识符。

  • direction (str) – 滚动的方向（“向上”或“向下”）。

async sleep(page: Page, duration: int | float) → 无[源代码]#

暂停执行指定的持续时间。

Parameters:

  • page (Page) – Playwright 页面对象。

  • duration (Union[int, float]) – 休眠的持续时间，单位为毫秒。

async visit_page(page: Page, url: str) → 元组[bool, bool][源代码]#

访问指定的URL。

Parameters:

  • page (Page) – Playwright 页面对象。

  • url (str) – 要访问的URL。

Returns:

Tuple[bool, bool] – 一个元组，指示是否重置先前的元数据哈希和最后一次下载。