Overview

Web Agent Bridge (WAB) is an open-source middleware script that creates a standardized interface between AI agents and websites. Instead of forcing AI agents to parse and guess DOM structures, WAB provides a clean, documented command layer that agents can read and execute.

When a website includes the WAB script, it exposes a window.AICommands object that describes all available actions, their parameters, and how to execute them. AI agents can discover these commands instantly and interact with the site accurately and securely.

Key Concepts

  • Bridge Script — The client-side JavaScript file added to websites
  • Actions — Defined operations that AI agents can execute (click, fill, scroll, API call)
  • Permissions — Granular controls over what agents are allowed to do
  • License Key — Unique identifier that links a site to its WAB account
  • Auto-Discovery — Automatic detection of interactive elements on the page

Quick Start

Get your website AI-ready in under 5 minutes.

Step 1: Create an Account

Sign up at /register and add your site from the dashboard. You'll receive a license key.

Step 2: Add the Script

Include this in your website's HTML:

HTML
<!-- Web Agent Bridge Configuration -->
<script>
window.AIBridgeConfig = {
  licenseKey: "WAB-XXXXX-XXXXX-XXXXX-XXXXX",
  agentPermissions: {
    readContent: true,
    click: true,
    fillForms: true,
    scroll: true
  }
};
</script>
<script src="https://yourserver.com/script/ai-agent-bridge.js"></script>

Step 3: Verify

Open your browser console and type window.AICommands. You should see the bridge object with discovered actions.

Configuration

The bridge is configured through the window.AIBridgeConfig object, which must be set before loading the script.

JavaScript — Full Configuration
window.AIBridgeConfig = {
  // License key from your dashboard
  licenseKey: "WAB-XXXXX-XXXXX-XXXXX-XXXXX",

  // Subscription tier (verified server-side)
  subscriptionTier: "free",

  // What AI agents are allowed to do
  agentPermissions: {
    readContent: true,       // Read page text
    click: true,              // Click elements
    fillForms: false,         // Fill and submit forms
    scroll: true,             // Scroll the page
    navigate: false,           // Navigate between pages
    apiAccess: false,          // Call internal APIs (Pro+)
    automatedLogin: false,     // Automated login (Starter+)
    extractData: false         // Extract structured data (Pro+)
  },

  // Access restrictions
  restrictions: {
    allowedSelectors: [],                        // Empty = allow all
    blockedSelectors: [".private", "[data-private]"],
    requireLoginForActions: ["apiAccess"],
    rateLimit: { maxCallsPerMinute: 60 }
  },

  // Activity logging
  logging: {
    enabled: false,
    level: "basic"   // "basic" or "detailed"
  }
};

Permissions

Permissions control what AI agents can do on your site. Each permission can be independently toggled.

PermissionDescriptionMin Tier
readContentRead text content from page elementsFree
clickClick buttons, links, and interactive elementsFree
scrollScroll the page or to specific elementsFree
fillFormsFill form fields and submit formsFree
navigateNavigate to different pagesFree
automatedLoginPerform automated login flowsStarter
apiAccessCall internal REST API endpointsPro
extractDataExtract structured data from the pagePro

API Reference

The window.AICommands object provides the following methods:

getActions(category?)

Returns an array of all available actions. Optionally filter by category.

JavaScript
const allActions = window.AICommands.getActions();
const navActions = window.AICommands.getActions("navigation");

// Returns: [{ name, description, trigger, category, requiresAuth, params, fields }]

execute(actionName, params?)

Execute a registered action. Returns a Promise with the result.

JavaScript
const result = await window.AICommands.execute("signup");
// → { success: true, action: "click", selector: "#signup-button" }

const formResult = await window.AICommands.execute("fill_contact_form", {
  name: "Alice",
  email: "alice@example.com"
});
// → { success: true, results: [...] }

readContent(selector)

Read text content from a DOM element.

JavaScript
const content = window.AICommands.readContent("h1.title");
// → { success: true, text: "Welcome!", html: "Welcome!", attributes: {...} }

getPageInfo()

Get metadata about the current page and bridge state.

JavaScript
const info = window.AICommands.getPageInfo();
// → { title, url, domain, lang, bridgeVersion, tier, permissions, actionsCount, rateLimitRemaining }

waitForElement(selector, timeout?)

Wait for a DOM element to appear. Useful for SPAs and dynamically loaded content.

JavaScript
await window.AICommands.waitForElement(".results-loaded", 15000);
// Resolves when the element appears, rejects on timeout

registerAction(actionDef)

Register a custom action that AI agents can discover and execute.

JavaScript
window.AICommands.registerAction({
  name: "addToCart",
  description: "Add the current product to cart",
  trigger: "click",
  selector: "#add-to-cart-btn",
  category: "e-commerce",
  metadata: { requiresProduct: true }
});

authenticate(agentKey, agentMeta?)

Authenticate an AI agent to access restricted actions.

refresh()

Re-scan the page and rebuild the action registry. Call this after significant DOM changes.

onReady(callback)

Register a callback for when the bridge finishes initialization.

Actions

Actions are the core building blocks of WAB. Each action has:

  • name — Unique identifier
  • description — Human/AI readable description
  • trigger — Type of action: click, fill_and_submit, scroll, api
  • selector — CSS selector of the target element
  • fields — Array of form fields (for fill_and_submit actions)
  • category — Grouping label
  • requiresAuth — Whether agent authentication is needed

Action Types

TriggerDescriptionPermission
clickClick on an elementclick
fill_and_submitFill form fields and submitfillForms
scrollScroll to an element or directionscroll
apiCall an internal API endpointapiAccess

Events

Subscribe to bridge events for monitoring and integration:

JavaScript
const bridge = window.AICommands;

bridge.events.on('ready', (data) => {
  console.log('Bridge ready', data.version);
});

bridge.events.on('action:before', ({ action, params }) => {
  console.log(`Executing: ${action}`);
});

bridge.events.on('action:after', ({ action, result }) => {
  console.log(`Result: ${result.success}`);
});

bridge.events.on('error', (err) => {
  console.error('Bridge error', err);
});

Available events: ready, action:before, action:after, action:registered, action:unregistered, agent:authenticate, error, refresh, destroy

Agent Integration Guide

If you're building an AI agent that interacts with websites, here's how to use WAB.

Detecting WAB

JavaScript — Agent Side
// Check if the site supports WAB
if (window.AICommands) {
  const info = window.AICommands.getPageInfo();
  console.log(`WAB v${info.bridgeVersion} detected`);
  console.log(`${info.actionsCount} actions available`);
  console.log(`Tier: ${info.tier}`);
} else {
  console.log('No WAB support — fall back to DOM parsing');
}

Discovering and Executing Actions

JavaScript — Full Agent Workflow
async function agentWorkflow() {
  const bridge = window.AICommands;

  // 1. Authenticate (if needed)
  bridge.authenticate("agent-key-123", {
    name: "MyAssistant",
    version: "2.0"
  });

  // 2. Discover available actions
  const actions = bridge.getActions();

  // 3. Find the action we need
  const loginAction = actions.find(a => a.name.includes('login'));

  // 4. Execute it
  if (loginAction) {
    const result = await bridge.execute(loginAction.name, {
      email: "user@example.com",
      password: "secure-password"
    });
    console.log(result);
  }

  // 5. Wait for navigation
  await bridge.waitForNavigation();

  // 6. Refresh actions for new page
  bridge.refresh();
}

Security

WAB is built with security as a first-class concern:

  • Permission-based access — Site owners control exactly what agents can do
  • Selector restrictions — Block sensitive areas of the page from agent interaction
  • Rate limiting — Built-in protection against abuse
  • Server-side license verification — Tier permissions are verified by the licensing server
  • Agent authentication — Optional agent identity verification
  • Opt-in only — Sites must explicitly add the script; users can disable via extensions

Best Practices

  1. Always use blockedSelectors to protect sensitive areas (forms with credit cards, admin panels)
  2. Start with minimal permissions and expand as needed
  3. Enable logging to monitor agent behavior
  4. Use the requireLoginForActions restriction for sensitive operations
  5. Keep your license key confidential

Examples

E-commerce Site

JavaScript
window.AIBridgeConfig = {
  licenseKey: "WAB-SHOP-XXXXX-XXXXX",
  agentPermissions: {
    readContent: true,
    click: true,
    fillForms: true,
    scroll: true
  },
  restrictions: {
    blockedSelectors: ["#checkout-payment", ".credit-card-form"],
    rateLimit: { maxCallsPerMinute: 30 }
  }
};

// After the bridge loads, add custom actions
document.addEventListener('wab:ready', () => {
  window.AICommands.registerAction({
    name: "searchProducts",
    description: "Search for products by keyword",
    trigger: "fill_and_submit",
    fields: [{ name: "query", selector: "#search-input", type: "text" }],
    submitSelector: "#search-btn",
    category: "search"
  });
});

SaaS Dashboard

JavaScript
window.AIBridgeConfig = {
  licenseKey: "WAB-SAAS-XXXXX-XXXXX",
  subscriptionTier: "pro",
  agentPermissions: {
    readContent: true,
    click: true,
    fillForms: true,
    apiAccess: true,
    extractData: true
  }
};

document.addEventListener('wab:ready', () => {
  // Custom API action
  window.AICommands.registerAction({
    name: "getAnalytics",
    description: "Fetch analytics data for the current period",
    trigger: "api",
    endpoint: "/api/analytics/current",
    method: "GET",
    requiresAuth: true,
    category: "data"
  });

  // Custom handler action
  window.AICommands.registerAction({
    name: "exportReport",
    description: "Generate and download a PDF report",
    trigger: "click",
    category: "export",
    handler: async () => {
      const res = await fetch('/api/report/generate');
      const blob = await res.blob();
      // trigger download...
      return { success: true, message: "Report downloaded" };
    }
  });
});

REST API

The WAB server provides a REST API for managing sites, licenses, and analytics.

Authentication

EndpointMethodDescription
POST /api/auth/registerPOSTCreate a new account
POST /api/auth/loginPOSTSign in and receive JWT token
GET /api/auth/meGETGet current user info

Sites

EndpointMethodDescription
GET /api/sitesGETList all your sites
POST /api/sitesPOSTAdd a new site
GET /api/sites/:idGETGet site details
PUT /api/sites/:id/configPUTUpdate site configuration
PUT /api/sites/:id/tierPUTChange subscription tier
DELETE /api/sites/:idDELETEDelete a site
GET /api/sites/:id/snippetGETGet install snippet
GET /api/sites/:id/analyticsGETGet analytics data

License

EndpointMethodDescription
POST /api/license/verifyPOSTVerify a license key for a domain
POST /api/license/trackPOSTRecord an analytics event

FAQ

Is WAB free to use?

The core script is open source and free forever. Advanced features like API access, detailed analytics, and automated login require a paid subscription.

Does WAB work with all AI agents?

WAB works with any agent that can execute JavaScript in a browser context — including Selenium, Puppeteer, Playwright, browser extensions, and AI tools like OpenAI's Operator or Anthropic's Computer Use.

What if my site is a SPA?

Call bridge.refresh() after navigation events to re-scan for new elements. The waitForElement() method helps agents wait for dynamically loaded content.

Can I use WAB without the licensing server?

Yes. Without a license key, WAB runs in free-tier mode with all basic permissions. The licensing server only validates premium features.