Skip to main content
Use the agent for model-driven browser work. Use SDK resources around it when the workflow needs explicit lifecycle, policy, files, downloads, status, recordings, validation, retries, persistence, or recovery.

Browser envelope

Create or resume the browser in application code, then pass its browserId into the agent run.
The SDK keeps browser boundaries and durable resources explicit around the agent run. When you pass browserId, keep browser policy on the explicit browser, not on the agent config.

Same-browser session loop

Use agent.session(...) when related goals should share a browser.
Sessions keep the same browser alive across related goals. Include the important context in each follow-up goal so the model has the details it needs.

Resource handoff

Stage files in deterministic code and tell the agent how to use the staged file id in browser work.
A staged SDK file id is not a local browser path. The browser-code helper files.path(fileId) resolves it inside the managed browser execution environment.

Verification gate

Validate the result before your application takes business action.
Use the model’s final text as a summary, not as the only evidence. Store structured output, source URLs, browser IDs, artifact IDs, page metadata, status, and recordings when the workflow needs auditability.

Recovery loop

When a run blocks or fails, application code can inspect state and continue with more context.
Use this pattern for long-running tasks, blockers, CAPTCHA review, transient failures, and workflows that need durable retry behavior.

Advanced exact browser step

Use exact browser control only when the browser step itself must be deterministic. Keep the step bounded, then return to the agent or SDK resource APIs.
When exact control creates a download, handle that artifact through browser.downloads. Do not assume the agent can read SDK download artifacts unless your workflow explicitly feeds their contents back into a later model or browser step.

Choose the right layer

  • Use agent.run(...) for live browser work.
  • Use application code for business rules your product must enforce every time.
  • Use browser resources for lifecycle, files, downloads, page metadata, status, recordings, and recovery.
  • Use exact browser control only when a specific browser step must be deterministic.
Reference: SDK agent reference, SDK browser reference, SDK resources reference, and runtime browser control.