Browser Agent

What it is

The Browser Agent runs a headless Chromium browser driven by a language model. At each step the model looks at the page, picks an action (open a URL, click, type, scroll, read), and the browser performs it. The session ends when the model decides the task is done or when a limit is reached.

You can run it from two places, and both use the same engine:

• Workflow node: the Browser Agent node runs one browsing session each time it executes. See Workflows for how nodes connect.
• Chat: ask a chat agent to browse a site. The agent starts a session through the agent_browse action of its web_search tool, can check on it with browse_status, and can stop it with browse_abort.

When to use it

A browser session is the most expensive web tool: it holds a real browser and a model context for the whole task, roughly a hundred times the cost of fetching a page. Chat agents are told to use it only when a plain search or page fetch cannot do the job, for example when content only appears after clicking through a site or filling in a form. Prefer a catalog integration or an HTTP request when the site has an API.

Before you begin

On a self-hosted install without the component:

• If the install is linked to the cloud with the Cloud model source, a Browser Agent node relays its session to the cloud, which runs it and bills your cloud account.
• Otherwise the node shows a notice in the builder and fails at run time with a message explaining how to enable it, and chat agents do not offer browsing.

docker compose --env-file .env --env-file docker/.env.ce.browser-agent up -d

Configure the node

1. 1
   Add the node
   Add a Browser Agent node to your workflow.
2. 2
   Write the task
   Fill in Task, the only required field. Be specific: vague tasks waste steps. The task supports {{...}} templates, so you can pass in data from earlier nodes.
3. 3
   Optionally set a start URL and a model
   Set Start URL if you know where the agent should begin. If you leave it empty, the agent picks a URL from the task. Pick a model, or leave it unset to use the platform default.

Model selection

The model must answer one step at a time as a plain chat completion. When no model is set, or when the requested model is not in the catalog, the platform uses the highest-ranked model of the browser agent category (set by an administrator on the Models page) and reports the substitution. CLI bridge models such as Claude Code or Codex are not used for automatic selection, because they run a whole agent session per call. See Models.

Outputs

Every session returns these fields:

Reference them downstream by the node label:

{{agent:price_check.output.final_result}}
{{agent:price_check.output.final_url}}
{{agent:price_check.output.pages_visited}}

Stop reasons

Any stop reason other than COMPLETED makes the node fail, with final_result as the error message, so one error branch catches every unsuccessful session.

Limits and concurrency

Each session holds a real Chromium process, so the platform bounds how many run at once and how many steps you use per day.

Time spent in the queue counts against the 600 seconds, with at least 30 seconds left to run. So a workflow that starts several browser sessions in parallel (for example in a split) runs them one after another for the same user instead of failing all but one. The limits apply the same way whatever model drives the session.

Live view and taking control

While a session runs, you can open a live view of the browser: in the workflow, with View live browser on the node; in chat, in the panel that appears in the conversation. Password, card number, and security code fields are masked in screenshots and in the live view.

Click the live view to take control. After you confirm with Yes, take control, the agent pauses at the next step boundary and you can use the page yourself. Select Resume agent to hand control back.

• The session clock keeps running while the agent is paused.
• If you stop interacting for 5 minutes, the agent resumes on its own.
• Typing into password, card number, and security code fields is blocked for the agent and for you, so you cannot sign in with a password during a session.

After the task finishes

If someone is watching the live view (or has taken control) when the agent finishes, the result is returned right away but the page stays open so you can keep using it. The browser closes 20 seconds after the last viewer leaves, after 5 minutes without input, or after 30 minutes in any case. You keep at most one open page: your next session closes the previous one. Held pages do not block new sessions.

Pricing

There is no per-step or per-session fee. Every model call of the session is priced at the rate of the model actually used, and the session appears in your credit history under Browser Agent, one entry per session. See Billing. On a self-hosted install that relays through the cloud, the usage is billed on the linked cloud account.

Troubleshooting

Related pages