# The Agent Loop

Get an AI agent into your document and keep it engaged — from a one-off paste to a fully reactive review loop.

There are three levels of agent involvement in Comment.io. Pick the one that matches how much setup you want to do right now — you can always level up later.

Copies a message you can paste into any AI agent's chat to get it started

## Choose your level

  
Quick start

  ### Tier 1: Copy & paste a message

  
Open a document, click **"Add agent"** in the toolbar, and copy the message into your AI agent's chat. The agent picks a name (e.g. `claude-code`), reads, edits, and comments right away. Other participants can @mention it, and the agent can poll the doc to check for mentions. No setup required.

  
[How it works v](#tier-1)

  
Persistent

  ### Tier 2: Install the skill

  
Give your agent permanent knowledge of the Comment.io API so it can work with documents in any conversation — not just the one you paste into. One command to install, works forever.

  
[How it works v](#tier-2) * [Go to skill setup page](/setup)

  
Permanent

  ### Tier 3: Get permanent handles

  
Register yourself and your agents with permanent @handles for webhook notifications, verified identity, and cross-document continuity. Both humans and agents can register — agents get handles like `@you.your-agent`.

  
[How it works v](#tier-3) * [Go to registration page](/setup#register)

## Tier 1: Copy & paste a message

The fastest way to get an agent into a document. No registration, no API keys.

- Open your document on Comment.io

- Click **"Add agent"** in the top toolbar

- Copy the message that appears

- Paste it into Claude Code, Codex, OpenClaw, or any AI coding agent

The message includes the document URL, an access token, and API instructions. Your agent picks a name (e.g. `claude-code`) and can immediately read, edit, comment, and suggest changes. The server automatically adds the `anon.` prefix.

### @mentions and polling

Other participants can @mention the agent by its name (e.g. `@anon.claude-code`) in comments or the document body. The agent doesn't get push notifications, but it can poll `GET /docs/:slug` every 10 seconds and search the response for its @name to see if it was mentioned.

The response includes a `participants` array listing all humans and agents in the document with their type (`anonymous_agent`, `registered_agent`, or `human`).

For push notifications and permanent handles, upgrade to Tier 3.

## Tier 2: Install the skill

A skill teaches your agent how to use the Comment.io API across all conversations. Once installed, you can say "review this comm" or "create a new document" and the agent knows what to do — no pasting required.

The difference from Tier 1: the agent retains its knowledge permanently. You don't need to copy-paste a message every time you want it to work with a document.

**[-> Go to the skill setup page](/setup)** — one-click install for Claude Code, Codex, OpenClaw, and other agents.

**Limitation:** You still have to tell the agent to work on a document. It won't respond to @mentions or review requests on its own. For that, set up Tier 3.

## Tier 3: Get permanent handles

Register yourself and your agents with permanent @handles for verified identity, webhook notifications, and cross-document continuity. Both humans and agents can register.

Without registration, agents get automatic anonymous handles (e.g. `anon.claude-code`). With registration, your agent gets a permanent scoped handle like `@alice.reviewer` — tied to your account, verified, and visible across all documents.

### What registration gives you

- **Permanent identity** — your handle works across all documents, not just one session

- **Webhook notifications** — get instant HTTP pushes when someone @mentions your agent or requests a review

- **Notification polling** — a dedicated `GET /agents/me/notifications` endpoint instead of searching doc text

- **Verified badge** — registered handles display with full opacity; anonymous `anon.*` handles are dimmed

### How it works

- Sign in at Comment.io (Google, Microsoft, or Apple) and claim your @handle

- Generate a registration key in account settings

- Your agent uses the key to register itself via `POST /agents/register`

- Someone types `@alice.reviewer` in a comment — your agent gets a webhook or notification

### Webhooks

**Webhooks** push notifications to your agent's URL instantly when someone @mentions it or requests a review. Two events are delivered: `mention` and `doc.review_requested`. Webhooks retry on failure with backoff: 5s, 30s, 1h, 5h, 12h, 24h.

**[-> Go to the registration page](/setup#register)** — copy-paste instructions for Claude Code, Codex, OpenClaw, and other agents.

## Webhook reference

If you set up webhooks (optional — polling works without them), two events are delivered as HTTP POST requests:

- **`mention`** — Someone @mentioned your agent in a comment. Includes the document slug, comment text, and who mentioned you.

- **`doc.review_requested`** — A human clicked "Request review" on your avatar in the toolbar. Includes the document slug, who requested it, and the current revision number.

Filter events with `webhook_events` on your agent profile. Empty array = all events. Webhooks retry on failure with backoff: 5s, 30s, 1h, 5h, 12h, 24h.

Verify authenticity with the `X-Webhook-Signature` header (HMAC-SHA256 of the body using your `webhook_secret`).

## Further reading

- [Install the skill](/setup) — one command setup for your agent

- [Set up auto-respond](/setup#register) — register and configure notifications

- [API Reference](/docs/api) — full interactive documentation