##### Websites

- See the AWP Protocol Specifications below, and familiarize yourself with the standard ai parameters
- Add the appropriate ai parameters to your website.

> 🎉 Your website can be reliably used by any AI agent!

##### APIs

- See the AWP Protocol Specifications below, and familiarize yourself with the standard /ai-handshake endpoint
- Add the standard /ai-handshake endpoint to your API.

> 🎉 Your API can be reliably used by any AI agent!

- See the AWP Tool below, and familiarize yourself with its parse_html and parse_api methods.
- Add the AWP Tool to your AI Agent.

> 🎉 Your AI agent can now reliably use any AWP compliant websites or APIs!

Protocol Specifications

$3

#### Introduction

> ##### The Challenge of Web Interactivity for AI Agents
>
> Without information about what a web page is for, how it is structured, what features it provides, and how to interact with it, an AI agent has to figure out everything on its own.
>
> This is commonly done through scrappers and/or vision models aimed at guessing what the agent sees.
>
> Websites being diverse, complex, dynamic, Javascript-heavy and often moslty made of generic

> For more information about Universal Tools, see ◉ Universal Intelligence

$3

`bash
pip install awp

(if using universal tool) Choose relevant UIN install for your device

`python
import awp

Get HTML documentation

| Method | Parameters | Return Type | Description |
|--------|------------|-------------|-------------|
| parse_html | • html: str: HTML page to parse
• format: str \| None = "YAML": Output format | Any | Parses all AWP ai-* parameters on the page and returns a documentation in the requested format (YAML, JSON), usable by any AI agent to reliably understand and interact with that web page |
| parse_api | • url: str: URL of the API to parse
• authorization: str \| None = None: Authentication header if required
• format: str \| None = "YAML": Output format | Any | Calls the standard /ai-handshake endpoint of that API and returns an OpenAPI compliant documentation of that API in the requested format (YAML, JSON), usable by any AI agent to reliably understand and interact with that API |

#### As Universal Tool

`python
from awp import UniversalTool as AWP

Get HTML documentation

| Method | Parameters | Return Type | Description |
|--------|------------|-------------|-------------|
| __init__ | • verbose: bool \| str = "DEFAULT": Enable/Disable logs, or set a specific log level | None | Initialize a Universal Tool |
| parse_html | • html: str: HTML page to parse
• format: str \| None = "YAML": Output format | Tuple[Any, Dict] | Parses all AWP ai-* parameters on the page and returns a documentation in the requested format (YAML, JSON), usable by any AI agent to reliably understand and interact with that web page |
| parse_api | • url: str: URL of the API to parse
• authorization: str \| None = None: Authentication header if required
• format: str \| None = "YAML": Output format | Tuple[Any, Dict] | Calls the standard /ai-handshake endpoint of that API and returns an OpenAPI compliant documentation of that API in the requested format (YAML, JSON), usable by any AI agent to reliably understand and interact with that API |
| (class).contract | None | Contract | Tool description and interface specification |
| (class).requirements | None | List[Requirement] | Tool configuration requirements |

#### Example Output

##### Parse HTML

###### Input

`html




`yaml
elements:
- selector: html
description: Travel site to book flights and trains
contains:
- selector: html body form.form-booking-flight
description: Form to book a flight
state: pending
content: Book a flight Where to?
contains:
- selector: html body form.form-booking-flight input#destination[name='destination'][type='text'][role='destination-input']
description: Form input where to enter the destination
available_interactions:
- type: input
description: enables the form confirmation button, given certain constraints
attributes:
name: destination
role: destination-input
alt: destination input
aria-required: 'true'
maxlength: 30
minlength: 3
required: true
type: text
- selector: html body form.form-booking-flight div button
description: Confirmation button to proceed with booking a flight
content: See available flights
available_interactions:
- type: click
description: proceed
prerequisites:
- selector: html body form.form-booking-flight input#destination[name='destination'][type='text'][role='destination-input']
interaction: input destination
next_features:
- list of available flights
- book a flight
- login
- type: hover
description: diplay additonal information about possible flights
attributes:
aria-disabled: 'true'
- selector: html body form.form-booking-flight div button:nth-of-type(2)
description: Cancel button to get back to the home page
content: Back
available_interactions:
- type: click
description: dismiss form and return to home page
next_features:
- access forms to book trains
- access forms to book flights
`

> YAML (default) or JSON per requested format.
>
> YAML recommended for improved token efficiency and stability.

##### Parse API

###### Input

GET https//example.api.com/ai-handshake

###### Output

OpenAPI compliant documentation, YAML (default) or JSON per requested format.

Example available here.

> Tip: Tools like Swagger can automatically generate a OpenAPI compliant documentation for your API which you may serve at /ai-handshake. They usually also provide no-code UIs to display and interact wich that documentation on the web (eg. Swagger UI).

#### Playground

A ready-made playground is available to help familiarize yourself with the AWP protocols and tools.

`sh


Install project dependencies

!lng_icon !lng_icon The AWP tool can be used across all platforms (cloud, desktop, web, mobile).

- !lng_icon How to use natively with python (cloud, desktop)
- !lng_icon How to use on the web, or in web-native apps, with javascript/typescript (cloud, desktop, web, mobile)