# Browser

Source: https://www.hyperagent.com/docs/tools/browser

> For AI agents: the documentation index is at https://www.hyperagent.com/llms.txt and the complete documentation in one file at https://www.hyperagent.com/llms-full.txt. Any docs page is also served as Markdown by appending `.md` to its URL.

Use a live browser to navigate sites, complete forms, work behind logins, hand control to a person, and capture evidence.

Some work ends with an answer. Other work has to happen on a site: compare inventory behind filters, upload a file, complete a form, verify a published page, or work inside a signed-in account. The **Browser** tool gives the agent a live browser for that work.

Watch the live session from the browser panel and take control at any point.
When a login, two-factor prompt, CAPTCHA, or judgment call needs you, the
agent hands over the same session and continues from the state you leave
behind.

## What the agent can do in the browser [#what-the-agent-can-do-in-the-browser]

Navigate, click, type, scroll, fill forms, and upload files from the thread.
It can also run a page script when a widget resists ordinary clicks.

Observe what's on screen, extract comparable structured data across pages,
and pull text or HTML directly.

Take screenshots and keep the good ones as thread assets. Hyperagent records
every session, and the agent can save that recording as a video you can
watch, download, and share.

Take control of the live session for a login, challenge page, or judgment
call, then hand it back without losing progress.

## Choose the right web surface [#choose-the-right-web-surface]

| Surface              | Use it for                                                                    | What it can reach                                          |
| -------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Search**           | Finding and reading public information.                                       | Search results and public pages; no signed-in interaction. |
| **Browser**          | Forms, filters, uploads, logins, visual checks, and other live site work.     | Public internet sites and the session's saved login state. |
| **Workspace Chrome** | Testing local files, generated HTML, or a development server before shipping. | Files and servers inside the thread's private workspace.   |

Start with Search when the job is read-only. Use Browser when the agent needs to operate the site or when the page only works in a real browser. Use workspace Chrome for local development that's not yet reachable on the public internet.

## How a browser session works [#how-a-browser-session-works]

When the agent needs the browser, it opens a session: one live browser it drives for the length of a job. You can watch that session from the browser panel while the thread is open, and take it over yourself at any point without waiting for an invitation.

Sessions are time-bounded rather than permanent. Hyperagent releases a session that sits idle, and every session ends after about an hour. That keeps a long-running job from holding a browser open forever; when the agent needs the site again, it re-opens the page and carries on. A session ending loses nothing about the task, only the live browser itself.



## Hand off logins and challenge pages [#hand-off-logins-and-challenge-pages]

For a first-time login, two-factor prompt, CAPTCHA, or any step that needs your judgment, the agent hands you the live session. Complete the step in the browser panel, then return control. The agent continues from the signed-in state you left behind.

Handoff keeps the session alive past the agent's turn so it waits for you instead of timing out mid-step. Inside Hyperagent, use the browser panel directly. From an external channel, open the thread in Hyperagent first; only the account owner can enter the session.

## Two ways to stay signed in [#two-ways-to-stay-signed-in]

Every session starts clean unless you choose to preserve its login state. Hyperagent has two independent options, and a run uses only one:

|                                             | **Stay logged in**                                                | **Persistent sessions**                                                 |
| ------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Scope**                                   | One generalist thread.                                            | Every authorized run of one named agent.                                |
| **Best for**                                | Continuing one signed-in conversation.                            | An agent whose recurring work requires the same accounts.               |
| **Where to enable it**                      | In the live browser panel or the thread's settings, even mid-run. | On the agent before the run starts.                                     |
| **External Slack, email, or Telegram runs** | Not available.                                                    | Available because the agent owner explicitly enabled unattended access. |
| **How to clear it**                         | Select **Delete saved logins** on the thread.                     | Turn persistent sessions off on the agent.                              |

When the agent finishes a sign-in during a handoff, a consent card offers to keep that login. Accept mid-run and Hyperagent queues the save until the turn ends, so keeping a login never interrupts the work in progress.

## Saved logins stay scoped to you [#saved-logins-stay-scoped-to-you]

A browser with saved logins acts inside a site as you, so Hyperagent keeps that state within strict boundaries:

* **Teammates running a shared agent get a clean browser.** An agent's persistent sessions attach only to runs its owner authorizes, never to a teammate's run of that shared agent.
* **You can always delete the state.** Delete saved logins on a thread, turn persistent sessions off on an agent, or delete the thread. Each action destroys the stored login state.
* **A thread's logins expire on their own.** Hyperagent deletes a thread's saved logins after the conversation sits untouched for about thirty days.
* **Binding a thread to an agent releases the thread's own logins**, since the agent's setting takes over from there.

The thread's history records everything the browser does in it.

## Recordings and screenshots [#recordings-and-screenshots]

Hyperagent records every session automatically. Ask the agent to save the recording and it becomes an MP4 thread asset you can watch, download, and share. Saving it finalizes the recording and closes the active session, so this should be the final browser step in a job.

Screenshots work differently. The agent can inspect a screenshot privately, then save the useful frames as visible thread assets. That keeps failed or irrelevant captures out of the conversation.

## FAQs [#faqs]

It hands you the live session. You sign in yourself in the browser panel, clearing any two-factor prompt, and the agent continues from the signed-in state. A consent card then offers to keep the login for next time; the agent saves nothing unless you accept.

Only if you ask it to. Turn on persistent sessions on the agent to keep logins across all its runs, or Stay logged in on a generalist thread to keep them for that one conversation. Otherwise every session starts from a clean browser.

No. An agent's persistent sessions attach only to runs its owner authorizes, so a teammate running the same shared agent gets a clean browser. A thread's Stay logged in state belongs to that one conversation of yours.

Sessions are time-bounded: Hyperagent releases an idle one, and every session ends after about an hour. The task isn't lost, only the live browser. The agent re-opens the page it needs and carries on. This is also why a long job re-navigates rather than holding one browser open the whole time.

Take over. When a site throws a challenge page or a step the agent can't clear, it hands you the live session and you handle it in the browser panel; the agent resumes from where you leave the page.

Screenshots the agent decides to keep become assets in the thread. Hyperagent records every session, and a saved recording lands in the thread as an MP4 you can watch, download, and share. Saving a recording finalizes it and closes the session, so it comes at the end of a browser job.

Browser can't open `localhost` servers or `file://` paths from the thread workspace. For local rendering and testing, use the sandbox's headless Chrome; [Data and code explains how the sandbox connects to the rest of Hyperagent](https://www.hyperagent.com/docs/tools/data-and-code#how-the-sandbox-meets-the-rest-of-the-platform).