How to give an agent a browser for a bounded task

Create a bounded Browserbase session through Vaaya, let your agent inspect one permitted workflow, verify its result and release the session.

Use a browser when the task needs an interaction: opening a filter, selecting a date, inspecting a rendered state or checking a flow on your own site. Define the end state before creating a session so the agent knows when to stop.

This guide uses Vaaya's Browserbase route for a small, read-only task. The agent will open one public page, apply a specified filter and return the visible matching items. The example is a workflow template, not a report of a completed browser run.

1. Bound the task before opening a session

Connect the agent using Vaaya's installation guide. It also needs a compatible browser controller that can connect to a remote session. Vaaya provisions the browser; the agent's controller performs navigation and inspection.

Give the agent the starting URL, allowed domain, permitted actions and output fields. A useful first task is: open your public product directory, select one category and record the first page of results. State whether following result links is allowed and whether pagination is in scope.

Keep state-changing actions explicit. Reading a draft is different from publishing it; filling a form is different from submitting it. For this first run, allow navigation and filters only, with no sign-in, submission, purchase or message sending.

2. Plan the session and its budget

Ask consult for the current browser route and price. The Vaaya catalog lists browserbase/create_session, session_status, extend_session and release_session.

The current create schema accepts estimatedMinutes, with a five-minute minimum. Check the current quote for the requested duration and include any proposed extension in the total budget. A longer session is a spending decision, not an automatic response to a slow page.

Paste this after replacing the brackets:

Use Vaaya to open a browser for this bounded task:
Start at [URL], stay on [domain], select [filter], and return
[visible fields] from [one page or another explicit limit].
Allowed actions: navigation, reading and the named filter.
Do not submit forms, send messages, purchase or change accounts.
My total session budget is [amount]. Check the current schema
and quote, set a call ceiling, then create one session.
Verify the visible result. Stop on login requirements, an
unexpected side effect or exhausted scope. Release the session
when finished, including if the task fails.

3. Connect and inspect the current page

Create the session within the approved budget. The route returns a session identifier and connection URL. Keep connection details out of public logs and pass them to the agent's supported browser controller.

Have the agent inspect the page before choosing a control. It should use the labels and structure it actually sees rather than replaying a guessed sequence from an old layout. After applying the filter, wait for the visible result to update and inspect it again.

If the controller cannot attach, check session_status using session_id before buying another session. Preserve the error and release a session you cannot use. Do not assume a different paid browser will remove the same site's access restrictions.

4. Verify the result against the task

Check that the selected filter is visible and that the returned items belong to it. Capture the relevant labels, result URLs and retrieval time. If only the first page was reviewed, say so; a first-page result count is not a complete inventory.

An illustrative handoff could use this shape:

{
  "starting_url": "https://example.com/directory",
  "requested_filter": "Analytics",
  "observed_filter": null,
  "items": [],
  "coverage": "One results page requested",
  "completion": "Example only; browser task not run",
  "session_released": null
}

Populate the observed fields from the actual browser state. A successful click does not establish that the intended filter took effect.

5. Release the session and report what happened

Call browserbase/release_session with session_id after collecting the result. Put cleanup in the failure path too. If release fails, report that failure and check session status; do not mark cleanup complete without evidence.

Return the result, coverage limit, actual charge and any unresolved obstacle. If the task needed more time, keep the partial evidence and explain the next action before extending the session. Current call fields are available in the tool reference.

For the next run, narrow the workflow around the obstacle you observed. A bounded task is easier to repeat when its start page, allowed actions, completion check and cleanup are all recorded.

Questions

Does creating a browser session perform the task for me?

No. It provisions a browser and returns connection details. Your agent needs a compatible browser controller to navigate, click and inspect the page.

Can a browser session always access a blocked website?

No. A session can still encounter login requirements, site restrictions or verification challenges. Record the limitation and use a permitted route rather than assuming a session guarantees access.

What should happen when the task finishes or fails?

Preserve the requested result and observed state, then release the session. Do not create repeated sessions or extend paid time automatically when the approved scope or budget has been exhausted.