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

> Explore BuilderIO/agent-native's functionality with its comprehensive README.md. Learn about Actions, Agent runtime, and get quick-start guides for building agent-native apps.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: architecture
- Published: 2026-06-30

---

**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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/README.md) [L1-L5](https://github.com/BuilderIO/agent-native/blob/main/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](https://github.com/BuilderIO/agent-native/blob/main/README.md#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](https://github.com/BuilderIO/agent-native/blob/main/README.md#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](https://github.com/BuilderIO/agent-native/blob/main/README.md#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](https://github.com/BuilderIO/agent-native/blob/main/README.md#L15-L29).

## Quick Start Instructions

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

```bash
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](https://github.com/BuilderIO/agent-native/blob/main/README.md#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:

```typescript
// 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:

```typescript
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:

```typescript
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:

```bash

# 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`](https://github.com/BuilderIO/agent-native/blob/main/README.md)** (root) | High-level overview, architecture summary, and quick-start guide | [View](https://github.com/BuilderIO/agent-native/blob/main/README.md) |
| **[`packages/core/README.md`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/README.md)** | Core runtime details, Action API, and agent-runtime plumbing | [View](https://github.com/BuilderIO/agent-native/blob/main/packages/core/README.md) |
| **[`packages/skills/README.md`](https://github.com/BuilderIO/agent-native/blob/main/packages/skills/README.md)** | Built-in and community skills catalog | [View](https://github.com/BuilderIO/agent-native/blob/main/packages/skills/README.md) |
| **`templates/*/README.md`** | Individual template documentation for each SaaS starter | [View](https://github.com/BuilderIO/agent-native/tree/main/templates) |

## Summary

- BuilderIO/agent-native includes a comprehensive [`README.md`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/README.md) resides at the repository root ([`/README.md`](https://github.com/BuilderIO/agent-native/blob/main//README.md)). This file contains the framework's mission statement, architectural overview, and quick-start instructions [L1-L5](https://github.com/BuilderIO/agent-native/blob/main/README.md#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](https://github.com/BuilderIO/agent-native/blob/main/README.md#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](https://github.com/BuilderIO/agent-native/blob/main/README.md#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.