DEV Community

Terminal Chai
Terminal Chai

Posted on

Agent-Native: Builder.io's Framework for Building True Agentic Apps

#ai #opensource #programming

Over the past two years, the software industry rushed to add AI to existing applications. In 95% of cases, the implementation looked identical: an iframe or floating chat sidebar pinned to the right-hand corner of a traditional web app.

While chat sidebars are easy to bolt on, they create a fractured user experience:

  • Zero Shared Context: The user has to manually re-explain what they are viewing in the main dashboard.
  • Dual Maintenance Burden: Engineers maintain one set of REST/GraphQL endpoints for the UI, and a separate set of function-calling tools for the LLM.
  • Asynchronous Disconnect: Actions performed by the user aren't visible to the agent, and outputs generated by the agent rarely reflect immediately inside the native UI state.

To solve this architectural disconnect, Builder.io has open-sourced Agent-Native (BuilderIO/agent-native)—a full-stack TypeScript framework designed for applications where human users and AI agents collaborate as first-class citizens across the exact same action layer.

Here is an architectural deep dive into how Agent-Native works, how it bridges the UI with agent toolsets, and how to build your first agent-native application.

The Core Philosophy: The Unified Action Layer

In a traditional web application, frontend components trigger client-side functions or API calls. In an agentic system, LLMs invoke tools via JSON schema definitions.

Agent-Native merges these two paradigms into a single unified primitive: The Action.

                           ┌────────────────────────┐
                           │   defineAction(...)    │
                           │  (Zod Schema & Logic)  │
                           └───────────┬────────────┘
                                       │
         ┌──────────────────┬──────────┴──────────┬──────────────────┐
         ▼                  ▼                     ▼                  ▼
  [ React Hooks ]   [ AI Agent Tools ]     [ MCP Protocol ]   [ REST Endpoints ]
 (useActionQuery)    (Direct Invocation)   (Model Context)    (HTTP / CLI)
Enter fullscreen mode Exit fullscreen mode

Instead of defining an API endpoint and then duplicating that logic in an LLM tool prompt, you define the action once using @agent-native/core:

import { defineAction } from "@agent-native/core/action";
import { z } from "zod";

export default defineAction({
  description: "\"Update the status of a project task.\","
  schema: z.object({
    taskId: z.string().describe("The unique ID of the task"),
    status: z.enum(["todo", "in_progress", "done"]),
  }),
  http: { method: "POST" },
  run: async ({ taskId, status }, ctx) => {
    // Shared business logic, database mutation & permission checks
    const updated = await ctx.db.tasks.update(taskId, { status });
    return updated;
  },
});
Enter fullscreen mode Exit fullscreen mode

Because of this unified structure:

  1. The React UI calls it naturally via React hooks: 
   const { mutate } = useActionMutation("updateTask");
Enter fullscreen mode Exit fullscreen mode
  1. The AI Agent receives it automatically as an LLM tool with complete parameter schemas and descriptions.
  2. External Systems can trigger it through auto-generated HTTP endpoints, Model Context Protocol (MCP) servers, or terminal CLIs.

Shared State and Reactive Data

The biggest frustration with AI assistants is context-blindness. If a user is inspecting a financial report or viewing a specific kanban column, having to prompt the agent with "Look at the quarterly column" is tedious.

Agent-Native treats application state as a shared real-time ledger between the human and the agent:

  • Shared State: The agent automatically receives active UI context (current route, focused element, highlighted table row, active filter).
  • Shared Data: Mutations executed by the agent reflect immediately inside the UI without full-page reloads or manual refreshes.
  • Action-Driven, Not Pixel-Driven: Unlike fragile computer-use tools that attempt to parse screenshots and click on screen coordinates, Agent-Native agents execute typed actions directly. This delivers deterministic reliability, zero UI hijacking, and instant execution speeds.

Production Batteries Included

Beyond the action layer, Agent-Native ships with full infrastructure support out of the box:

  • PostgreSQL & PGlite: Runs lightweight PGlite embedded in local memory for development, and connects seamlessly to managed PostgreSQL (Supabase, Neon, AWS RDS) in production.
  • Autonomous Automations: Trigger agent workflows not just from manual chat prompts, but on recurring cron schedules or webhook events.
  • Agent Teams: Built-in orchestration to delegate complex workflows across multiple specialized agents in the same workspace.
  • Skills and Memory: Persistent context storage and modular skills that give agents long-term organizational knowledge.
  • Enterprise Permissions: Granular role-based access control (RBAC) ensuring agents only execute actions authorized for the active user session.

Quick Start: Creating Your First Agent-Native App

You can bootstrap a complete agent-native application using the official CLI:

npx --yes @agent-native/core@latest create my-agent --standalone --template chat
Enter fullscreen mode Exit fullscreen mode

Once generated, navigate into your directory and start the local development environment:

cd my-agent
npm run dev
Enter fullscreen mode Exit fullscreen mode

This starts a local Nitro-compatible server with embedded PGlite, auto-registers all actions inside the /actions directory, and serves an interactive collaborative UI with built-in agent chat and inspection panels.

Summary

Agent-Native represents the natural evolution of software engineering in the age of generative AI. By retiring disconnected chat bubbles and unifying the action layer across code and models, it enables developers to build applications where AI is an active, reliable collaborator.

Top comments (0)