Agentation is currently desktop only.

## Overview

Agentation exposes callbacks that let you integrate annotations into your own workflows — send to a backend, pipe to terminal, trigger automations, or build custom AI integrations.

- Sync annotations to a database or backend service
- Build analytics dashboards tracking feedback patterns
- Create custom AI integrations (MCP servers, agent tools)

## Props

`onAnnotationAdd`(annotation: Annotation) => void  
Called when an annotation is created

`onAnnotationDelete`(annotation: Annotation) => void  
Called when an annotation is deleted

`onAnnotationUpdate`(annotation: Annotation) => void  
Called when an annotation comment is edited

`onAnnotationsClear`(annotations: Annotation\[\]) => void  
Called when all annotations are cleared

`onCopy`(markdown: string) => void  
Callback with the markdown output when copy is clicked

`onSubmit`(output: string, annotations: Annotation\[\]) => void  
Called when "Send Annotations" is clicked

`copyToClipboard`boolean  
default: true  
Set to false to prevent writing to clipboard (if handling via onCopy)

`endpoint`string  
MCP server URL for syncing annotations

`sessionId`string  
Pre-existing session ID to use

`onSessionCreated`(sessionId: string) => void  
Called when a new session is created

`webhookUrl`string  
Webhook URL to receive annotation events

## Basic usage

Receive annotation data directly in your code:

```
import { Agentation, Annotation } from "agentation";

function App() {
  const handleAnnotation = (annotation: Annotation) => {
    console.log(annotation.element, annotation.comment);
  };

return (
    <>
      <YourApp />
      <Agentation onAnnotationAdd={handleAnnotation} />
    </>
  );
}
```

## Annotation type

The `Annotation` object passed to callbacks. See [Agentation Format](/content/schema/index.html) for the full schema.

```
type Annotation = {
  // Required
  id: string;              // Unique identifier
  comment: string;         // User's annotation text
  elementPath: string;     // CSS selector path
  timestamp: number;       // Unix timestamp (ms)
  x: number;               // % of viewport width (0-100)
  y: number;               // px from document top
  element: string;         // Tag name ("button", "div")

// Recommended
  url?: string;            // Page URL
  boundingBox?: {          // Element dimensions
    x: number;
    y: number;
    width: number;
    height: number;
  };

// Context (varies by output format)
  reactComponents?: string;   // Component tree
  cssClasses?: string;
  computedStyles?: string;
  accessibility?: string;
  nearbyText?: string;
  selectedText?: string;      // If text was selected

// Browser component fields
  isFixed?: boolean;       // Fixed-position element
  isMultiSelect?: boolean; // Created via drag selection

// Annotation kind (defaults to "feedback")
  kind?: "feedback" | "placement" | "rearrange";

// Layout mode data
  placement?: {
    componentType: string;
    width: number;
    height: number;
    scrollY: number;
    text?: string;
  };
  rearrange?: {
    selector: string;
    label: string;
    tagName: string;
    originalRect: { x: number; y: number; width: number; height: number };
    currentRect: { x: number; y: number; width: number; height: number };
  };
};
```

## HTTP API

The `agentation-mcp` server provides a REST API for programmatic access:

### Sessions

|     |     |     |
| --- | --- | --- |
| POST | /sessions | Create a new session |
| GET | /sessions | List all sessions |
| GET | /sessions/:id | Get session with annotations |

### Annotations

|     |     |     |
| --- | --- | --- |
| POST | /sessions/:id/annotations | Add annotation |
| GET | /annotations/:id | Get annotation |
| PATCH | /annotations/:id | Update annotation |
| DELETE | /annotations/:id | Delete annotation |
| POST | /annotations/:id/thread | Add thread message |
| GET | /sessions/:id/pending | Get pending annotations |
| GET | /pending | Get all pending annotations |

### Events (SSE)

|     |     |     |
| --- | --- | --- |
| GET | /sessions/:id/events | Session event stream |
| GET | /events | Global event stream (optionally filter with `?domain=...`) |

### Health

|     |     |     |
| --- | --- | --- |
| GET | /health | Health check |
| GET | /status | Server status |

## Real-Time Events

Subscribe to real-time events via Server-Sent Events:

```
# Session-level: events for a single page
curl -N http://localhost:4747/sessions/:id/events

# Global: events across ALL sessions
curl -N http://localhost:4747/events

# Filtered by domain: events for pages on a specific domain
curl -N "http://localhost:4747/events?domain=localhost:3001"

# Reconnect after disconnect (replay missed events)
curl -N -H "Last-Event-ID: 42" http://localhost:4747/sessions/:id/events
```

### Event types

- `annotation.created` — New annotation added (includes `kind` field for design annotations)
- `annotation.updated` — Annotation modified (comment, status, design data, etc.)
- `annotation.deleted` — Annotation removed
- `session.created` — New session started
- `session.updated` — Session updated
- `session.closed` — Session closed
- `action.requested` — Agent action requested
- `thread.message` — New message in annotation thread

## Environment Variables

| Variable | Description | Default |
| --- | --- | --- |
| AGENTATION\_STORE | Storage backend (`memory` or `sqlite`) | sqlite |
| AGENTATION\_EVENT\_RETENTION\_DAYS | Days to keep events | 7 |

## Storage

By default, data is persisted to SQLite at `~/.agentation/store.db`. To use in-memory storage:

```
AGENTATION_STORE=memory npx agentation-mcp server
```

## Programmatic Usage

```
import { startHttpServer, startMcpServer } from 'agentation-mcp';

// Start HTTP server on port 4747
startHttpServer(4747);

// Start MCP server (connects via stdio)
await startMcpServer('http://localhost:4747');
```

See [MCP Server](/content/mcp/index.html) for AI agent integration and available tools.