Browser Use

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.

Guided mode onlybrowser_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.

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:

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

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

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 skill uses. To add slides to a flow:

Upload the deck to your Knowledge Base and note its document ID. Documents are created via the Create Document API and are prepared for presentation automatically. The document must be owned by you and presentable (a pdf slide deck works well).
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.
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.

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
            }
          ]
        }
      ]
    }
  }'

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

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.

{
  "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:

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:

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

See Skills Overview for how attachments work and the full API reference.

Displaying the browser video track in your app

The live browser is published the same way the 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.

If you embed with the @tavus/cvi-ui Conversation block, replica video and screen-share switching is built in - you do not need to wire up the track yourself.

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 for the full example - the wiring is identical; only the source of the shared surface differs.

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.

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

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.

Getting Started

Guides

Build

Deploy

Debug

Resources

How it works

Adding the browser use skill to your PAL

Configuration

Flow object

Step object

Showing slides during a flow

Waiting for the participant’s answer

Best practices

Update the configuration

Displaying the browser video track in your app

Capability limitations

​How it works

​Adding the browser use skill to your PAL

​Configuration

​Flow object

​Step object

​Showing slides during a flow

​Waiting for the participant’s answer

​Best practices

​Update the configuration

​Displaying the browser video track in your app

​Capability limitations

How it works

Adding the browser use skill to your PAL

Configuration

Flow object

Step object

Showing slides during a flow

Waiting for the participant’s answer

Best practices

Update the configuration

Displaying the browser video track in your app

Capability limitations