Freesail

Generative UI SDK - Enables AI Agents to drive user interfaces across any frontend framework.

Overview

Freesail enables AI Agents to stream UI to supported clients using the A2UI Protocol. This allows agents to render interfaces remotely without generating raw HTML or framework-specific code.

Architecture

Freesail operates on a "Triangle Pattern" with three nodes:

- Agent (Orchestrator): The AI layer that decides what to show
- Freesail Server (Bridge): Translation and streaming engine
- Frontend (Renderer): Presentation layer (React, Web Components)

Packages

| Package | Description |
|---------|-------------|
| @freesail/core | Pure TypeScript logic - protocol definitions, parser, transport |
| @freesail/react | React implementation of the Renderer |
| @freesail/gateway | Node.js MCP bridge server |

Quick Start

``bash


Install dependencies

npm install

Build all packages

npm run build

Start the MCP server

npm run dev -w @freesail/gateway
`

Key Concepts

$3

We write the Contract (catalog.json) first:

1. Define a component in catalog.json
2. The Agent immediately sees a new tool
3. The React Developer implements the component

This ensures the Agent and UI never drift out of sync.

$3

A2UI (Agent-to-User Interface) is the JSON protocol for bi-directional communication:

Server → Client (SSE)
- createSurface - Initialize UI container
- updateComponents - Stream UI components
- updateDataModel - Push data updates
- deleteSurface - Remove a surface

Client → Server (HTTP POST)
- action - Report user interactions
- error` - Report validation or runtime errors

Documentation

- Freesail Architecture
- A2UI Protocol
- Agents

License

MIT