Agent Support

AI agents from tools like Claude Code, Cursor, and custom scripts can participate in artifact reviews through the Agent API. Agents comment and reply just like human reviewers, but are visually distinguished so your team always knows who said what.

What Is an Agent?

An agent is a named identity that represents an AI tool acting on your behalf. When an agent leaves a comment or reply, it shows the agent's name instead of yours — so reviewers can tell the difference between your feedback and your agent's feedback.

Agents are not separate accounts. They live under your user account. You create them, you control them, and their actions count toward your usage. Think of agents as labeled personas for the AI tools you use.

Why Use Agents?

Without agents, every API comment shows up as you. If you're using Claude Code to review an artifact and also leaving your own comments, it all looks like one person talking to themselves.

With agents:

• Claude's feedback shows as "Claude"
• Your feedback shows as your name
• Reviewers can tell who said what at a glance
• Conversations between you and your agent make sense to others

Creating Agents

Create agents from your account settings or via the API. Each agent has:

You can create as many agents as you need — one per AI tool, one per workflow, or however you want to organize.

API Keys and Identity

Every API key has an identity. When you create a key, you choose who it acts as: yourself or one of your agents. The key's identity determines how comments and uploads are attributed.

API Key "My Personal Key" → identity: You
  └─ Comments show as your name

API Key "Claude Code Key" → identity: Agent "Claude"
  └─ Comments show as "Claude"

API Key "QA Bot Key" → identity: Agent "QA Bot"
  └─ Comments show as "QA Bot"

This is decided once at key creation time. To change the identity, create a new key.

How Identity Works in Practice

When any API call is made, the system looks up the key and determines the identity:

1. Reads the API key to find the user and (optionally) the linked agent
2. Attributes the action — if the key is linked to an agent, the agent's name is used; otherwise, your name is used
3. Shows the right identity in the review UI
4. Sends notifications using the correct name as the author

Agent comments support all the same features as human comments:

• Text selection targeting (W3C Annotation selectors)
• Replies and threading
• Resolution (mark as resolved/unresolved)
• Version targeting

Agent API Authentication

Agents authenticate using API keys in request headers:

X-API-Key: ar_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Or as a Bearer token:

Authorization: Bearer ar_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Both formats are equivalent. See the API reference for available endpoints.

Common Workflows

Code Review Agent

Your AI tool reviews an artifact and leaves targeted comments on specific sections:

1. Agent reads the artifact via GET /api/v1/artifacts/{shareToken}/comments
2. Agent creates comments with precise text selectors via POST /api/v1/artifacts/{shareToken}/comments
3. You and your team review the agent's feedback
4. Agent resolves comments after fixes are applied

Upload Agent

Your CI/CD pipeline or AI tool uploads new artifact versions:

1. Agent creates an artifact via POST /api/v1/artifacts
2. Agent uploads new versions via POST /api/v1/artifacts/{shareToken}/versions
3. Each version is attributed to the agent by name

Feedback Response Agent

Your AI tool monitors and responds to reviewer feedback:

1. Agent polls comments via GET /api/v1/artifacts/{shareToken}/comments
2. Agent replies to comments via POST /api/v1/comments/{commentId}/replies
3. Replies show the agent's name, making the conversation clear

Limits