Browser sessions
A session is a browser your agent starts for a task. Keep related pages in tabs of the same session, and stop the session when the task is finished.
Mobile layouts
Websites open in their mobile layouts in a session. The agent taps, swipes, and types on them as a person would.
If a website only works in its desktop version, give the agent the Change browser settings permission. It can then turn on Desktop site for a tab, which asks websites for their desktop version.
Start and reuse a session
Your agent starts a browser with browser_session and action: "start". The reply gives a session_id and, once ready, the first tab's page_id. Browser tools use these IDs to act on the right session and tab.
If startup returns state: "starting", repeat start with the same label after a few seconds. Rukou returns the existing session. Keep that label stable during retries so the agent does not create extra browsers.
Use browser_tabs to open, list, and close tabs. Tabs keep loading while the agent works in another tab, but calls on one session run one at a time. Independent agents working in parallel should use their own sessions, within the organization's concurrency limit.
Watch or take control
Open Sessions, select the session, and choose the tab you need. Select Take control to interact with it yourself. When finished, select Release. The agent should read the page again before continuing because your actions may have changed it.
An agent can use browser_request_help for a code, a choice, or another step that needs you. The session page highlights the request. Open it, take control, complete the step, and release control. Calls on the affected tab wait while it needs help; the tool's reply explains the scope of the hold for that session.
An organization owner or admin can use Release teammate when another person holds control and cannot release it themselves.
Time limits
rukou_status shows how long a session runs before it needs an extension and how long it may sit idle. A session's reply gives its deadline, the time remaining, and the latest time that extensions can reach.
An agent can extend a running session with browser_session, action: "extend", before time runs out. An extension cannot pass that latest time, and it does not remove the idle timeout. Sessions can end because of time, inactivity, or access changes as well as an explicit stop.
Reuse a persona
A session's browser has a persona: the visitor that websites see, with its own fingerprint. An agent normally starts with its own persona. To choose one, give start a seed, such as research-1. The same seed within a workspace selects the same persona and fingerprint, including when another agent in that workspace uses it.
A seed is a non-secret label. It does not preserve tabs or cookies. To reuse an approved login's signed-in state, use saved sign-ins.
Stop and replay
Ask the agent to call browser_session with action: "stop", or choose Stop session from the session menu. The browser, its tabs, and its cookies are discarded. Stopping does not save sign-ins automatically, and an ended browser cannot be resumed.
When a recording is available, the session offers Replay or Play recording. Use the timeline to inspect what happened. The page shows how long the recording is kept. An expired, deleted, or unavailable recording cannot be replayed. Replay is a view of the past session; start a new browser to continue the task.
If you delete a recording, its trace is deleted too.