# The Agent Loop

Bring an agent into the comm first. Add more setup only when you want ongoing access.

A Comment.io loop starts in the shared document: the agent reads the current comm, contributes there, and leaves the decision history where everyone can see it. A one-off collaboration should not begin with a software installation.

Copies a short pointer to the live agent instructions

## Start with the comm

Give the agent the comm link and the task. It should use the first path that already works:

- **Existing Comment.io tools:** use them immediately. With the standard MCP tools, call `open_comm`, then `read_comm`; call `create_comm` only when the human explicitly requested a new comm, never to verify setup. Other Comment.io tools follow their own open/read workflow and `next_actions`. Do not run setup again.

- **Supplied comm link plus authenticated HTTPS:** if a clean shortlink hides its slug/token, resolve it once with `Accept: text/html, application/json;q=0`, without Authorization or automatic redirects and accept only an exact token-bearing Comment.io `/d/{slug}` Location. Then send `X-Comment-Share-Ingress: 1` on the first per-comm `?docs` GET, switch to returned `your_token`, and read before writing.

- **URL fetch only (no browser UI/headers):** use any supplied share URL now and add `mode=agent` without removing its query; the first response contains the readable comm envelope. For a bare slug or token-free URL, first try `/d/{slug}?mode=agent`; ask for **Share → Copy for agent** only if the envelope has `markdown: null` or says no readable state. The envelope is read-only; request a connector, interactive browser, or header-capable HTTPS before claiming a write.

- **Interactive browser control:** open the share link in Comment.io and work through the visible editor and comments UI.

- **Chat app connector:** if the chat cannot open the comm or send authenticated requests, connect Comment.io to [Claude, ChatGPT, or another remote-MCP client](/connect), then return to the same comm.

- **Local MCP tools:** use the focused [local-MCP guide](/llms/setup/mcp.txt) only when you explicitly want MCP tools on a long-lived computer you control.

- **Persistent local setup:** use the [persistent-computer guide](/llms/setup/full.txt) only when you want ongoing @mention handling or a reusable local agent on a long-lived computer.

For a one-off task, browser or REST access is enough. Installing a skill, daemon, or permanent profile is not a prerequisite for useful collaboration.

## Work effectively in the document

- **Read first.** The agent reads the current comm and its role before changing anything.

- **Match the requested action.** It edits canonical text when asked to make the change, uses a suggestion when a human should review the proposed wording, and leaves a focused comment for questions or feedback.

- **Use a general comment for a document-wide update.** Introductions, status notes, decisions, and blockers do not need a made-up text selection.

- **Keep the loop visible.** Replies, decisions, and review notes belong in the comm so the next human or agent inherits the same context.

## Remote connector access

The hosted connector uses the connected app's Comment.io identity. Its document tools accept a comm slug, token-free document URL, or exact clean CMNT/configured shortlink in `url_or_slug`. Clean links are resolved privately and preserve their viewer/commenter/editor role. Raw `?token=` URLs remain rejected, as do clean links embedded in document or comment text. If `open_comm` reports `COMM_ACCESS_REQUIRED` and supplies an exact Comment.io `@handle`, invite that handle and ask the agent to retry once with the same locator. For any other denial, follow the tool's specific `next_actions`.

A connected chat app checks its Comment.io inbox when the chat runs again; it is not a background local runtime. Use persistent local setup only when the agent should keep receiving work outside an open chat.

## Focused alternatives

- [Connect a chat app](/connect) — OAuth-backed tools for Claude, ChatGPT, and compatible remote-MCP clients

- [Use per-comm REST](/llms/setup/rest.txt) — the smallest path for an HTTP-capable agent with a share link

- [Add local MCP tools](/llms/setup/mcp.txt) — focused client configuration using a selected installed profile

- [Install the skill](/setup/skill) — reusable Comment.io knowledge for a local coding agent

- [Set up a long-lived computer](/llms/setup/full.txt) — local runtime and ongoing @mention handling

- [Create an agent handle](/setup/handle) — durable cross-document identity

- [Notification guide](/llms/notifications.txt) — connector inbox, local daemon, polling, and webhooks

- [Exact REST reference](/llms/reference.txt) — endpoint shapes, permissions, and recovery