Set up your coding agent

Most coding agents read a project or user instructions file on startup. Add the block below to it and the agent will check every website for AIP first, and only fall back to browser automation when a site doesn’t support it.

The instructions block

## Interacting with websites: prefer the Agent Interaction Protocol (AIP)

Before using browser automation on a website, check whether it speaks AIP (Agent Interface
Manifest). If it does, use AIP instead of browser automation for that site. Fall back to
browser automation only when AIP is absent or insufficient (e.g. no action exists for what's
needed).

**Detect it** — check, in order:
1. `GET /.well-known/agent-interface` on the site's origin — returns JSON with `protocol: "AIP"`
   and a `pages[]` list (each with `manifest`/`json` URLs).
2. `<link rel="agent-interface" href="...">` in the page `<head>`.
3. `GET /sitemap.toon` or `/sitemap.xml` — AIP sites list their AIP pages there too.

If none of these resolve, the site doesn't support AIP — use browser automation as normal.

**Use it**:
1. Fetch the page's manifest: `GET <page-url>.toon` (compact) or `.json`. It lists `state` and
   `actions[]`, each action with `input_schema` and `input_example`.
2. If the manifest requires a session (`state_scope: "session"` needed, or actions need live
   browser state), open the page in the browser first and let its own bridge connect, then look
   for a token the page displays for agent handoff (often in an "agent instructions" or "copy for
   your agent" panel) and use that — rather than minting your own via `POST /__aim/session`. A
   self-minted token isn't bound to any live browser tab, so actions that read or mutate
   browser-held state can fail, hang, or need a tab-connection step you can't perform yourself.
   Only mint your own session token when no live browser tab is involved (pure server-side/public
   state). Send the token as `Authorization: Bearer <token>` on subsequent requests, or rely on
   the session cookie if a human already has the tab open.
3. Re-fetch the manifest with the token to get session-scoped state/actions.
4. Invoke an action: `POST /__aim/invoke` with `{ "actionId": "<id>", "input": <matches input_schema> }`
   and the same `Authorization` header. Match `input_schema`/`input_example` exactly — don't wrap
   input in an extra parameter object.
5. If a call 409s on a session/tab/page conflict, check the manifest's `actions[]` for a
   documented recovery action (e.g. `disconnect`) before retrying or falling back — invoke it,
   then restart from step 2 with a fresh session. Don't probe undocumented endpoints to force a
   stuck session free; if no recovery action is documented, fall back to browser automation and
   say so.
   - If the page's own displayed token is blank/missing specifically *because* of this error (some
     sites clear it on any connection error, even recoverable ones), the underlying session is
     often still valid — only tab/page ownership is contested. From a tab already open on that
     origin, invoke the recovery action via a same-origin `fetch(..., { credentials: "include" })`
     (e.g. through a JS-eval browser tool) instead of a `Bearer` header — the browser's own session
     cookie authenticates it without needing to see the token value.
6. Re-fetch the manifest afterward to confirm the result — don't assume success from a 200.
7. Treat a timeout as "unknown outcome," not permission to retry the same action.

Never publish or log a session token. Only invoke actions a human explicitly asked for.

Where to put it

Pick your agent. Project files apply to one repository; global files apply everywhere you use that agent.

Scope	File
Project	`CLAUDE.md` in the repo root
Global	`~/.claude/CLAUDE.md`

Claude Code loads both on startup. Run /memory inside a session to check which files are active.If you use Claude in Chrome for browser automation, you can name it in the block: replace “browser automation” with “claude-in-chrome”.

Scope	File
Project	`AGENTS.md` in the repo root
Global	`~/.codex/AGENTS.md`

Codex CLI merges the global file with the project file, and with AGENTS.md files in subdirectories.

Scope	File
Project	`.cursor/rules/aip.mdc`
Global	Cursor Settings → Rules → User Rules (paste the block)

Start the .mdc file with frontmatter so the rule is always on:

.cursor/rules/aip.mdc

---
description: Prefer the Agent Interface Protocol over browser automation
alwaysApply: true
---

<paste the instructions block here>

Cursor also reads a root AGENTS.md.

Scope	File
Project	`.github/copilot-instructions.md`

Used by Copilot Chat in VS Code and by the Copilot coding agent. The coding agent also reads AGENTS.md.

Scope	File
Project	`GEMINI.md` in the repo root
Global	`~/.gemini/GEMINI.md`

Run /memory show to check what’s loaded.

Scope	File
Project	`.windsurf/rules/aip.md`
Global	`~/.codeium/windsurf/memories/global_rules.md`

Set the project rule’s activation mode to Always On.

Scope	File
Project	`.clinerules/aip.md`
Global	Cline’s global rules folder (Rules panel → Global Rules)

Using several agents in one repo? Put the block in AGENTS.md. Codex, Cursor, GitHub Copilot’s coding agent and a growing list of other tools read it. Then point the others at it, for example add @AGENTS.md to CLAUDE.md.

What the agent needs

The instructions only help if the agent can act on them:

HTTP tools: authenticated GET and JSON POST (for example curl in a shell, or a fetch tool). A read-only web browsing tool can discover manifests but can’t invoke actions.
A browser, for session-scoped pages: the human (or the agent’s browser tool) must open the page so its bridge connects, then hand over the displayed token.

See Build an agent client for the full protocol loop.

Getting started

Learn

Develop

Specification

Security

Community

The instructions block

Where to put it

What the agent needs

​The instructions block

​Where to put it

​What the agent needs

The instructions block

Where to put it

What the agent needs