# MagicBrowse

Canonical URL: https://magiccard.ai/docs/components/magicbrowse
Markdown URL: https://magiccard.ai/docs/components/magicbrowse.md
Summary: MagicBrowse helps agents use legacy commerce websites by combining browser automation, checkout-specific behavior, and a growing site memory.
Description: MagicBrowse is the commerce-specialized browser agent layer for checkouts, forms, and payment flows.

## Canonical Answer

MagicBrowse helps agents use legacy commerce websites by combining browser automation, checkout-specific behavior, and a growing site memory. MagicBrowse is the commerce-specialized browser agent layer for checkouts, forms, and payment flows. LLM planner with vision plus a high-speed DOM navigator for checkout execution.

![MagicBrowse checkout trace](https://magiccard.ai/docs-assets/images/components-magicbrowse-handoff.svg)

## Key Points

- Browser-use agent purpose-built for real e-commerce navigation and checkout flows.
- LLM planner with vision plus a high-speed DOM navigator for checkout execution.
- Stops at login, payment, identity, CAPTCHA, and every other protected step.
- Learns from successful runs through site memory, runtime hints, and checkout traces.

## Commerce-First Browser Use

General browser agents are broad and brittle around checkout. MagicBrowse narrows the problem: search result pages, product pages, carts, guest checkout, provider handoff, form observation, and sensitive-step detection. The active package is `@nuanu-ai/magicbrowse`, and the CLI is `@nuanu-ai/magicbrowse-cli`.

## Planner And Navigator

MagicBrowse separates planning from low-level browser movement. The planner reasons over the task, visual state, and commerce-specific policies. The navigator performs DOM-oriented actions and reports structured observations. This lets MagicPay keep the agent fast on ordinary browsing while enforcing hard stops before sensitive entry.

```ts
import { act, launch } from '@nuanu-ai/magicbrowse';

const session = await launch({
  headless: false,
  url: 'https://www.booking.com',
});

const result = await act({
  sessionId: session.id,
  goal: 'Find a Hilton stay from May 10 to May 12 and stop before sensitive guest or payment data.',
});

if (result.status === 'needs_handoff') {
  await createMagicPayRequest(result.handoff);
}
```

## Sensitive-step Handoff

MagicBrowse should not type passwords, card values, passport details, OTPs, or final payment confirmations directly from model context. When it observes a protected form, MagicPay creates a request, resolves the approved artifact, writes the value through the trusted fill path, and returns only the continuation state the browser agent needs.

## Site Memory

MagicBrowse teaches itself after each successful checkout. Successful commerce traces can be converted into site-specific hints: useful URLs, checkout milestones, button labels, form shapes, provider handoff patterns, and recovery notes. These hints speed up future runs and reduce repeated exploration, but they never override live page state, policy, or user approval. Over time, this becomes an agentic knowledge base of internet commerce: a practical memory of how real merchants, booking sites, marketplaces, and checkout flows work for AI agents.

## Related

- E2E Purchase Flow: https://magiccard.ai/docs/guides/e2e-purchase
- Agent Skills: https://magiccard.ai/docs/integrations/agent-skills
- MagicPay Memory fill: https://magiccard.ai/docs/components/memory-fill