Agent Contracts

Every component ships with a machine-readable contract. AI agents read intent, safety level, and consequences directly from the DOM.

What Is The Agent Layer

Every VhyxUI component ships with a machine-readable contract. This contract describes what the component does, its safety level, and what consequences follow from interaction. AI agents and testing tools read these contracts directly from the DOM — no additional API, no configuration, no schema to write.

Contracts live in the data-vhyx-contract attribute on every component's root element. Any VhyxSeal-compatible tool can read a page, collect these attributes, and build a complete picture of available actions and their risk profile. This layer is built into every component by default — it cannot be removed, only overridden.

Default Contracts

Here is the default contract for the Button component.

Button default contract

{
  "type": "action",
  "intent": "trigger-action",
  "safetyLevel": "low",
  "requiresConfirmation": false,
  "destructive": false,
  "reversible": true,
  "consequence": "triggers the associated action",
  "requires": []
}

Field	Type	What it means
`type`	string	Category of component action
`intent`	string	Machine-readable action identifier
`safetyLevel`	string	How carefully an agent should proceed
`requiresConfirmation`	boolean	Must agent ask human before acting
`destructive`	boolean	Permanently deletes or modifies data
`reversible`	boolean	Whether the action can be undone
`consequence`	string	Plain language description of what happens
`requires`	array	Conditions that must be true before acting

Every VhyxUI component ships with a default contract. You get this automatically — no configuration needed.

Override A Contract

Pass a contract prop to any component to merge overrides on top of the default. Only the fields you specify change — the rest remain from the default contract.

Basic — add intent and consequence

<Button
  variant="primary"
  contract={{
    intent: 'save-draft',
    consequence: 'saves the current draft to the database',
  }}
>
  Save Draft
</Button>

Destructive — delete account

<Button
  variant="destructive"
  contract={{
    intent: 'delete-account',
    safetyLevel: 'critical',
    requiresConfirmation: true,
    destructive: true,
    reversible: false,
    consequence: 'permanently deletes the user account and all associated data',
    requires: [
      'user is authenticated',
      'confirmation dialog has been acknowledged',
    ],
  }}
>
  Delete Account
</Button>

High-stakes actionsActions like order placement or payment should always set requiresConfirmation: true and describe the consequence precisely. Agents will not proceed without this information.

Form submission with requires array

<Button
  type="submit"
  variant="primary"
  contract={{
    intent: 'submit-order',
    safetyLevel: 'high',
    requiresConfirmation: true,
    consequence: 'places the order and charges the payment method on file',
    requires: [
      'cart is not empty',
      'payment method is valid',
      'shipping address is set',
    ],
  }}
>
  Place Order
</Button>

The Manifest

VhyxSeal-compatible tools can generate a manifest from any VhyxUI page — a single JSON document that describes every contract-bearing component on that page. The manifest is what an AI agent reads before deciding how to interact with your application.

Below is a simplified manifest for a page with a single Button that places an order. The agent reads this, sees safetyLevel: "high" and requiresConfirmation: true, and knows to pause and ask the human before proceeding.

page-manifest.json

{
  "version": "1.0.0",
  "components": [
    {
      "id": "vhyx-button-1",
      "type": "action",
      "intent": "submit-order",
      "safetyLevel": "high",
      "requiresConfirmation": true,
      "consequence": "places order and charges payment method"
    }
  ]
}

For deeper reading on VhyxSeal contracts and the manifest format, see the VhyxSeal Documentation →