Hand control to a human
A handoff lets a person finish a step that your agent cannot or must not do alone. For example, the person types a code sent to a phone, completes a CAPTCHA that the solver does not clear, or gives an approval. Your agent stops at that step, a person does it in the session's live view, and the agent continues in the same browser with the result.
Before you begin
Put your Steel API key in the STEEL_API_KEY environment variable. Then install the Steel SDK and Playwright:
npm install steel-sdk playwrightpython3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwrightPlan for the time that the person needs. A session ends at its timeout, even while a person works in it, so set one that leaves the person enough time. Limits has the longest timeout for each plan. If you set inactivityTimeout, it counts only the time with no browser command and no input in the live view. A person who reads a page for a long time without clicking can reach that limit.
1. Show the live view to the person
Every session has a debugUrl. It opens the browser's live view, and by default the person can click and type in it. Send the URL to the person, or show it in your app. Embed a live browser in your app shows the frame.
This program opens the sign-in page of Steel's practice site, prints the live view URL, and waits until the person reaches the secure area behind the sign-in. Then it continues with the signed-in page. The sign-in page shows its username and password. For your site, replace the two URLs.
import Steel from "steel-sdk";
import { chromium } from "playwright";
const client = new Steel();
const session = await client.sessions.create({ timeout: 900000 });
try {
const browser = await chromium.connectOverCDP(session.websocketUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://steel.dev/practice/login");
console.log(`Sign in here: ${session.debugUrl}`);
await page.waitForURL("https://steel.dev/practice/secure", { timeout: 600000 });
console.log(`Signed in. The agent continues on ${page.url()}`);
await browser.close();
} finally {
await client.sessions.release(session.id);
}from playwright.sync_api import sync_playwright
from steel import Steel
client = Steel()
session = client.sessions.create(api_timeout=900000)
try:
with sync_playwright() as playwright:
browser = playwright.chromium.connect_over_cdp(session.websocket_url)
context = browser.contexts[0]
page = context.pages[0] if context.pages else context.new_page()
page.goto("https://steel.dev/practice/login")
print(f"Sign in here: {session.debug_url}")
page.wait_for_url("https://steel.dev/practice/secure", timeout=600000)
print(f"Signed in. The agent continues on {page.url}")
browser.close()
finally:
client.sessions.release(session.id)Run the program, and open the URL that it prints:
npx tsx handoff.mtspython handoff.pySign in here: https://api.steel.dev/v1/sessions/3f2b8c1e-7a4d-4e9b-b6c2-5d8e1f0a9c37/player/…
Signed in. The agent continues on https://steel.dev/practice/secureThe session timeout in the program is 15 minutes, and the wait is 10 minutes. The wait ends first, so the program can still release the session if nobody signs in. Choose both values for your task and your plan.
2. Wait for the person to finish
Stop all of your agent's browser actions while the person works. If the agent and the person act at the same time, one of them can leave the page, type over the other's input, or send a form twice.
Wait for one of these:
- A URL, an element or text that appears only after the step is done, as the program does with
waitForURL. This also proves that the step worked. - An event from your app. For example, show a "Done" button next to the live view, and let your agent wait for the click. A click only tells you that the person thinks they are done, so check the page before the agent continues.
Always set a limit on the wait. When the limit passes, or when the person cancels, release the session. Closing the live view does not end the session, and the session costs browser time until its timeout.
3. Continue the agent
The agent continues in the same browser, on the page where the person left it. The steps before the handoff are already done, so do not repeat them. Read the page again before the next action, because the person may have opened another page.
To avoid a handoff on the next run, save the login. Create the session with persistProfile: true, and Steel saves its cookies to a profile when you release the session. Stay signed in across sessions shows the steps.
To let the person watch the rest of the run without control, open a second live view that is view-only. Embed a live browser in your app explains how.
Check that it worked
Before the agent's next action, check the page for the result of the step. In the program, waitForURL (wait_for_url in Python) returns only when the browser reaches https://steel.dev/practice/secure, so the sign-in worked. If the wait ends without that page, the step was not done: hand control back to the person, or release the session.
Next steps
- Credentials: Let Steel fill one-time passwords, so the person is needed less often.