Keep Browser-Agent Downloads After the Session Ends

The agent clicks Export, sees a download begin, and tells the user the report is ready. The browser session closes. The next person opens the supplied path and finds nothing.

This failure has two separate causes to investigate: the agent may have reported completion too early, or it may have handed over a browser-managed temporary file instead of a durable copy. Even after those problems are fixed, the saved document can still cover the wrong account or reporting period.

For browser-agent builders and operations teams, the deliverable should be a verified artifact, not evidence that a button was clicked.

Methodology and the four states of an export

We reviewed Playwright's download guide and API reference, plus MDN's documentation of download response headers. The monthly-export scenario here is an original acceptance design, not a live test of an accounting portal.

Use four separate states: requested, completed, persisted, and accepted. Requested means the export interaction happened. Completed describes transport. Persisted means a copy lives in the agreed storage location. Accepted means its contents satisfy the requested task.

Playwright documents that downloads associated with a browser context are deleted when that context closes. Its guide also establishes the listener before the triggering click and awaits saving the result. These details matter if your agent harness owns Playwright directly. Playwright downloads guide.

Specify the artifact before clicking

For a fictional monthly supplier export, write down the workspace, calendar period, expected format, and final destination before opening the export menu. Include the timezone used to interpret the period. “Last month” becomes ambiguous when a task resumes after a month boundary.

Choose a destination that the intended recipient can access after the agent session ends. A path inside an ephemeral runner is not a durable handoff simply because it is outside the browser's temporary folder. Hosted systems may instead need an approved artifact store with a stated retention period.

Also decide what would make the file acceptable. For a CSV, that might include expected header names and an account identifier. For a PDF, it might be a visible report heading and date range. Do not invent a row count unless there is a reliable expected count to compare.

These requirements make the browser step a means to an outcome rather than the outcome itself.

Await the save, then close the session

The Playwright API distinguishes the start event from completion. Its saveAs method waits for an in-progress download before copying it; failure reports an error or null after completion. The path method is not a universal remote-artifact solution: it throws when connected remotely. Playwright Download API.

In a directly controlled integration, the sequence should therefore connect the export interaction to its download, wait for the durable save, and only then allow session cleanup. Avoid detached event handlers whose work is still running when the main task exits.

If your agent uses a hosted browser tool, use that tool's documented download or artifact handoff instead. Do not assume it exposes Playwright objects, local paths, or identical retention behavior. Ask for the tool's artifact identifier and verify how to retrieve it.

A timeout should produce a bounded failure report. Repeatedly clicking Export without knowing whether earlier requests are still running can leave several indistinguishable results.

Do not let the filename decide what you received

The Content-Disposition response header can indicate an attachment and suggest its name. Browsers may transform that name to satisfy filesystem rules. A suggested name is not a certificate of the file's contents. MDN Content-Disposition.

For our proposed workflow, allocate a job-specific output location and a controlled filename. Keep the original suggested name as metadata, not as permission to write an arbitrary path. If another export has the same name, preserve it separately until the duplication is understood.

Next inspect the artifact without executing embedded code. Confirm it is the expected format rather than an error page or unrelated document. Then check its period and workspace against the original request. A nonempty PDF can be a perfectly valid report for the wrong month.

For structured files, transport success is only the entrance to data validation. The CSV reconciliation guide covers row accounting and schema checks before analysis.

Hand over a receipt, not just a cheerful message

A useful receipt for the fictional export contains the task's reporting period, the saved artifact reference, its size, completion time, and the content checks actually performed. Include a source page reference only if it can be shared without exposing session credentials or signed access tokens.

A content hash can help recognize identical bytes across copies. It does not establish that those bytes came from the intended account or that the report is accurate. Keep identity evidence and business validation separate.

Give the recipient an honest status. “Saved; period not verified” is materially different from “Ready for analysis.” If only a temporary download exists, say that persistence has not finished instead of presenting its path as the final result.

The browser-versus-crawler guide helps decide whether interaction is necessary in the first place. This receipt is the next boundary once a browser is involved.

Limitations and a practical acceptance exercise

In a test environment, close the browser after a successful save and confirm that the recipient can still retrieve the artifact. Repeat with a canceled download, two files sharing a suggested name, and a file containing the wrong reporting period. These are proposed exercises; we have not executed them against a service.

Browser exports remain dependent on session expiry, access policy, service-side generation time, and the tool's storage contract. Some files require manual review, and a parsed header cannot establish the correctness of every value.

Do not expand permissions or circumvent a portal's controls to rescue a failed export. Preserve the observed status and explain the missing step. The definition of done is that the right recipient can obtain the right artifact after the agent leaves—not that the download animation appeared.