ARIA for AI agents · Semantic layer · MCP-ready

The open protocol for AI-navigable web apps.

Define what your app is, what it can do, and what rules apply — as a versioned semantic contract any AI agent can read over HTTP, MCP, or in-process hooks — without scraping fragile markup.

Read the Docs View on GitHub

MITOpen standard
SDK · Policy · EventsContract stack
HTTP · MCP · ReactAgent surface

bun add @synqel/sdk zod

Flow

How it works

Three layers from declaration to audited execution — built for humans and machines to share the same contract.

Register

Describe your app's entities and actions in semantic terms. Declare what exists, what can be done, and in what order.

Understand

AI agents read a clean, structured snapshot — not HTML. They know what objects exist, what actions are available, and what policies apply.

Execute

Policy gates each attempt; optional JSON Schema validates payloads; bound handlers run your real business logic. Every step emits semantic events for audits and observability.

Contrast

What AI agents see

Without Synqel, agents parse opaque markup. With Synqel, they get a versioned envelope with your registry snapshot — intent, optional JSON Schema per action, workflows, and capabilities.

Noise

Before — raw HTML

html

<!-- What AI sees today: raw HTML soup -->
<div class="sc-1x2b3c product-card">
  <span class="price-label">$299</span>
  <button class="btn btn-primary sc-4d5e6f"
    onclick="addToCart(123)">
    Add to Cart
  </button>
</div>

Signal

After — Synqel envelope (synqel.snapshot.v1)

json

{
  "format": "synqel.snapshot.v1",
  "registryVersion": 12,
  "snapshot": {
    "entities": [
      {
        "id": "product_123",
        "type": "product",
        "metadata": { "price": 299 }
      }
    ],
    "actions": [
      {
        "id": "add_to_cart",
        "intent": "mutation",
        "deterministic": true,
        "inputJsonSchema": {
          "type": "object",
          "properties": {
            "sku": { "type": "string" },
            "qty": { "type": "number" }
          },
          "additionalProperties": false
        }
      }
    ],
    "capabilities": {
      "canSearch": true,
      "canCheckout": true
    },
    "workflows": [
      {
        "id": "checkout_flow",
        "steps": ["add_to_cart", "confirm_order"]
      }
    ]
  }
}

Use cases

Where teams adopt Synqel first

Any product with multi-step tasks, sensitive mutations, or AI copilots benefits from a single semantic contract — not a one-off integration per screen.

Retail · SaaS

Commerce & checkout

Expose carts, shipping zones, promos, and payment steps as entities and workflows so agents complete purchases without guessing hidden state.

Internal tools

Admin & back-office

Bulk edits, approvals, and role-gated mutations become explicit actions with policy — agents and humans share the same rule chain.

Support & ticketing

Ticket status, allowed transitions, and safe customer-facing actions are readable as a snapshot instead of inferred from DOM layout.

Growth

Onboarding & wizards

Multi-step flows register as ordered workflows: the agent knows what step comes next and which fields are blocking progression.

Finance · Health

Compliance & regulated flows

High-risk steps stay behind policy gates; every attempt and outcome is emitted as a semantic event for auditors and replay.

DevTools

Developer dashboards

Releases, feature flags, pipelines, and environments surface as navigable capabilities — ideal for internal AI assistants and bots.

Products

What you can ship on top of the protocol

The SDK is the spine; these are common product shapes teams build once the registry, policy, and events are in place.

In-app copilot

A chat or command palette that reads the same registry snapshot your external agents use — one contract, two audiences.

Agent bridge (@synqel/mcp)

Stdio MCP tools expose snapshot + execution to Claude Desktop, Cursor, and other MCP hosts — without inventing a parallel agent protocol.

Agent-native E2E testing

Drive flows by intent and workflow ids instead of brittle selectors; assert on policy decisions and emitted events.

Audit & observability console

Stream semantic events across tenants or services: who attempted what, which policy fired, and the structured result.

Policy playground

Let operators or developers simulate mutations against rule chains before changes hit production traffic.

Multi-tenant AI layer

Per-workspace or per-customer registry snapshots and capabilities — agents stay scoped to the right org and data boundary.

See concrete patterns in Examples and wire policy in Policy.

Beyond AI agents

Specialized applications

The same semantic contract that makes your app AI-navigable also unlocks structural advantages in testing, accessibility, and growth.

Testing

AI-driven E2E & regression testing

Replace brittle CSS selectors with intent and workflow IDs. Tests assert on semantic events and policy decisions — not DOM snapshots — so they survive UI refactors without breaking.

Drive flows by workflow ID, not fragile locators
Assert on emitted events and policy outcomes
Replay any agent session for regression coverage

Accessibility

Richer-than-ARIA semantic surface

The registry exposes what the app is and what it can do — not just visual roles. Automated a11y auditors, screen readers, and AT tools get structured entities and allowed actions with full machine-readable context.

Entities carry type and purpose, not just DOM role
Actions declare intent class and policy constraints
One contract for AT tools, agents, and auditors alike

Marketing & Growth

Semantic funnels and personalization

Expose experiments, campaigns, and conversion steps as first-class semantic workflows. AI agents and analytics tools read the same structured surface to optimize flows, personalize experiences, and measure what matters.

Campaigns and experiments as versioned entities
Conversion steps registered as ordered workflows
Policy gates on high-value mutations (upgrades, checkouts)

Design

Key principles

Intent over structure

Actions carry intent class (navigation, mutation, query, system) — not DOM selectors. AI agents reason about purpose, not markup.

Deterministic by default

Policy gates prevent AI agents from executing mutations without explicit permission. Every action goes through a composable rule chain.

MCP-ready, not MCP-competitive

Synqel defines meaning and governance; MCP is optional transport. Ship the same registry via React hooks, HTTP snapshot routes, or @synqel/mcp tools (synqel_get_snapshot, synqel_execute_action).

Audience

Who it's for

Frontend developers

Adding AI features to existing web applications.

AI / agent developers

Who need structured application context instead of raw HTML.

Accessibility engineers

The same semantic tree concept, richer than ARIA, machine-readable.

Platform builders

Who need a standardized observability and policy layer.

Ship a semantic surface your agents can trust.

Start with the protocol spec, wire the SDK, and expose a clean snapshot — no scraping, no brittle selectors.

SDK quickstart Read the specification