> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camel-ai.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Camel.toolkits.browser toolkit

<a id="camel.toolkits.browser_toolkit" />

<a id="camel.toolkits.browser_toolkit._get_str" />

## \_get\_str

```python theme={"system"}
def _get_str(d: Any, k: str):
```

Safely retrieve a string value from a dictionary.

<a id="camel.toolkits.browser_toolkit._get_number" />

## \_get\_number

```python theme={"system"}
def _get_number(d: Any, k: str):
```

Safely retrieve a number (int or float) from a dictionary

<a id="camel.toolkits.browser_toolkit._get_bool" />

## \_get\_bool

```python theme={"system"}
def _get_bool(d: Any, k: str):
```

Safely retrieve a boolean value from a dictionary.

<a id="camel.toolkits.browser_toolkit.BaseBrowser" />

## BaseBrowser

```python theme={"system"}
class BaseBrowser:
```

<a id="camel.toolkits.browser_toolkit.BaseBrowser.__init__" />

### **init**

```python theme={"system"}
def __init__(
    self,
    headless = True,
    cache_dir: Optional[str] = None,
    channel: Literal['chrome', 'msedge', 'chromium'] = 'chromium',
    cookie_json_path: Optional[str] = None,
    user_data_dir: Optional[str] = None
):
```

Initialize the WebBrowser instance.

**Parameters:**

* **headless** (bool): Whether to run the browser in headless mode.
* **cache\_dir** (Union\[str, None]): The directory to store cache files.
* **channel** (`Literal["chrome", "msedge", "chromium"]`): The browser channel to use. Must be one of "chrome", "msedge", or "chromium".
* **cookie\_json\_path** (Optional\[str]): Path to a JSON file containing authentication cookies and browser storage state. If provided and the file exists, the browser will load this state to maintain authenticated sessions. This is primarily used when `user_data_dir` is not set.
* **user\_data\_dir** (Optional\[str]): The directory to store user data for persistent context. If None, a fresh browser instance is used without saving data. (default: :obj:`None`)

**Returns:**

None

<a id="camel.toolkits.browser_toolkit.BaseBrowser.init" />

### init

```python theme={"system"}
def init(self):
```

Initialize the browser.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.clean_cache" />

### clean\_cache

```python theme={"system"}
def clean_cache(self):
```

Delete the cache directory and its contents.

<a id="camel.toolkits.browser_toolkit.BaseBrowser._wait_for_load" />

### \_wait\_for\_load

```python theme={"system"}
def _wait_for_load(self, timeout: int = 20):
```

Wait for a certain amount of time for the page to load.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.click_blank_area" />

### click\_blank\_area

```python theme={"system"}
def click_blank_area(self):
```

Click a blank area of the page to unfocus the current element.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.visit_page" />

### visit\_page

```python theme={"system"}
def visit_page(self, url: str):
```

Visit a page with the given URL.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.ask_question_about_video" />

### ask\_question\_about\_video

```python theme={"system"}
def ask_question_about_video(self, question: str):
```

Ask a question about the video on the current page,
such as YouTube video.

**Parameters:**

* **question** (str): The question to ask.

**Returns:**

str: The answer to the question.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.get_screenshot" />

### get\_screenshot

```python theme={"system"}
def get_screenshot(self, save_image: bool = False):
```

Get a screenshot of the current page.

**Parameters:**

* **save\_image** (bool): Whether to save the image to the cache directory.

**Returns:**

Tuple\[Image.Image, str]: A tuple containing the screenshot
image and the path to the image file if saved, otherwise
:obj:`None`.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.capture_full_page_screenshots" />

### capture\_full\_page\_screenshots

```python theme={"system"}
def capture_full_page_screenshots(self, scroll_ratio: float = 0.8):
```

Capture full page screenshots by scrolling the page with a buffer
zone.

**Parameters:**

* **scroll\_ratio** (float): The ratio of viewport height to scroll each step. (default: :obj:`0.8`)

**Returns:**

List\[str]: A list of paths to the screenshot files.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.get_visual_viewport" />

### get\_visual\_viewport

```python theme={"system"}
def get_visual_viewport(self):
```

**Returns:**

VisualViewport: The visual viewport of the current page.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.get_interactive_elements" />

### get\_interactive\_elements

```python theme={"system"}
def get_interactive_elements(self):
```

**Returns:**

Dict\[str, InteractiveRegion]: A dictionary of interactive elements.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.get_som_screenshot" />

### get\_som\_screenshot

```python theme={"system"}
def get_som_screenshot(self, save_image: bool = False):
```

Get a screenshot of the current viewport with interactive elements
marked.

**Parameters:**

* **save\_image** (bool): Whether to save the image to the cache directory.

**Returns:**

Tuple\[Image.Image, Union\[str, None]]: A tuple containing the
screenshot image
and an optional path to the image file if saved, otherwise
:obj:`None`.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.scroll_up" />

### scroll\_up

```python theme={"system"}
def scroll_up(self):
```

Scroll up the page.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.scroll_down" />

### scroll\_down

```python theme={"system"}
def scroll_down(self):
```

Scroll down the page.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.get_url" />

### get\_url

```python theme={"system"}
def get_url(self):
```

Get the URL of the current page.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.click_id" />

### click\_id

```python theme={"system"}
def click_id(self, identifier: Union[str, int]):
```

Click an element with the given identifier.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.extract_url_content" />

### extract\_url\_content

```python theme={"system"}
def extract_url_content(self):
```

Extract the content of the current page.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.download_file_id" />

### download\_file\_id

```python theme={"system"}
def download_file_id(self, identifier: Union[str, int]):
```

Download a file with the given selector.

**Parameters:**

* **identifier** (str): The identifier of the file to download.

**Returns:**

str: The result of the action.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.fill_input_id" />

### fill\_input\_id

```python theme={"system"}
def fill_input_id(self, identifier: Union[str, int], text: str):
```

Fill an input field with the given text, and then press Enter.

**Parameters:**

* **identifier** (str): The identifier of the input field.
* **text** (str): The text to fill.

**Returns:**

str: The result of the action.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.scroll_to_bottom" />

### scroll\_to\_bottom

```python theme={"system"}
def scroll_to_bottom(self):
```

<a id="camel.toolkits.browser_toolkit.BaseBrowser.scroll_to_top" />

### scroll\_to\_top

```python theme={"system"}
def scroll_to_top(self):
```

<a id="camel.toolkits.browser_toolkit.BaseBrowser.hover_id" />

### hover\_id

```python theme={"system"}
def hover_id(self, identifier: Union[str, int]):
```

Hover over an element with the given identifier.

**Parameters:**

* **identifier** (str): The identifier of the element to hover over.

**Returns:**

str: The result of the action.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.find_text_on_page" />

### find\_text\_on\_page

```python theme={"system"}
def find_text_on_page(self, search_text: str):
```

Find the next given text on the page, and scroll the page to the
targeted text. It is equivalent to pressing Ctrl + F and searching for
the text.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.back" />

### back

```python theme={"system"}
def back(self):
```

Navigate back to the previous page.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.close" />

### close

```python theme={"system"}
def close(self):
```

<a id="camel.toolkits.browser_toolkit.BaseBrowser.show_interactive_elements" />

### show\_interactive\_elements

```python theme={"system"}
def show_interactive_elements(self):
```

Show simple interactive elements on the current page.

<a id="camel.toolkits.browser_toolkit.BaseBrowser.get_webpage_content" />

### get\_webpage\_content

```python theme={"system"}
def get_webpage_content(self):
```

<a id="camel.toolkits.browser_toolkit.BaseBrowser._ensure_browser_installed" />

### \_ensure\_browser\_installed

```python theme={"system"}
def _ensure_browser_installed(self):
```

Ensure the browser is installed.

<a id="camel.toolkits.browser_toolkit.BrowserToolkit" />

## BrowserToolkit

```python theme={"system"}
class BrowserToolkit(BaseToolkit):
```

A class for browsing the web and interacting with web pages.

This class provides methods for browsing the web and interacting with web
pages.

<a id="camel.toolkits.browser_toolkit.BrowserToolkit.__init__" />

### **init**

```python theme={"system"}
def __init__(
    self,
    headless: bool = False,
    cache_dir: Optional[str] = None,
    channel: Literal['chrome', 'msedge', 'chromium'] = 'chromium',
    history_window: int = 5,
    web_agent_model: Optional[BaseModelBackend] = None,
    planning_agent_model: Optional[BaseModelBackend] = None,
    output_language: str = 'en',
    cookie_json_path: Optional[str] = None,
    user_data_dir: Optional[str] = None
):
```

Initialize the BrowserToolkit instance.

**Parameters:**

* **headless** (bool): Whether to run the browser in headless mode. When running inside a CAMEL runtime container, this is automatically set to True since containers typically don't have a display.
* **cache\_dir** (Union\[str, None]): The directory to store cache files.
* **channel** (`Literal["chrome", "msedge", "chromium"]`): The browser channel to use. Must be one of "chrome", "msedge", or "chromium".
* **history\_window** (int): The window size for storing the history of actions.
* **web\_agent\_model** (Optional\[BaseModelBackend]): The model backend for the web agent.
* **planning\_agent\_model** (Optional\[BaseModelBackend]): The model backend for the planning agent.
* **output\_language** (str): The language to use for output. (default: :obj:`"en`")
* **cookie\_json\_path** (Optional\[str]): Path to a JSON file containing authentication cookies and browser storage state. If provided and the file exists, the browser will load this state to maintain authenticated sessions without requiring manual login. (default: :obj:`None`)
* **user\_data\_dir** (Optional\[str]): The directory to store user data for persistent context. If None, a fresh browser instance is used without saving data. (default: :obj:`None`)

<a id="camel.toolkits.browser_toolkit.BrowserToolkit._reset" />

### \_reset

```python theme={"system"}
def _reset(self):
```

<a id="camel.toolkits.browser_toolkit.BrowserToolkit._initialize_agent" />

### \_initialize\_agent

```python theme={"system"}
def _initialize_agent(
    self,
    web_agent_model_backend: Optional[BaseModelBackend],
    planning_agent_model_backend: Optional[BaseModelBackend]
):
```

Initialize the agent.

<a id="camel.toolkits.browser_toolkit.BrowserToolkit._observe" />

### \_observe

```python theme={"system"}
def _observe(self, task_prompt: str, detailed_plan: Optional[str] = None):
```

Let agent observe the current environment, and get the next
action.

<a id="camel.toolkits.browser_toolkit.BrowserToolkit._act" />

### \_act

```python theme={"system"}
def _act(self, action_code: str):
```

Let agent act based on the given action code.

**Parameters:**

* **action\_code** (str): The action code to act.

**Returns:**

Tuple\[bool, str]: A tuple containing a boolean indicating whether
the action was successful, and the information to be returned.

<a id="camel.toolkits.browser_toolkit.BrowserToolkit._get_final_answer" />

### \_get\_final\_answer

```python theme={"system"}
def _get_final_answer(self, task_prompt: str):
```

Get the final answer based on the task prompt and current
browser state.
It is used when the agent thinks that the task can be completed
without any further action, and answer can be directly found in the
current viewport.

<a id="camel.toolkits.browser_toolkit.BrowserToolkit._task_planning" />

### \_task\_planning

```python theme={"system"}
def _task_planning(self, task_prompt: str, start_url: str):
```

Plan the task based on the given task prompt.

<a id="camel.toolkits.browser_toolkit.BrowserToolkit._task_replanning" />

### \_task\_replanning

```python theme={"system"}
def _task_replanning(self, task_prompt: str, detailed_plan: str):
```

Replan the task based on the given task prompt.

**Parameters:**

* **task\_prompt** (str): The original task prompt.
* **detailed\_plan** (str): The detailed plan to replan.

**Returns:**

Tuple\[bool, str]: A tuple containing a boolean indicating
whether the task needs to be replanned, and the replanned schema.

<a id="camel.toolkits.browser_toolkit.BrowserToolkit.browse_url" />

### browse\_url

```python theme={"system"}
def browse_url(
    self,
    task_prompt: str,
    start_url: str,
    round_limit: int = 12
):
```

A powerful toolkit which can simulate the browser interaction to
solve the task which needs multi-step actions.

**Parameters:**

* **task\_prompt** (str): The task prompt to solve.
* **start\_url** (str): The start URL to visit.
* **round\_limit** (int): The round limit to solve the task. (default: :obj:`12`).

**Returns:**

str: The simulation result to the task.

<a id="camel.toolkits.browser_toolkit.BrowserToolkit.get_tools" />

### get\_tools

```python theme={"system"}
def get_tools(self):
```