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

Why this matters

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, …)

Quick start

Level 0 — drop it in

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

Level 1 — add metadata (optional)

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

Level 2 — register native tools (optional)

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

Safety model (built in)

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
};

Hiding or customizing the inspector

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>
   

Development

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

Test layers

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

Project structure

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

Testing in a WebMCP browser

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

Website

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

Deploying the demo

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.

License

MIT © 2026 Will Huang