lupin.Open console
Browsers

Choose research or an interactive browser session

Choose temporary public research for evidence gathering and a managed session when a task needs page state or human interaction.

Lupin editorialAI-assisted3 min read

Choose by the state the task needs

Use public research when the deliverable is information from public pages and the task can finish in one bounded operation. Use an interactive session when the work needs several page actions, a deliberate tab arrangement, an authenticated page or a human takeover. The distinction is about workflow state, not whether a browser renders the source. Lupin's research endpoint also uses Cloudflare Browser Run for source reading. Keeping an interactive browser open merely to fetch one public document adds lifecycle work that a temporary research operation already handles for you.

Know what search actually returns

A research search request contains action search and a query of at most 500 characters. The configured Composio search service produces result URLs and snippets; Cloudflare then attempts to open a suitable source. The response separates search.results from sources. A search snippet is evidence that the search provider returned that text, not evidence that Lupin successfully read the underlying page. The current source reader considers a bounded candidate set and stops after its first usable source. A result containing several snippets therefore should not be described as a comprehensive reading of every linked document.

Use explicit reading for a known source

If you already know the public document URL, request action read rather than spending a search action to rediscover it. Reading uses browser runtime, while search also consumes an app action. Both research modes require a stable Idempotency-Key and create and delete permissions because they allocate and close a temporary session. Public URL validation rejects credentials in URLs, private destinations and custom ports. A public website that is unavailable or blocked can still fail after input validation. Preserve that distinction when reporting why an evidence request did not finish.

Illustrative request; source reviewed, not executed against a live provider.
{"action":"read","url":"https://example.com"}

Move to interaction deliberately

An interactive session exposes tabs, navigation, reading, screenshots and a fixed action catalog. It is useful when the agent must observe a form, select an exact visible control, act and inspect the resulting state. It is also where a human can complete an authorized sign-in through live view. Do not assume research inherits the user's local cookies or API authorization header; the public reader does not forward those credentials. If the desired evidence is behind a login, ask the authorized owner to use the appropriate session or app connection instead of treating a public-read failure as a parsing problem.

Evaluate evidence and cleanup separately

For research, inspect source URLs, retrieval times, visible text and session_closed. If cleanup_pending is present, the information result and resource cleanup have different outcomes, and both need tracking. An empty sources array can mean the chosen pages were too short, blocked or unusable even when search results exist. For interaction, record the session identifier and end it after saving evidence. Neither route creates durable browser profiles. A practical decision rule is to begin with the smallest operation that can answer the question, then move to a managed session only when an observed need for page state justifies it.

Sources & verification

Reviewed against the current Lupin route, provider adapter and shared input contracts, plus the linked official references. Examples were not run against live services.

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.

Put it into practice

Give your agent the right tools.

Review the API, workspace requirements and permissions before enabling a workflow.

Explore browsers