Draft v1.0 chevron_right Open Standard

The UI Protocol for AI Agents

HIT enables applications to publish a machine-readable contract of every UI capability-so Agents can navigate and operate software deterministically, without pixel-scraping or fragile CSS selectors.

Read the Spec Demo →

Demo

See it in action.

Architecture

Three pillars. One contract.

🌳

The Tree (DIL)

Data Intent Layer

A nested JSON structure representing the UI's complete hierarchy. Every interactive element is a Node exposing semantics, schemas, and live state.

📡

Intent Socket

Real-Time Stream

A WebSocket protocol that pushes live state updates (PATCH_STATE) as the UI evolves (e.g. loading states, validation errors). No polling required.

🤖

Agent Portal

MCP Interface

The bridge translating standard LLM tool-calling into HIT protocol operations. Fully MCP-compliant via execute_intent and list_nodes.

Protocol Flow

Discovery → Telemetry → Execution

1
Phase 1

Discovery

get_tree() SAFE

Agent requests the full Hierarchical Intent Tree mapping the complete application capabilities.

list_nodes(filter) SAFE

Agent semantically indexes nodes matching a specific intent boundary.
2
Phase 2

Telemetry

focus_node(uid) SAFE

Agent signals intention. The GUI visually engages the "Ghost Highlight" for the human observer.

PATCH_STATE STREAM

The app pushes real-time visual state updates (loading, success, errors) back to the Agent.
3
Phase 3

Execution

call_action() MEDIUM RISK

Agent triggers a rigidly defined structural action declared on the active node.

Guardrail HIGH RISK

If the action carries high risk, the server pauses execution pending physical Human confirmation.

Reference

The Agentic Schema

A HIT Node is the atomic unit of the protocol, a structured, localized specification of a user interface capability.

Privacy & Control

Built for human oversight

Agent access is fundamentally constrained by what exactly the application developers explicitly register.

🔭

Scoped Visibility

The tree exposes nodes strictly based on the User's active permission scope. Secrets are completely unmapped.

🛑

The Kill Switch

A globally bound intervention mechanism. Disconnects the socket intercepting Agent commands instantly.

⚠️

Risk Guardrails

Tags declare risk logic natively. High-risk methods trigger a server-bound interruption requiring Human approval.

🔒

Deterministic Input

Agents cannot arbitrarily hallucinate inputs. Form schemas dictate strict types and valid enum lists.

Integration

Add HIT to your app in 4 steps

1. Include the SDK

<!-- Zero dependencies. Drop it into your bundle. -->
<script src="https://unpkg.com/@hit-protocol/core/dist/browser.js"></script>

2. Register an interactive element

HIT.register('checkout.submit', {
  role: 'action',
  intent: {
    domain: 'commerce',
    action: 'submit',
    object: 'order'
  },
  actions: [{
    name: 'execute',
    risk: 'high',
    handler: async (payload) => ({
      order_id: await processOrder(payload)
    })
  }]
}, document.getElementById('btn-submit'));

3. Run the Local Broker (Optional)

# Terminal
docker run -p 8080:8080 -p 8081:8081 buto007/hit-relay-core

The HIT-Relay-Core manages the WebSockets and broadcasts State events between the browser UI and AI Agents.

4. Agent Execution (MCP)

// 1. Agent discovers the capability
const nodes = HIT.AgentPortal.list_nodes();

// 2. Agent isolates focus dynamically
HIT.Manager.focusNode('checkout.submit');

// 3. Agent passes parameters. High risk fires Guardrail!
const receipt = await HIT.AgentPortal.execute_intent(
  'commerce.submit.order',
  { confirm: true }
);

Future Vision

From Alpha to Standard

Done

v1.0-ALPHA

The Provider

check_circle Core Node registration SDK
check_circle React Component Hooks
check_circle Risk Guardrails

Next Up

v1.0-BETA

The Bridge

check_circle Node.js WebSocket Engine & Local Broker
radio_button_unchecked Vue / Svelte Integrations
radio_button_unchecked Multi-Client State

Future

v1.0-FINAL

The Standard

radio_button_unchecked NPM Publish Registry
radio_button_unchecked Core Conformance Suite
radio_button_unchecked Community Governing Board

Was this protocol specification helpful?

Leave feedback to guide the direction of v1.0.