Inspect and stop an agent browser

Inspect an agent's assigned browser before automated work, then stop that browser after the task finishes. These operations return browser metadata and preserve saved browser storage. Use the generated OpenAPI contract for exact request paths, fields, and response schemas.

Who can do this

Use a workspace API key created by a current workspace administrator. That administrator must also have permission to run the agent. The saved browser must have one exclusive grant to that agent and its home project.

Configure browser access and grants in the app before using automation. Workspace API keys cannot change browser access, start a private browser, or edit profile grants. Those operations require an interactive user token and the corresponding workspace permissions.

Control browser JavaScript

Browser access includes page JavaScript and authenticated page requests by default. The browser_evaluate tool can extract table data or run an asynchronous fetch() using the page's existing sign-in. Normal website cookie and CORS rules apply. Application-specific authorization headers are not supplied automatically.

JavaScript has normal page authority, including writes and reading page fields. Keep the agent's task permissions appropriate for the website. Browser Off, permitted websites, profile grants, and private control still apply.

Linked credential values are masked when they appear directly in browser text results. This does not guarantee credential secrecy from page JavaScript. After control returns to the agent, JavaScript can read values exposed by the website and return them in another form. Use accounts suitable for the agent's access.

A workspace administrator can opt out through the existing browser-access policy API by setting javascript_enabled to false. This change requires an interactive user token. Read the current policy and preserve its other fields when updating it. Omit javascript_enabled to keep its saved value, or set it to true to enable JavaScript again. Use the generated OpenAPI contract and SDK for exact request and response fields. The setting has no separate control in the app.

Evaluation accepts at most 64,000 source characters. Returned text is limited to 8,000 characters and shows an explicit truncation notice when needed. Request only the data your task requires. Evaluation does not add an automatic page snapshot.

After JavaScript runs, switching to private control restarts the browser before you can enter private information. Saved sign-ins and website storage remain available. A website can still expire its own sign-in. An interrupted evaluation is not repeated automatically; inspect the browser before deciding whether another action is safe.

1. Inspect the assigned browser

Read the agent's browser runtime metadata through the operation in OpenAPI. Confirm the agent, conversation, saved browser, and ownership before submitting work. Keep the conversation ID and current browser metadata with your task record.

The response contains metadata without page content or credentials. An idle agent alone does not establish that its browser is available. A person can hold private control or deliberately pause the browser. Inspect both the conversation and browser state.

2. Wait for the task to finish

Set the optional tool-call ceiling when submitting the task. It limits tool execution for the run. Use OpenAPI for the exact request field and supported limits. Keep the source turn ID returned for the task. Wait for that exact task to finish or cancel it and confirm that it has settled. Do not use another conversation or an unrelated task as cleanup authority.

Read the browser metadata again after settlement. Use the current browser state when requesting Stop. If that state changed, inspect it again before deciding which task owns the browser.

3. Request Stop and confirm the result

Submit the stop operation with the conversation ID, source turn ID, and current browser state. Read the result and confirm that the browser is stopped. An accepted request or a lost response alone does not confirm shutdown.

Stop preserves saved browser storage. It does not delete the profile or change the agent's browser grants. Keep the task record until you have confirmed the final state.

If the operation fails

A changed browser state, another conversation, private control, or a deliberate pause prevents cleanup. Inspect the current state after a conflict. Do not repeat Stop without checking which task owns the current browser.

If administrator access or the agent's run permission changed, restore the required access through the app. If exclusive browser access is missing, review its grants there. Preserve the saved browser while resolving the conflict.