Quick Start
📖 OVERVIEW
Section titled “📖 OVERVIEW”What is Freesail?
Section titled “What is Freesail?”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
Section titled “🚀 GET STARTED”Quick Start
Section titled “Quick Start”To quickly run the full example stack (Agent + Gateway + React UI):
- Map a Google Gemini API key in your environment by running
export GOOGLE\_API\_KEY=your-api-key.- Execute the provided script from the project root using
bash ./Example-Typescript/run-all.shThis script automatically builds all packages and launches the Gateway, Agent, and React UI as three independent processes.
🏗️ ARCHITECTURE
Section titled “🏗️ ARCHITECTURE”The Triangle Pattern
Section titled “The Triangle Pattern”Freesail operates on a three-node architecture that successfully separates control logic from data 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 instead of raw React code.
- Freesail Gateway (Bridge): A Node.js 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 retries automatically if the network drops.
🧠 CONCEPTS
Section titled “🧠 CONCEPTS”Schema-First Development
Section titled “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
Section titled “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.
Stateless Agent / Stateful Client
Section titled “Stateless Agent / Stateful Client”- The AI Agent operates without remembering the history of every UI update.
- The Client maintains the “Truth” by storing the Data Model.
- Upon user actions, the Client transmits the full relevant context back to the Agent.
🛠️ HOW-TO
Section titled “🛠️ HOW-TO”1. Setting Up the Gateway
Section titled “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.
2. Setting Up the React Application
Section titled “2. Setting Up the React Application”- Install the required packages by running npm install freesail @freesail/catalogs.
- Utilize FreesailProvider to manage the gateway connection and register component catalogs via the catalogDefinitions prop.
- Create designated control areas using FreesailSurface.
3. Creating Custom Catalogs
Section titled “3. Creating Custom Catalogs”You can extend the UI vocabulary by bundling a custom catalog:
- Define the component schemas, detailing properties and children, inside a catalog.json file.
- Build standard React components that implement FreesailComponentProps.
- Bundle the catalog into a single CatalogDefinition object exporting the namespace, schema, and components map.
- Supply this definition directly to the FreesailProvider.
4. Building the AI Agent
Section titled “4. Building the AI Agent”- Connect the agent to the gateway’s MCP endpoint using StreamableHTTPClientTransport.
- The agent lists resources and subscribes to notifications from the gateway.
- 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.
- Gateway streams the A2UI messages for rendering components, to the UI.
📚 NODE PACKAGES
Section titled “📚 NODE PACKAGES”Packages Directory
Section titled “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/catalogs: Official UI catalog schemas and type definitions.