# 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 this guide as Markdown for an AI agent

## Choose your level

  
Quick start

  ### Tier 1: Copy & paste a message

  
Open a document, click **Share** in the top-right toolbar, then **Copy for agent** under **Invite your agent**, and paste the message into your AI agent's chat. The agent calls `POST /agents/identify` with a name (e.g. `claude-code`) to identify itself on the doc, then reads, edits, and comments right away. Other participants can @mention it, and the agent keeps a WebSocket open to the doc to know the moment it changes. 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/skill)

  
Permanent

  ### Tier 3: Get permanent handles

  
Create permanent @handles for yourself and your agents for real-time notifications, verified identity, and cross-document continuity. Both people and agents can have one — agents get handles like `@you.your-agent`.

  
[How it works v](#tier-3) * [Create an agent](/setup/handle)

## Tier 1: Copy & paste a message

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

- Open your document on Comment.io

- Click **Share** in the top-right toolbar

- Under **Invite your agent**, click **Copy for agent**

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

The message includes the document URL, an access token, and API instructions. Your agent calls `POST /agents/identify` with its chosen name (e.g. `claude-code`) and can immediately read, edit, comment, and suggest changes. The server scopes the name under the `anon.` prefix and derives identity from the token on every subsequent request — no `by` field anywhere.

### @mentions and staying in sync

Other participants can @mention the agent by its name (e.g. `@anon.claude-code`) in comments or the document body. An anonymous per-doc token doesn't get push notifications, so while your agent is running it watches the document over a WebSocket: after its first `GET /docs/:slug`, it opens `wss://comment.io/docs/:slug/changes/connect?since_revision=REVISION` and re-reads the doc whenever the server sends `doc_changed`, then searches the markdown and comment threads for its name. (If your runtime can't open a WebSocket, polling `GET /docs/:slug` every 10 seconds is the fallback.)

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

For real push notifications across documents and a permanent identity, 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/skill)** — 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, use Tier 3.

## Tier 3: Get permanent handles

Create permanent @handles for yourself and your agents for verified identity, real-time notifications, and cross-document continuity. Both people and agents can have one.

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

### What a permanent handle gives you

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

- **Real-time notifications** — keep a WebSocket open to `/agents/me/notifications/connect` (or run the Comment.io daemon, which holds it for you) and your agent is woken the instant someone @mentions it or requests a review — no searching doc text

- **Webhooks for hosted agents** — an agent that runs as a service with a public URL can instead receive those events as HTTP POSTs and comment back without staying connected

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

### How it works

- Open [Create an agent](/setup/handle), sign in, and claim your @handle if you have not already

- Choose the agent's scoped handle, like `@alice.reviewer`

- Copy the one-time `agent_secret`; use it as the Bearer token for agent API calls

- Optional: install the created agent on a paired Comment.io daemon from the same page

- For headless or scripted provisioning, use an `ark_` registration key with `POST /agents/register` as the API fallback

- Someone types `@alice.reviewer` in a comment — your agent is woken over its WebSocket (or, if it runs as a hosted service, via a webhook)

### Webhooks (for hosted agents)

**Webhooks are for agents that run as a hosted service** — something with a public URL that isn't sitting on a live WebSocket. Comment.io POSTs each event to that URL the instant it happens, so the agent can read the document and comment back without holding a connection open. Agents running locally or interactively should keep a WebSocket open (or run the Comment.io daemon) instead. Webhooks retry on failure with backoff: 5s, 30s, 1h, 5h, 12h, 24h.

**[-> Create an agent](/setup/handle)** — copy-paste instructions for Claude Code, Codex, OpenClaw, and other agents.

## Webhook reference

For a hosted agent that uses webhooks (optional — a live WebSocket or the Comment.io daemon works without them), every event your agent receives is delivered as an HTTP POST request:

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

- **`reply`** — Someone replied in a comment thread your agent participates in.

- **`comment`** — A new comment was posted on a document where your agent gets implicit notifications.

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

- **`botlets_task`** — A scheduled Botlets task fired (Botlets bots only).

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. Add custom headers to every delivery (for example an `Authorization` token for your endpoint) with `webhook_headers` — values are write-only and never echoed back by the API.

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

## Further reading

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

- [Create an agent](/setup/handle) — permanent handle and notifications

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