> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser Use

> Let your PAL drive a live browser and narrate a guided flow while participants watch over screen share.

The `browser_use` skill lets the PAL drive a live web browser and walk participants through a guided, pre-authored flow. You define one or more named flows as an ordered list of steps; during the call the PAL runs a flow, narrates each page as it moves, and the browser is streamed to participants on the PAL's screen-share track.

<Note>
  **Guided mode only**

  `browser_use` runs owner-authored, named flows that you script ahead of time. The PAL follows the steps you defined - it does not free-browse or take navigation instructions from the participant. If you don't attach the skill, the PAL has no browser.
</Note>

## How it works

When you attach the skill, the PAL gains a small set of flow-control tools. The PAL starts a flow, and for each step a browser worker carries out the instruction on a real cloud browser while the PAL narrates what is on screen. The live browser is published as a screen-share track on the PAL's participant, so participants see the pages as the PAL talks through them.

Because each flow is named and scripted, you get repeatable, on-message walkthroughs: the same product tour, onboarding flow, or feature walkthrough every time, narrated live.

## Adding the browser use skill to your PAL

Attach the skill with a `PUT` to the PAL's skill collection, passing your flows in `config`:

```bash theme={null}
curl --request PUT \
  --url https://tavusapi.com/v2/personas/{persona_id}/skills/browser_use \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "config": {
      "guided_flows": [
        {
          "name": "Onboarding",
          "description": "Sign in and set up a first project",
          "start_url": "https://app.example.com",
          "steps": [
            {
              "task": "Click the Log in button and sign in",
              "prompt": "Let'\''s start by signing in.",
              "url": "https://app.example.com/login"
            },
            {
              "task": "Open the Projects tab and create a new project",
              "prompt": "Now we'\''ll create your first project."
            }
          ]
        }
      ]
    }
  }'
```

The skill is active on the PAL's next conversation.

## Configuration

| Field               | Type                  | Required    | Description                                                                                                                                                                                |
| ------------------- | --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `guided_flows`      | array of flow objects | Yes         | The named flows the PAL can run. At least one flow is required (up to 20). Each flow is a `{name, description, steps}` object (see below).                                                 |
| `start_url`         | string (URL)          | No          | Default landing page, used only for flows that don't set their own `start_url`. Each flow normally carries its own (see the flow object below), so this is a fallback.                     |
| `slide_document_id` | string                | Conditional | The Knowledge Base document (a slide deck) that `slide` steps show pages from. Required only if any step uses `slide` (see [Showing slides during a flow](#showing-slides-during-a-flow)). |

### Flow object

| Field         | Type                  | Required | Description                                                                                                                                                         |
| ------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string                | Yes      | A short name for the flow. The PAL uses this to pick which flow to run, so make it descriptive (e.g. `"Onboarding"`, `"Reporting tour"`).                           |
| `description` | string                | No       | A one-line summary of what the flow covers. Helps the PAL choose the right flow.                                                                                    |
| `start_url`   | string (URL)          | No       | The page the browser lands on before this flow's first step, so each flow can begin on its own relevant page. Falls back to the top-level `start_url` when omitted. |
| `steps`       | array of step objects | Yes      | The ordered steps of the flow. At least one step is required (up to 50 per flow).                                                                                   |

### Step object

Each step is a browser action, a spoken aside, or a slide.

| Field             | Type         | Required    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------- | ------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `task`            | string       | Conditional | The instruction the browser worker carries out for this step, in plain language (e.g. `"Open the Projects tab and create a new project"`). Required unless the step is a **speak-only** step (`prompt` only) or a **slide** step (`slide`).                                                                                                                                                                                                   |
| `prompt`          | string       | Conditional | What the PAL narrates while this step runs. **Required on `task` (browser) steps and speak-only steps** — a live page has no pre-authored text to narrate from. **Optional on `slide` steps**: if you omit it, the PAL narrates the slide from its page summary. A step with only a `prompt` (no `task`, no `slide`) is a **speak-only** step: the PAL says it and performs no browser action — handy as an intro before the first real step. |
| `url`             | string (URL) | No          | A checkpoint URL for this step. When set, the flow can jump straight to this step by navigating directly to the page instead of replaying earlier steps. Not allowed on a slide step.                                                                                                                                                                                                                                                         |
| `slide`           | integer      | No          | The 1-based page of `slide_document_id` to show on the shared screen for this step, instead of moving the browser. A slide step is narrated by its `prompt` — or, if omitted, by the slide's own page summary — and performs no browser action, so it cannot also carry a `task` or a `url`. See [Showing slides during a flow](#showing-slides-during-a-flow).                                                                               |
| `wait_for_answer` | boolean      | No          | After this step is narrated, the flow **holds at the step boundary and waits for the participant to reply** instead of auto-advancing. Valid on `slide` and `task` (browser) steps — rejected on speak-only steps. Put it on steps whose narration ends with a question. See [Waiting for the participant's answer](#waiting-for-the-participants-answer).                                                                                    |

## Showing slides during a flow

A flow can interleave **slides** with live browser steps - useful for framing a demo ("here's the architecture") before dropping into the product, or recapping at the end. A slide step swaps the shared screen to a page of a slide deck and the PAL narrates it, exactly like a browser step, as part of the same walkthrough. There is no split screen: whichever acted most recently owns the surface (a browser step reclaims it from a slide, and vice versa).

Slides come from a **Knowledge Base document** - the same kind of document the [Presentation](/sections/conversational-video-interface/skills/presentation) skill uses. To add slides to a flow:

1. **Upload the deck** to your Knowledge Base and note its document ID. Documents are created via the [Create Document](/api-reference/documents/create-document) API and are prepared for presentation automatically. The document must be owned by you and presentable (a pdf slide deck works well).
2. **Set `slide_document_id`** in the skill config to that document ID. All slide steps in the config draw their pages from this one deck.
3. **Add `slide` steps** where you want a page shown, using the 1-based page number of the deck. A `prompt` is optional on a slide step — give one to script the narration, or omit it to let the PAL narrate the slide from its page summary.

```bash theme={null}
curl --request PUT \
  --url https://tavusapi.com/v2/personas/{persona_id}/skills/browser_use \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "config": {
      "slide_document_id": "d1234567890",
      "guided_flows": [
        {
          "name": "Product overview",
          "description": "Frame the product with a slide, then show it live",
          "start_url": "https://app.example.com",
          "steps": [
            {
              "slide": 1,
              "prompt": "Here'\''s the big picture of how the platform fits together."
            },
            {
              "task": "Open the Projects tab and create a new project",
              "prompt": "Now let'\''s see it in action - I'\''ll create a project."
            },
            {
              "slide": 4,
              "prompt": "Recap the three things we set up, then ask if anything needs a second look.",
              "wait_for_answer": true
            }
          ]
        }
      ]
    }
  }'
```

<Note>
  `slide_document_id` is **required** whenever any step uses `slide`; the config is rejected otherwise. If the referenced deck isn't display-ready when the conversation starts, slide steps gracefully degrade to speak-only (the PAL narrates the `prompt` without swapping the screen).
</Note>

## Waiting for the participant's answer

By default a flow **auto-advances**: as soon as a step's narration finishes, the next step begins. That's right for a continuous walkthrough, but wrong for a step that ends with a question — the screen would move on before the participant can answer.

Set `"wait_for_answer": true` on a `slide` or `task` step to make the flow **pause at that step's boundary** once its narration is done. While it waits:

* The current slide or page **stays on the shared screen**.
* The PAL answers follow-ups, repeats, or clarifications from it ("wait, say that again" gets a re-explanation, not the next slide).
* The flow continues only when the participant is ready to move on — the PAL resumes it explicitly; talking alone never advances it.
* On the **final step**, the hold works the same way; once the participant is ready, the PAL wraps up and the shared screen returns to the PAL's video automatically.

```json theme={null}
{
  "slide": 2,
  "prompt": "Walk through the agenda, then ask whether it covers what they came for.",
  "wait_for_answer": true
}
```

Interjections behave sensibly on every step, flagged or not: if the participant talks over a step's narration, the flow pauses, the PAL handles what they said, and resuming **finishes that step's point** before moving on — an interruption never costs a step its content.

## Best practices

**Flag question steps with `wait_for_answer`.** If a step's narration ends with a check-in ("does that match what you're seeing?"), set `wait_for_answer` on it — otherwise the flow advances the moment the question is spoken. Writing "pause for questions" inside the `prompt` does **not** pause the flow; only the flag does.

**Keep steps small and give each one a `prompt`.** Break the flow into small, single-action steps, and write a sentence or two of narration (`prompt`) for each. The PAL narrates a step *after* its action lands, and while it is speaking the browser is already planning the next step - the on-screen move is held until the narration finishes, so the page never moves mid-sentence. The narration therefore doubles as the browser's think-and-load time: a small task plus a sentence of narration lets the browser stay a step ahead, so the flow moves with no dead air. Very short prompts (or one oversized task) can leave a beat where the PAL has stopped talking but the browser is still working - tune it on a real run and lengthen the narration wherever the flow stalls.

## Update the configuration

`PATCH` merges changes into the existing config - fields you omit are preserved:

```bash theme={null}
curl --request PATCH \
  --url https://tavusapi.com/v2/personas/{persona_id}/skills/browser_use \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "config": {
      "start_url": "https://app.example.com/home"
    }
  }'
```

Use `PUT` on the same path to overwrite the entire configuration. To turn the skill off, detach it:

```bash theme={null}
curl --request DELETE \
  --url https://tavusapi.com/v2/personas/{persona_id}/skills/browser_use \
  --header 'x-api-key: <api-key>'
```

See [Skills Overview](/sections/conversational-video-interface/skills/overview) for how attachments work and the full [API reference](/api-reference/persona-skills/attach-skill-to-persona).

## Displaying the browser video track in your app

The live browser is published the same way the [Presentation](/sections/conversational-video-interface/skills/presentation) skill publishes slides: as a `screenVideo` track on the **same participant as the PAL's video**, not as a separate participant. Your frontend shows it by watching that participant's `screenVideo` track and rendering it when it becomes playable.

<Note>
  If you embed with the [`@tavus/cvi-ui`](/sections/conversational-video-interface/component-library/blocks) [`Conversation`](/sections/conversational-video-interface/component-library/blocks#conversation-block) block, replica video and screen-share switching is built in - you do not need to wire up the track yourself.
</Note>

If you build a custom Daily layout, follow the same steps as the presentation skill: find the PAL's participant, subscribe to its `tracks.screenVideo.state`, and render the `screenVideo` track when the PAL is sharing (falling back to the replica `video` track otherwise). See [Displaying the presentation video track](/sections/conversational-video-interface/skills/presentation#displaying-the-presentation-video-track-in-your-app) for the full example - the wiring is identical; only the source of the shared surface differs.

<Note>
  The `screenVideo` track is lazy: it does not exist until the PAL starts sharing the browser. Don't block or error on a missing screen track when the call connects - render the replica video and switch to the browser once `screenVideo.state` becomes `playable`.
</Note>

## Capability limitations

`browser_use` includes full presentation support: slide steps can show pages from a Knowledge Base deck as part of a flow (see [Showing slides during a flow](#showing-slides-during-a-flow)). Because of this overlap, `browser_use` and `presentation` cannot be attached to the same PAL at the same time. Attach `browser_use` if you need guided browser flows (with or without slides), or `presentation` if you only need slides.

<Note>
  The PAL publishes a single screen-share track. It shows either the live browser or a slide at any given moment, never both at the same time. There is no split screen.
</Note>