BuilderIO/agent-native README.md: Framework Documentation and Architecture Guide

Yes, BuilderIO/agent-native includes a comprehensive README.md at the repository root that thoroughly explains the framework's functionality, core architectural concepts including Actions and Agent runtime, and provides quick-start instructions for building agent-native applications.

The BuilderIO/agent-native repository delivers a framework for building agent-native applications where agents operate as first-class citizens rather than side-by-side chatbots. The project's README.md serves as the primary documentation entry point, detailing how the framework unifies UI, agents, and backend logic through shared Actions and real-time synchronization.

What Is Agent-Native?

According to the BuilderIO/agent-native source code, the framework is described as "the framework for agent-native apps" in the opening lines of README.md L1-L5. It enables agents to be first-class citizens inside real applications rather than isolated chatbots.

The README outlines three core pillars:

• Actions — Single, declarative units of work invocable from UI, agents, HTTP, MCP, A2A, or CLI
• Agent runtime — Bundles chat, tools, skills, memory, jobs, observability, and hand-offs into a unified runtime
• Backend-agnostic — Works with any Drizzle-compatible SQL database and any Nitro-compatible host

Architectural Pillars Detailed in the README

The BuilderIO/agent-native README.md explains several key architectural concepts that define the framework's approach.

Shared Actions

By defining work once as Actions, all participants—including human UI, agents, and APIs—share the same implementation. This guarantees consistent behavior and reduces code duplication across the stack L20-L22.

Real-Time Synchronization

The framework uses a single database to power state for both agents and UI, enabling instant bi-directional updates. This architecture eliminates the impedance mismatch between agent operations and user interface state L9-L13.

Templates and Clone-Ready Examples

The README showcases a catalog of fully-featured SaaS-style templates including Clips, Plans, Design, Content, Slides, and Analytics. Unlike traditional scaffolding, these templates are clone-able starting points, each with dedicated documentation and preview images L24-L99.

Skills and Extensibility

The framework supports skills that extend agent capabilities via simple CLI commands. For example, installing the visual-plan skill adds slash-commands (/visual-plan, /visual-recap) for planning and PR recap functionality L15-L29.

Quick Start Instructions

The BuilderIO/agent-native README.md provides a frictionless onboarding path through a single command:

npx @agent-native/core@latest create my-app

This one-liner guides developers through template selection, chat-only mode, or headless action-first mode L32-L49.

Code Examples from the README

The documentation includes practical snippets demonstrating the framework's API surface.

Defining a Simple Action

As shown on lines 7-18 of the README, Actions use a declarative API with Zod schema validation:

// src/actions/send-reply.ts
import { defineAction } from "@agent-native/core";
import { z } from "zod";
import { db, replies } from "@/server/db";

export default defineAction({
  schema: z.object({
    emailId: z.string(),
    body: z.string(),
  }),
  run: async ({ emailId, body }) => {
    // Persist the reply – the same action can be called from UI, agent, or CLI
    await db.insert(replies).values({ emailId, body });
  },
});

Invoking Actions from UI Components

The same Action runs when triggered from React components using the useActionMutation hook:

import { useActionMutation } from "@agent-native/react";
import sendReply from "@/actions/send-reply";

export function ReplyForm() {
  const { mutate, isLoading } = useActionMutation(sendReply);
  
  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    const form = e.currentTarget as HTMLFormElement;
    const emailId = form.emailId.value;
    const body = form.body.value;
    mutate({ emailId, body });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="emailId" placeholder="Email ID" required />
      <textarea name="body" placeholder="Your reply" required />
      <button type="submit" disabled={isLoading}>Send</button>
    </form>
  );
}

Triggering Actions from Agents

The agent-native paradigm allows agents to invoke the same Actions through natural language prompts:

import { askAgent } from "@agent-native/agent";

await askAgent(`
  Please send a reply to email 12345 with the message:
  "Thanks for reaching out! We'll get back shortly."
`);

Installing Skills via CLI

Extend functionality by adding skills through the command line:

# Run in a terminal inside the project

npx @agent-native/core@latest skills add visual-plan

After installation, the visual-plan and visual-recap slash-commands become available in supported editors.

Additional Documentation Files

Beyond the root README, the repository contains specialized documentation:

File	Description	Location
README.md (root)	High-level overview, architecture summary, and quick-start guide	View
packages/core/README.md	Core runtime details, Action API, and agent-runtime plumbing	View
packages/skills/README.md	Built-in and community skills catalog	View
templates/*/README.md	Individual template documentation for each SaaS starter	View

Summary

• BuilderIO/agent-native includes a comprehensive README.md at the repository root explaining all core functionality
• The documentation details the Actions architecture that unifies UI, agent, and API execution paths
• Real-time synchronization between agents and UI is achieved through a shared database architecture
• The README provides clone-ready templates for rapid application development
• Skills extend agent capabilities via CLI installation
• Quick-start instructions use npx @agent-native/core@latest create for immediate project setup

Frequently Asked Questions

Where is the main README.md located in BuilderIO/agent-native?

The primary README.md resides at the repository root (/README.md). This file contains the framework's mission statement, architectural overview, and quick-start instructions L1-L5.

What templates are available in Agent-Native?

The README documents six fully-featured SaaS templates: Clips, Plans, Design, Content, Slides, and Analytics. Each template represents a complete, clone-able application rather than a minimal scaffold, providing production-ready starting points for various use cases L24-L99.

How do I install skills in Agent-Native?

Install skills using the CLI command npx @agent-native/core@latest skills add [skill-name]. For example, adding visual-plan enables /visual-plan and /visual-recap slash-commands in your development environment, extending your agent's planning and code review capabilities L15-L29.

Is Agent-Native backend-agnostic?

Yes. According to the README, the framework works with any Drizzle-compatible SQL database and any Nitro-compatible host. This backend-agnostic design keeps the data layer interchangeable while maintaining the same Action definitions across different deployment targets.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}