Developer Guide

This guide covers how to build Agent-driven UI applications using the Freesail SDK. You’ll learn how to set up the architecture, run the gateway, connect agents, and build interactive UIs.

---

1. Core Concept

Freesail uses a Triangle Pattern with three independent processes:

Architecture Overview

• Agent: Decides what to show by calling MCP tools (e.g., create_surface, update_components).
• Gateway: Translates between MCP (agent-facing) and A2UI (UI-facing). Validates agent output against catalog schemas.
• Frontend: Renders A2UI JSON into React components and sends user actions back to the agent.

---

2. The Freesail Gateway

The Gateway is the central bridge between agents and frontends. It runs as a standalone Node.js process with two network-facing interfaces:

Interface	Protocol	Purpose
Agent-facing	MCP Stdio or Streamable HTTP	Exposes tools, resources, and prompts to AI agents
UI-facing	HTTP SSE + POST	Streams A2UI updates to the frontend, receives user actions

Starting the Gateway

# Decoupled mode (recommended) — agents connect via HTTP
npx tsx packages/@freesail/gateway/src/cli.ts \
  --mcp-mode http \
  --mcp-port 3000 \
  --http-port 3001

# Stdio mode — agent spawns gateway as child process
npx tsx packages/@freesail/gateway/src/cli.ts \
  --http-port 3001

CLI Options

Option	Default	Description
--mcp-mode <mode>	stdio	MCP transport: stdio (child process) or http (standalone)
--mcp-port <port>	3000	Port for MCP Streamable HTTP server (http mode only)
--mcp-host <host>	127.0.0.1	Bind address for MCP server (http mode only)
--http-port <port>	3001	Port for A2UI HTTP/SSE server
--webhook-url <url>	—	Forward UI actions to this URL via HTTP POST
--log-file <file>	—	Write logs to file (in addition to console)

Network Isolation

By default, the MCP server binds to 127.0.0.1 — only local processes can connect. The A2UI server binds to 0.0.0.0, making it accessible from browsers. This provides network-level security without requiring authentication.

How the Gateway Processes Requests

1. Agent → Gateway (MCP): Agent calls tools like create_surface or update_components. The gateway validates the call against the catalog schema and pushes the result to the appropriate frontend session via SSE.

2. Frontend → Gateway → Agent (Actions): When a user clicks a button, the frontend POSTs an action to the gateway. The gateway queues it as an MCP resource, and the agent polls for pending actions.

---

3. Setting Up the React Application

Install the SDK

npm install freesail @freesail/catalogs

Configure the FreesailProvider

The FreesailProvider manages the connection to the gateway and registers available component catalogs.

import { ReactUI } from 'freesail';
import { StandardCatalog, ChatCatalog } from '@freesail/catalogs';

const CATALOGS: ReactUI.CatalogDefinition[] = [
  StandardCatalog,
  ChatCatalog,
];

function App() {
  return (
    <ReactUI.FreesailProvider
      sseUrl="http://localhost:3001/sse"
      postUrl="http://localhost:3001/message"
      catalogDefinitions={CATALOGS}
    >
      <MainLayout />
    </ReactUI.FreesailProvider>
  );
}

Adding Surfaces

A FreesailSurface is a designated area that the AI agent can control.

import { ReactUI } from 'freesail';

function MainLayout() {
  return (
    <div className="app-container">
      {/* Client-managed surface (start with __) */}
      <aside className="sidebar">
        <ReactUI.FreesailSurface surfaceId="__chat" />
      </aside>

      {/* Agent-created surface (start with alphanumeric) */}
      <main className="content">
        <ReactUI.FreesailSurface surfaceId="workspace" />
      </main>
    </div>
  );
}

Surface Naming Rules

Type	Naming	Who creates it?	Agent permissions
Agent-managed	Alphanumeric (e.g., workspace)	Agent via create_surface	Full control
Client-managed	Starts with __ (e.g., __chat)	React app	updateDataModel only

---

4. Building the AI Agent

The agent connects to the gateway’s MCP endpoint and uses tools to drive the UI.

Connecting to the Gateway

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('http://localhost:3000/mcp')
);

const mcpClient = new Client(
  { name: 'my-agent', version: '1.0.0' },
  { capabilities: {} }
);

await mcpClient.connect(transport);

Creating a Surface

await mcpClient.callTool({
  name: 'create_surface',
  arguments: {
    surfaceId: 'workspace',
    catalogId: 'https://freesail.dev/catalogs/standard_catalog_v1.json',
    sessionId: 'session_abc123',
  },
});

Updating Components

await mcpClient.callTool({
  name: 'update_components',
  arguments: {
    surfaceId: 'workspace',
    sessionId: 'session_abc123',
    components: [
      { id: 'root', component: 'Column', children: ['greeting'] },
      { id: 'greeting', component: 'Text', text: 'Hello from the Agent!' },
    ],
  },
});

---

5. Driving Interactivity (Data Models)

Data Binding

Bind component properties to the data model for automatic UI updates:

// Agent sets up components with data bindings
await mcpClient.callTool({
  name: 'update_components',
  arguments: {
    surfaceId: 'ticker',
    sessionId,
    components: [
      {
        id: 'price',
        component: 'Text',
        text: { path: '/currentPrice' },  // Binds to data model
      },
    ],
  },
});

// Set the data model
await mcpClient.callTool({
  name: 'update_data_model',
  arguments: {
    surfaceId: 'ticker',
    sessionId,
    path: '/currentPrice',
    value: '$150.00',
  },
});

Real-Time Updates

Update data without re-sending the component tree:

await mcpClient.callTool({
  name: 'update_data_model',
  arguments: {
    surfaceId: 'ticker',
    sessionId,
    path: '/currentPrice',
    value: '$155.50',
  },
});

---

6. Handling User Actions

When a user interacts with a component, the SDK sends an Action back through the gateway:

1. UI Event: User clicks a button in the browser.
2. Action Payload: Freesail POSTs the action to the gateway with the surface’s data model.
3. Agent Processing: The agent picks up the action via MCP and responds.

{
  "version": "v0.9",
  "action": {
    "name": "submit_form",
    "surfaceId": "workspace",
    "sourceComponentId": "submit-btn",
    "context": { "formData": "..." }
  },
  "_clientDataModel": {
    "surfaceId": "workspace",
    "dataModel": { "items": [], "total": 99.99 }
  }
}

---

7. Running the Full Stack

The easiest way to run everything is with the provided script:

export GOOGLE_API_KEY=your-api-key
cd examples && bash run-all.sh

This starts three independent processes:

Process	URL	Purpose
Gateway	http://localhost:3001 (A2UI), http://127.0.0.1:3000 (MCP)	Bridge between agent and UI
Agent	http://localhost:3002	AI agent with health endpoint
UI	http://localhost:5173	Vite React dev server

---

8. Debugging

Session Identification

• The gateway assigns a sessionId to each SSE connection.
• The React SDK attaches this ID to every HTTP POST via the X-A2UI-Session header.
• The agent receives the sessionId through a synthetic __session_connected action.

If you need to access the current session ID in your React components (for example, to pass it to your own backend API or a conversational agent), you can use the useSessionId hook:

import { ReactUI } from 'freesail';

function SessionInfo() {
  const sessionId = ReactUI.useSessionId();

  if (!sessionId) return <div>Connecting to Gateway...</div>;

  return <div>Connected Session: {sessionId}</div>;
}

Common Issues

Symptom	Check
UI stuck on “Loading surface…”	Is the __chat surface being bootstrapped? Check agent logs.
Agent not receiving actions	Check the gateway logs for upstream messages. Verify X-A2UI-Session header in browser Network tab.
Components not rendering	Verify the catalogId matches a registered catalog. Check browser console for registry errors.
Components not rendering	Check if agent is passing the correct sessionid in the tool call.

---

Best Practices & Debugging

• Session Management: Each SSE connection is assigned a sessionId by the gateway. The React SDK attaches this ID to every HTTP POST request using the X-A2UI-Session header.
• useSessionId Hook: Use the useSessionId hook from the React SDK to access the current session ID directly in your components.