Skip to content

For the complete documentation index, see llms.txt. Markdown versions are available by appending .md to documentation page URLs. Read the agent handbook.

Zortex Docs
Start searching Install Vision
Browser sessions and profiles

Browser sessions and profiles

Choose the right browser context, reuse a live session, and recover without repeating completed actions.

On this page

A browser session is the live page context used by a task. A browser profile contains site state such as sign-ins. Opening a session does not guarantee that it uses the profile or account you need.

Choose the right starting context

Task Starting point What to check
Read public content browser.open with sessionMode: "isolated". The expected URL and page contents.
Work with an existing login An available authorized background profile route, or the source's supported connection flow. The actual signed-in account and target resource.
Continue an app connection Its current browserContinuation.sessionId or live connection-help page. The original source, account, and connection job.
Continue a browser goal The session returned by browser.run_goal. Its current snapshot, remaining goal, and retained input names.

isolated forces an owned headless session without personal-profile or native fallback. automatic tries the available background route and can use an owned headless profile. It is not a promise to attach to your current Chrome window or reuse its login.

If you name an account or profile, the agent should keep that choice throughout the task. A working browser with the wrong account is not ready for the requested work.

Reuse a live session

Use the returned ID for every operation on the page:

Shell
indra --root "$indra_root" action --json '{"name":"browser.observe","params":{"sessionId":"<returned-sessionId>"}}'

Here $indra_root is your existing Vault path, as set in Use a browser. After navigation or a popup closes, inspect the current snapshot before choosing another control. Keep the latest control object; an earlier page's control may no longer be valid.

The built-in provider retains at most eight active sessions. An idle session can expire after ten minutes without use. These are browser-session limits, not a guarantee that a whole delegated task is saved or resumed.

When finished, call browser.close and check for cleanup: "confirmed". Close only the sessions owned by your task.

Continue with retained inputs

A browser goal or connection continuation may return inputNames. These identify local values retained for that task. With a current control, browser.type can use inputName instead of sending the value again.

Use only a name actually returned by the continuation and only for its intended page and account. If the needed value is absent, follow the supported sign-in or input path. Do not put credentials into an ordinary task summary.

Recover an expired or interrupted session

  1. Check whether the intended action already happened. A provider read or saved object may establish the result even if the browser is gone.
  2. For a connection flow, inspect the original connection job or reopen connection help. Do not replay an old authorization URL.
  3. Open a fresh session only for the remaining work. Observe the starting state before acting.
  4. Preserve the same account, destination, and completed changes.

If a response disappeared after a submission, do not assume that the submission failed. Repeating it can create a duplicate. If no available read can settle the outcome, keep that uncertainty explicit.

A session ID is a reference to a live owner, not a saved browser checkpoint. Restarting the owner may lose it. For continuing the wider task, save the handoff described in Continue work.

Suggested