Grasp

When to use

• The task needs a real browser session, not a one-shot headless script
• The work depends on persistent login state, a visible browser window, or human handoff/recovery
• The agent needs one interface for page entry, extraction, share/export, forms, workspace actions, screenshots, and low-level browser control
• The agent must know which runtime instance it is acting on, or it needs to switch between user-visible tabs safely

Safe defaults

• Treat Grasp as the browser runtime surface. Use MCP tools for page actions instead of recreating interactions in shell scripts.
• Start with get_status. Before page-changing actions, prefer confirm_runtime_instance(display="windowed") or confirm the mode you actually expect.
• If a tool returns INSTANCE_CONFIRMATION_REQUIRED, confirm the instance and retry the same action.
• For first arrival to a URL, prefer entry(url, intent). Use navigate(url) only when you intentionally want to move the current page directly.
• Prefer the high-level surfaces first: runtime loop, form tools, and workspace tools. Drop to hint map, tabs, cookies, dialogs, or evaluate only when the higher-level path is not enough.
• Prefer list_visible_tabs / select_visible_tab before raw tab primitives such as get_tabs or switch_tab.
• Refresh get_hint_map after navigation, a page-changing click, a visible DOM change, or scroll-loaded content. Old hint IDs are not safe to reuse after the page changes.
• Use the handoff flow when the task is blocked by login, CAPTCHA, checkpoints, or other human-only steps.
• If local CDP is unreachable, Grasp may auto-launch local Chrome or Edge now. If that still does not recover the runtime, ask the user to run npx -y @yuzc-001/grasp, grasp connect, or start-chrome.bat on Windows.

Recommended workflow

1. get_status
2. confirm_runtime_instance when the task needs a confirmed live instance
3. entry(url, intent)
4. inspect
5. Follow the task surface that matches the job:
   • extract / extract_structured / extract_batch / share_page / continue
   • form_inspect
   • workspace_inspect
6. Use explain_route when the route choice needs explanation
7. If blocked, use handoff and then resume with continue

Task surfaces

Public web and extraction

Use entry(..., intent="extract" | "read"), then stay on inspect, extract, extract_structured, extract_batch, share_page, explain_share_card, and continue as long as the runtime surface is enough.

Forms

Use form_inspect -> fill_form / set_option / set_date -> verify_form -> safe_submit.

Authenticated workspaces

Use workspace_inspect -> select_live_item -> draft_action -> execute_action -> verify_outcome.

Lower-level control

Only when the higher-level surface is not enough, use get_hint_map, click, type, hover, scroll, scroll_into_view, screenshot, wait_for, go_back, go_forward, reload, raw tab tools, cookies, dialogs, file upload, drag-and-drop, keyboard controls, and evaluate.

Additional resources

• Detailed tool selection, examples, troubleshooting, and compatibility notes: references/tools.md
• Product framing for the runtime model: Browser Runtime for Agents