Why the 2.6K‑Star Agent‑Native Framework Beats Traditional Add‑on AI Solutions

Problem with Traditional Add‑on AI

Engineers often attach an AI chat box to an existing page, writing separate tool‑calling logic, UI state, Agent memory, and permission systems. Changing business logic requires updating buttons, APIs, and Agent tools three times, and the Agent can only return text, not manipulate the page or support long‑term product evolution.

Agent‑Native Overview

Agent‑Native (GitHub ★2.6k, MIT) re‑architects this pattern by treating Agent and UI as equal citizens. It unifies actions, state, and permissions, delivering a complete SaaS‑ready application.

Four Development Approaches Compared

Commercial SaaS tools : beautiful UI but not customizable.

Native LLM chat Agent : only a chat window, no business UI.

In‑house tools : built from scratch, months of work.

Agent‑Native : out‑of‑the‑box React UI, fork‑able.

Other dimensions (AI integration, customization freedom, code ownership, human‑machine collaboration) are similarly contrasted, with Agent‑Native offering native integration, full code control, and SQL‑backed state sharing.

Core Primitives

Unified Action : Define an action once with defineAction and reuse it across UI buttons, Agent tools, HTTP endpoints, MCP, A2A, CLI, and scheduled jobs. Example:

// Full‑scene generic business action
import z from "zod";
export default defineAction({
  schema: z.object({
    emailId: z.string(),
    body: z.string(),
  }),
  http: { method: "POST" },
  run: async ({ emailId, body }) => {
    await db.insert(replies).values({ emailId, body });
  },
});

The framework also defines

type ActionCaller = "tool" | "http" | "frontend" | "cli" | "mcp" | "a2a"

for permission and audit configuration.

SQL Global Shared State : Drizzle ORM supports SQLite, Postgres, Supabase, Neon. Core tables such as application_state (stores UI context) and sessions/oauth_tokens (unified auth) enable real‑time synchronization via SSE. Agents can read the current page context and write data that instantly updates the front‑end without refresh.

Built‑in Agent Runtime : Handles conversation loops, tool calls, skill system, persistent memory, async tasks, and observability. All LLM requests go through the runtime, allowing centralized prompt, permission, and retry management.

Skill System

Skills live under .agents/skills/…/SKILL.md and are loaded progressively. Only the skill name and short description reside in the system prompt; the full rule set, code examples, and constraints are fetched when the Agent matches a task. Scopes ( dev, runtime, both) control visibility.

Built‑in skills cover data storage, real‑time sync, Agent delegation, self‑modifying code, front‑end development, and permission security. App‑backed skills let the whole application be packaged as an MCP plugin for tools like Claude Code or Cursor.

Protocols

MCP (Model Context Protocol) : Exposes every Action as a standard MCP tool for third‑party Agents.

A2A (Agent‑to‑Agent) : Enables cross‑process communication between agents in the same workspace, supporting task delegation, data sharing, and team orchestration with key‑based isolation.

ACP (Agent Communication Protocol) 2026 update : Aligns with LSP, allowing Agent‑Native apps to drive local code Agents, generate visual plans, and produce visual PR reviews.

Self‑Modifying Agent

Using the self-modifying-code skill, an Agent can read and write project source files, components, or Action logic. The /visual-plan command generates a structured plan with UI sketches, architecture diagrams, and annotated code before execution; a human must approve via /visual-recap before changes are applied.

Production‑Ready Templates

Thirteen open‑source SaaS templates (e.g., Clips, Plans, Design, Content, Slides, Analytics, Mail, Calendar, Forms, Assets, Dispatch, Brain, Video) provide UI, database schema, Actions, skills, and permission systems out of the box.

Getting Started

Prerequisites: Node.js ≥20, pnpm, Anthropic Claude API key (replaceable with custom LLM).

Create a project:

npx @agent-native/core@latest create my-agent-platform
cd my-agent-platform
pnpm install
pnpm dev

Install visual‑plan skill:

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

Run Actions or Agents locally:

pnpm action reply-email --emailId xxx --body "test reply"
pnpm agent "Generate reply for email id 123"

Database migration (Drizzle): generate and verify scripts before applying.

Deploy with Nitro to Vercel, Cloudflare Workers, or self‑hosted servers:

npx @agent-native/core@latest deploy

Common Pitfalls & Mitigations

Migrating legacy projects: high refactor cost; recommend using Agent‑Native for new projects and adding an AI workbench to existing ones.

Skill cross‑model failure: isolate model‑specific skills via scope.

Real‑time sync not working: ensure useDbSync hook is used.

Self‑modifying code safety: require visual‑plan review before applying changes.

Database permission leakage: configure accessFilter for multi‑tenant isolation.

MCP/A2A auth failures: set A2A_SECRET and separate dev/production keys.

Architecture Details

Monorepo layout:

my-agent-platform/
├── packages/core        # CLI, Action, MCP/A2A core
├── packages/...         # Scheduler, migration, observability tools
├── apps/mail/slides     # Example business apps
├── packages/shared      # Shared Actions, DB models
└── .agents/skills       # Global Agent skills

Synchronization flow: Agent or front‑end writes to SQL → server emits SSE → front‑end useDbSync captures event → query cache refreshes → UI updates without flicker.

Resources

GitHub: https://github.com/BuilderIO/agent-native

Documentation: https://agent-native.com

Templates: https://agent-native.com/templates

Discord community: https://discord.gg/qm82StQ2NC