---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/observability/hand-control-to-a-human
markdown_url: https://steel.dev/docs/observability/hand-control-to-a-human.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Hand control to a human
description: Pause your agent and let a person finish a step, such as a two-factor sign-in, in the session's live view. Then continue.
summary: Pause your agent and let a person finish a step, such as a two-factor sign-in, in the session's live view.
type: how-to
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/observability/live-view.md
  - https://steel.dev/docs/observability/embed-a-live-browser.md
  - https://steel.dev/docs/observability/recordings.md
  - https://steel.dev/docs/observability/logs.md
  - https://steel.dev/docs/observability/agent-traces.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# 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:

**TypeScript**

```sh
npm install steel-sdk playwright
```

**Python**

```sh
python3 -m venv .venv
source .venv/bin/activate
pip 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](https://steel.dev/docs/platform/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](https://steel.dev/docs/observability/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](https://steel.dev/docs/observability/embed-a-live-browser) 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.

**TypeScript**

```ts file=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);
}
```

**Python**

```python file=handoff.py
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:

**TypeScript**

```sh
npx tsx handoff.mts
```

**Python**

```sh
python handoff.py
```

```text nocopy
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.

> **Warning**
>
> The `debugUrl` holds a token. Anyone who has the URL can watch the session, and can control it while the view is interactive. Send it only to the person who must act, and only after your app has checked who that person is.

## 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](https://steel.dev/docs/logins/stay-signed-in) 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](https://steel.dev/docs/observability/embed-a-live-browser#3-choose-interactive-or-view-only) 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](https://steel.dev/docs/logins/credentials): Let Steel fill one-time passwords, so the person is needed less often.
