AgentReady.js

Add one JavaScript file. Make your website agent-ready.

AgentReady.js is a progressive-enhancement layer for the existing web. Load it with a single <script> tag and it turns your site's semantic HTML — forms, navigation, buttons, app state — into safe, structured WebMCP tools that any WebMCP-capable agent can call directly: ChatGPT's in-app browser, Chrome 149+, or in-page agents using the standard getTools() / executeTool() shape.

Humans keep using the same interface. Agents get a reliable interface of their own.

<script src="agentready.js" defer></script>

Built for the WebMCP Challenge (Sep 2026).

🌐 繁體中文版:README.zh-tw.md

WebMCP lets a website declare its capabilities to agents instead of leaving them to guess through screenshots and DOM spelunking. But rewriting millions of existing websites isn't realistic — so AgentReady.js derives the tool layer automatically:

The same page then works with any WebMCP agent — ChatGPT, an in-page agent, or a future client — because everything is exposed through the standard document.modelContext API (with a navigator.modelContext fallback for Firefox, and an identical in-page fallback for browsers without it — including ChatGPT desktop's register-only client).

            Human
              │
        ┌─────┴─────┐
        │  Website  │
        └─────┬─────┘
        AgentReady.js  (semantic discovery + policy + inspector)
              │
      document.modelContext  ← native WebMCP when available
              │
   ChatGPT browser · Chrome 149+ · in-page agents (AskPage, …)

<script src="https://cdn.jsdelivr.net/npm/@willh/agentready@latest/dist/agentready.js" defer></script>

Or install via npm: npm install @willh/agentready → serve node_modules/@willh/agentready/dist/agentready.js.

That's it. AgentReady discovers the page and registers:

Synthesized tools are derived from aria-label / headings / action URLs. A search form becomes search_products({ q, category, max_price }) — not twenty set_input_17 primitives.

<form
  method="get"
  aria-label="Product search"
  data-agent-name="search_products"
  data-agent-description="Search products in the catalog"
  data-agent-submit="auto">
  <input name="q" type="search" placeholder="Search…" />
  <select name="category">…</select>
  <button>Search</button>
</form>

• data-agent-name / data-agent-tool — tool name (else derived from labels/heading/action)
• data-agent-description — tool description
• data-agent-submit="auto | confirm | never" — override the submit policy
• data-agent-hide — exclude a field from agents entirely
• data-agent-priority — synthesize this form first (max 8 per page)

<script>
  window.AgentReadyConfig = { siteName: 'My Store' };
</script>
<script src="agentready.js" defer></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    window.AgentReady.register({
      name: 'add_to_cart',
      description: 'Add a product to the shopping cart',
      inputSchema: {
        type: 'object',
        properties: { productId: { type: 'string' }, quantity: { type: 'number' } },
        required: ['productId'],
      },
      execute: ({ productId, quantity }) => cart.add(productId, quantity ?? 1),
    });
  });
</script>

window.AgentReady also exposes getTools(), executeTool(name, argsJson) and inspect() — the same shapes as the WebMCP standard API — so in-page agents work on every browser, even without the native API.

AgentReady treats everything on the page — and everything an agent might do — as untrusted by default. All tools carry untrustedContentHint; read tools carry readOnlyHint. Tool output is clamped to ~1,500 characters per call.

The inspector (bottom-right badge) shows the live tool list, every agent action with its arguments, highlights targets as the agent touches them, and pops an Approve / Decline dialog for consequential actions. Sensitive fields are excluded from schemas and discovery, so agents never see their existence or values.

Configuration:

window.AgentReadyConfig = {
  inspector: true,          // on-page badge + activity + confirm dialogs (false: confirm-gated actions are auto-declined — fail-closed)
  siteName: 'My Store',     // badge label
  maxResults: 8,            // find_on_page result cap
};

The inspector badge is enabled by default (inspector: true). Depending on your needs, you can hide or customize it:

1. Completely disable the inspector UI (Configuration):

   <script>
     window.AgentReadyConfig = {
       inspector: false, // Disables badge, activity feed, and approval dialogs
     };
   </script>
   <script src="agentready.js" defer></script>

   Note: AgentReady uses a fail-closed safety model. If inspector is set to false, any consequential actions requiring human confirmation (e.g., checkout, form submission) are automatically declined because there is no dialog UI for human approval.

2. Hide the entire UI with CSS: The inspector host element has a data-agentready-ui attribute. You can hide it via global CSS:

   div[data-agentready-ui] {
     display: none !important;
   }

   (Note: This keeps the inspector logic running, but approval popups will also be visually hidden).

3. Hide ONLY the badge (keeping human confirmation dialogs active): Because the inspector UI uses an open Shadow DOM (mode: 'open'), you can hide just the floating .badge while keeping the Approve / Decline modal functional when an agent requests a sensitive action:

   <script>
     window.addEventListener('DOMContentLoaded', () => {
       const host = document.querySelector('div[data-agentready-ui]');
       if (host?.shadowRoot) {
         const style = document.createElement('style');
         style.textContent = '.badge { display: none !important; }';
         host.shadowRoot.appendChild(style);
       }
     });
   </script>

Toolchain: Bun for installs/bundling/serving, TypeScript 7 (strict) for all source.

bun install        # or: make install
make ci            # typecheck → lint → build → unit tests → size → E2E (real Chrome)
make demo          # serve at http://localhost:8788

E2E uses your installed Chrome (channel: 'chrome') and falls back to Playwright's Chromium.

src/
  index.ts            boot, MutationObserver, public API
  runtime.ts          document.modelContext adapter + in-page shim (getTools/executeTool)
  semantic.ts         DOM discovery, stable refs (WeakRef), natural-language matching
  policy.ts           exposure levels, output budgets, sensitive-field redaction
  inspector.ts        shadow-DOM activity UI + human approval dialog
  env.ts              shared types: AgentEnv, AgentReadyConfig, FormInfo, Activity
  tools/              page.ts · interact.ts · forms.ts · controls.ts
demo/store/           Legacy Store demo (self-contained, deployable)
demo/test-page/       verification harness
tests/                bun:test unit + Playwright E2E

• ChatGPT desktop app — the in-app browser supports WebMCP by default (register-only client; AgentReady detects it and keeps getTools/executeTool in-page).
• Chrome 149+ — enable chrome://flags/#enable-webmcp-testing, restart, done.
• Firefox — AgentReady also detects navigator.modelContext.
• Without the native API, AgentReady runs its in-page shim: all tools still work through window.AgentReady — useful for local dev (http://localhost) and non-WebMCP browsers.

The landing page lives in site/ (plain HTML/CSS/JS, no build step) and is published to https://agentready.gh.miniasp.com/ by .github/workflows/pages.yml on every push to main that touches site/, demo/ or src/. The workflow assembles site/ + demo/store/ + demo/test-page/ into one GitHub Pages artifact, so the demo is reachable at /demo/store/. Preview locally with make demo → http://localhost:8788/site/ (the demo/store/ link only resolves on the deployed site).

demo/store/ is self-contained (bundle copied to vendor/agentready.js at build time) — drag it into Netlify, vercel deploy, npx wrangler pages deploy, or any static host.

MIT © 2026 Will Huang