Build an agent client

Any HTTP client can speak AIP. This is the loop a well-behaved agent follows.

Detect AIP

Check, in order:

GET /.well-known/agent-interface: JSON with protocol: "AIP" and a pages[] list.
<link rel="agent-interface" href="..."> in the page <head>.
GET /sitemap.toon or /sitemap.json.

If none resolve, the site doesn’t speak AIP. Fall back to browser automation.

Get a session token from the human

Ask the human to open the page and copy the token from its agent instructions panel. Don’t mint your own with POST /__aim/session when a live tab is involved; it won’t be bound to that tab.

Read the manifest

GET /store.toon
Authorization: Bearer <token>

Check state_scope is session and browser_connected is true.

Invoke one action

POST /__aim/invoke
Authorization: Bearer <token>
Content-Type: application/json

{ "actionId": "add_to_cart", "input": { "variantId": "phone-black-256", "quantity": "1" } }

Match input_schema exactly. Don’t wrap input in an extra object.

Verify

Re-read the manifest and confirm the state changed as intended. Don’t trust a 200 alone.

Rules

Only invoke actions the human asked for. Confirm before consequential: true actions.
Read fresh state before each decision when acting on several items.
Treat 504 as unknown outcome. Re-read, never blindly retry.
On 409 for a session or page conflict, look for a documented recovery action (disconnect) in actions[]. Don’t probe undocumented endpoints.
Never log, publish or put the token in a URL.

Set up your agent

Ready-made instructions for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and Cline: Set up your agent.

Getting started

Learn

Develop

Specification

Security

Community

Rules

Set up your agent

​Rules

​Set up your agent

Rules

Set up your agent