Skip to content

Hand control to a human

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

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 playwright

Plan 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.

handoff.mts
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);
}

Run the program, and open the URL that it prints:

npx tsx handoff.mts
Sign in here: https://api.steel.dev/v1/sessions/3f2b8c1e-7a4d-4e9b-b6c2-5d8e1f0a9c37/player/…
Signed in. The agent continues on https://steel.dev/practice/secure

The 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.