Quick Start

Freesail is an Agent-driven UI SDK that enables AI Agents to drive user interfaces. Freesail allows agents to render interfaces remotely by streaming UI to supported clients via the A2UI Protocol, without generating framework-specific code or raw HTML.

🚀 GET STARTED

To quickly run the full example stack (Agent + Gateway + React UI):

1. Download the quickstart repository from Github.
2. Create a .env file in the project working directory by copying the .env.example file. The quickstart example supports Gemini (default), OpenAI, and Anthropic Claude. Set LLM_PROVIDER and the corresponding API key in .env.
3. Execute the provided script from the project root:

bash ./run-all.sh

This script automatically builds all packages and launches the Gateway, Agent, and React UI as three independent processes.

You can access the React app at the default url http://localhost:5173. Chat with the agent and ask it to perform various activities. The example agent has no connectivity to any other API other than the LLM and gateway. Feel free to customize the agent.

🏗️ ARCHITECTURE

The Three Nodes of Freesail

Freesail operates on a three-node architecture that separates agent logic from A2UI message streaming:

• Agent (Orchestrator): The intelligence layer (e.g., LangChain) decides what to show using MCP tools. It connects to the Gateway via MCP Streamable HTTP transport and generates structured JSON data, guided by the Gateway.
• Freesail Gateway (Bridge): A server acting as the translation engine that streams A2UI messages to the Frontend via Server-Sent Events (SSE). It also injects catalog definitions into the Agent’s system prompt and validates tool calls against the catalog schema.
• Frontend (Renderer): The presentation layer (e.g., React) translates incoming A2UI messages into dynamic UI statefully. It maintains the local Data Model, handles user interactions, and sends response back to the agent via the Gateway.

🧠 CONCEPTS

Schema-First Development

Freesail enforces a “Headless & Contract-First” philosophy.

• You must define a component’s schema in a catalog.json contract first.
• The UI Developer builds the React component and registers the catalog, making the component available to the Agent via tools.
• This strategy prevents the Agent from hallucinating invalid components and ensures the UI and Agent do not drift out of sync.

A2UI Protocol

The Agent-to-User Interface (A2UI) is a JSON protocol managing bi-directional communication.

• Server → Client: Uses SSE for messages like createSurface, updateComponents, updateDataModel, and deleteSurface.
• Client → Server: Uses HTTP POST for messages like action to report interactions and error to report runtime or validation errors.

Bi-directional State Sync

• The Client owns the state and the data model.
• Upon user actions, the Client transmits the full relevant context back to the Agent.
• The AI Agent takes further action, updates the UI components or the data model.

🛠️ HOW-TO

1. Setting Up the Gateway

The Gateway runs as a standalone Node.js process exposing two interfaces:

• Agent-facing: MCP Streamable HTTP binding by default to 127.0.0.1 on Port 3000.
• UI-facing: HTTP SSE + POST binding to 0.0.0.0 on Port 3001.

Start the gateway using the Freesail CLI:

npx freesail run gateway

Configuration can be supplied via CLI flags or a freesail.config.json file. See the Gateway CLI reference for all options.

2. Setting Up the React Application

• Install the required packages:

npm install freesail @freesail/standard-catalog @freesail/chat-catalog

• Use FreesailProvider with a single gateway URL to manage the connection and register component catalogs via the catalogs prop.
• Create designated rendering areas using FreesailSurface.

3. Creating Custom Catalogs

You can extend the UI vocabulary by bundling a custom catalog:

1. Scaffold a new catalog with npx freesail new catalog.
2. Declare which components and functions to import from existing packages in catalog.include.json, then run npx freesail include catalog --package @freesail/standard-catalog.
3. Define additional component schemas in components.json and implement them in components.tsx.
4. Run npx freesail prepare catalog to merge schemas and generate the resolved catalog JSON.
5. Pass the resulting CatalogDefinition to FreesailProvider via catalogs.

4. Building the AI Agent

• Connect the agent to the gateway’s MCP endpoint using StreamableHTTPClientTransport.
• Use FreesailAgentRuntime from @freesail/agent-runtime to manage session lifecycle and action routing.
• The agent invokes tools like create_surface and update_components to direct the UI.
• Bind component properties to the data model using path variables and update them using update_data_model.
• The Gateway streams A2UI messages to the UI for rendering.

📚 NODE PACKAGES

Packages Directory

• @freesail/core: Pure TypeScript logic handling protocol definitions, parser, and transport.
• @freesail/react: React implementation of the Renderer.
• @freesail/gateway: Node.js MCP bridge server.
• @freesail/standard-catalog: Standard UI catalog (components and functions).
• @freesail/chat-catalog: Chat UI components for agent-driven chat surfaces.
• @freesail/agent-runtime: Runtime library for building Freesail agents.

Refer the Developer Guide for detailed guidance.