A human hand-off is the moment a browser agent stops, passes the live browser window to a person for a step it should not take itself, and carries on once the person is done. Sign-ins, two-factor codes, CAPTCHAs and anything irreversible are the usual steps. The agent keeps its place, the person works in the same page and the same session, and nothing secret passes through the agent.
This post covers why some steps belong to a person, how a hand-off works in Browz, when a stored sign-in is the better choice, and how to write agent instructions that use hand-off well.
Why some steps belong to a person
An agent that can click and type could, in principle, attempt any step on a page. Some steps are better left to you:
- CAPTCHAs exist to confirm that a person is present. Having a person complete them is what the site asks for.
- Two-factor codes often arrive on your phone, by text or in an authenticator app the agent cannot and should not reach.
- Passkeys and security keys need a fingerprint, a face or a touch on the device.
- Consent and payment screens commit you to something. A person should read them.
- Anything irreversible, such as deleting data or sending a message on your behalf, deserves a person's final look.
There is a safety reason too. If the agent never types your password or code, a hostile page cannot trick it into repeating them elsewhere. Prompt injection and browser agents explains that risk.
How a hand-off works in Browz
In Browz, the agent calls the MCP tool browz_request_human. Here is the whole sequence, as in the human hand-off recipe:
- The agent notices. It reads the page with
browz_snapshot. On a sign-in page, the snapshot flags it withNEEDS A PERSON. - It asks. It calls
browz_request_humanwith the profile id and a short reason, such as "Sign in to example.com". - Browz pauses and alerts you. Automation on that profile pauses, its window comes to the front, a notification appears, and a banner in the window offers I'm done and Cancel.
- You finish the step in that window: type the password, enter the code, complete the check.
- The call returns. It ends when you click I'm done, when the address reaches a page you agreed in advance, when you cancel, or when the time runs out.
- The agent carries on in the same signed-in session. It takes a new snapshot first, since the page has changed.
A call looks like this:
{
"id": "<profile id>",
"reason": "Sign in to shop.example.com, then click I'm done",
"kind": "login",
"timeoutSec": 300,
"doneWhenUrlContains": "/dashboard"
}kind is login, two_factor, captcha or other, and is worked out from the page when left out. timeoutSec runs from 10 seconds to 30 minutes, 5 minutes by default. doneWhenUrlContains lets the hand-off end by itself as soon as a tab reaches the page that follows a successful sign-in, so you do not need to click anything. targetId picks a tab when the profile has several.
If you click Cancel, the call ends as cancelled; if nobody responds in time, it ends as timed out. Either way the agent gets a clear result and can ask again, try another route, or end the session.
Profiles with a window
A hand-off needs a window the person can see, so run tasks that may need you with a headed profile, which is how Browz profiles open by default. For jobs that run unattended on a server, sign the identity in beforehand or use a stored sign-in.
Through the hosted server
Hand-off also works for cloud agents through the hosted MCP server at mcp.gobrowz.com, a free public beta. There, one call waits about 70 seconds and returns state: "waiting" with a handoffId. The agent calls browz_request_human again with that handoffId to keep waiting, or with cancel: true to take control back. Connecting a cloud agent to your own computer covers the hosted setup.
Hand-off or stored sign-in
Not every login needs you at the keyboard. For a routine sign-in to an account you are entitled to use, store the password and, optionally, the authenticator seed in Browz once. The agent then calls browz_credential_fill for each field, Browz types the value itself, only on that sign-in's sites over https, and the agent gets back only "filled". AI agent login without sharing the password explains how it stays hidden.
| Situation | Better choice |
|---|---|
| A password and authenticator code you can store | Stored sign-in |
| A code sent by text or email | Hand-off |
| A passkey or security key | Hand-off |
| A CAPTCHA or "verify you are human" check | Hand-off |
| A code box that is a plain text field | Hand-off |
| A consent, payment or deletion screen | Hand-off |
| A daily scheduled job with no one around | Stored sign-in, or a profile signed in beforehand |
The two work well together: the agent fills the stored password and code, and calls for you only when the site asks for something extra.
Writing agent instructions for hand-off
A model does what its instructions make easy. A few lines in the system prompt, or in a project file such as CLAUDE.md for Claude Code, make hand-off the natural path:
If a snapshot says NEEDS A PERSON (a sign-in, a verification code or a CAPTCHA),
call browz_request_human with a short reason and wait. Never type a password or
code you were given in chat, and never try to solve a CAPTCHA. After the call
returns, take a new browz_snapshot before you continue.Some habits that help:
- Write the reason for a person. "Sign in to shop.example.com as the support account" beats "login required". The reason is shown to you, up to 300 characters.
- Agree the finish line. Pass
doneWhenUrlContainswith the path of the page after sign-in, so the hand-off ends by itself. - Choose a timeout that fits. Five minutes suits a sign-in; a code that arrives by email may need longer.
- Say what to do on cancel. Tell the agent to stop and report, rather than try again in a loop.
- Hand off before anything irreversible. Ask the agent to call for you before it submits a payment, deletes something or sends a message.
- Never collect secrets in chat. The agent should not ask you to paste a password or code into the conversation. You type it into the page, or Browz fills it from a stored sign-in.
Hand-off in the Browz safety model
You decide exactly what each agent may do: its own key, its own profiles, only the sites you allow, sign-ins it can use on your computer but never read, and a person for the login.
Hand-off is the last part of that line. A person completes CAPTCHAs and 2FA, the agent's key reaches only the sites you allow, and every call an agent key makes, a hand-off included, is in the local log on your computer for 90 days. When a verification check still loops after you complete it, the verification troubleshooting article lists the settings to check. More on agents in Browz is on Browz for AI agents.
Frequently asked questions
What is human in the loop for browser agents?
It means a person takes part at chosen moments of an agent's task. For a browser agent, the agent pauses at a step such as a sign-in or a CAPTCHA, a person completes it in the same browser, and the agent carries on from there.
Can an AI agent complete a CAPTCHA in Browz?
The agent hands it to you. It calls browz_request_human, the profile's window comes to the front, you complete the check, and the agent carries on in the same session. The tool itself tells the agent never to use services that complete CAPTCHAs for it.
Does the agent see what I type during a hand-off?
No. While you work, automation on that profile is paused, and the call returns only an outcome to the agent, such as that you finished or that the page reached the agreed address. Afterwards the agent reads the page that follows with a new snapshot.
What happens if I am away when the agent asks for help?
The call waits until its timeout, five minutes by default and up to thirty, then ends as timed out. The agent can ask again later or end the session, and the profile keeps its state.
Do I need hand-off if I store my sign-ins in Browz?
Often not for the password and authenticator code, which Browz can fill without the agent seeing them. You still need hand-off for codes sent by text or email, passkeys, CAPTCHAs and any step you want to approve yourself.