Core Components of Agent‑Native: A Complete Architecture Guide

Agent‑Native implements a four‑layer architecture that unifies autonomous AI agents with full‑stack applications through shared Actions, an Agent Runtime, SQL‑backed persistence, and a React frontend.

BuilderIO/agent-native provides a framework for building agent‑first applications where business logic serves as the single source of truth for both user interfaces and LLM agents. The core components of agent-native create a shared action surface that guarantees consistency and real‑time synchronization across the entire system. This architecture enables developers to build SaaS‑grade applications where agents and users operate on the same data layer through identical typed operations.

The Four-Layer Architecture

The foundation of Agent‑Native rests on four tightly integrated layers that bridge AI capabilities with production UI code.

Actions: The Single Source of Truth

Actions form the cornerstone of the architecture, defined using defineAction in files like templates/videos/actions/view-screen.ts. Each action creates a typed endpoint at /api/action/<name> that exposes business logic to both the frontend and the agent.

According to AGENTS.md, Actions are "the single source of truth for all business logic." They are consumed via:

• UI Hooks: useActionQuery and useActionMutation from @agent-native/core/client
• Agent Tools: Automatically registered as callable tools in the agent's runtime

// templates/videos/actions/view-screen.ts
import { defineAction } from "@agent-native/core";

export default defineAction({
  schema: z.object({
    screenId: z.string(),
  }),
  run: async ({ screenId }) => {
    // Business logic, DB access, etc.
    return await db.select().from(screens).where(eq(screens.id, screenId));
  },
});

Agent Runtime: Memory and Coordination

The Agent Runtime manages the agent's memory, skills, jobs, and observability. Located under .agents/skills/, the runtime coordinates A2A (Agent‑to‑Agent) communication, sub‑agents, and background jobs.

As implemented in the core packages, this runtime provides the infrastructure for agents to maintain state across sessions and communicate with other agents in the system.

SQL-Backed Data Layer

All persistent state lives in a Drizzle‑compatible SQL database, including application data, agent memory, and workspace files. The workspace-files tool, implemented in packages/core/src/workspace-files/tool.ts, stores large intermediate data as resources scoped to users or organizations.

await workspaceFiles.write({
  path: "scratch/q2-memos/acme.md",
  content: longMarkdown,
  contentType: "text/markdown",
});

This unified storage approach ensures that both the UI and agent read from the same source of truth, with useDbSync() enabling instant bi‑directional updates.

Frontend Integration (React + shadcn/ui)

The Frontend Layer consists of TypeScript React components built with shadcn/ui primitives and Tabler icons. Components consume actions through the @agent-native/core/client helpers:

import { useActionMutation } from "@agent-native/core/client";

export function ScreenButton({ id }: { id: string }) {
  const viewScreen = useActionMutation("view-screen");
  return (
    <button
      onClick={() => viewScreen.mutateAsync({ screenId: id })}
    >
      Open Screen
    </button>
  );
}

Source: templates/videos/app/pages/DesignSystems.tsx

Modular Package System

Agent‑Native distributes functionality across specialized packages within the packages/ directory:

• @agent-native/core: The runtime engine and client hooks
• @agent-native/dispatch: MCP (Model Context Protocol) and credential hub
• @agent-native/scheduling: Calendar and scheduling logic
• @agent-native/pinpoint: Analytics and tracking
• @agent-native/embedding: Iframe sandbox capabilities

Skills System

The Skills System provides declarative extensions via .agents/skills/* directories. Skills like /visual‑plan and /visual‑recap are versioned, composable, and can be added to any agent without code changes.

To add a skill:

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

Implementation details in packages/skills/src/install.ts

Templates

Templates are ready‑made SaaS‑grade applications (Mail, Calendar, Slides, Analytics) that demonstrate the complete stack. Each template bundles a UI, a set of actions, and a pre‑configured agent runtime, serving as reference implementations for the architecture.

How the Components Work Together

The integration flow follows a consistent pattern across all Agent‑Native applications:

1. Define an Action – export default defineAction({ … }) creates a typed endpoint at /api/action/<name>
2. Expose to UI – Hooks like useActionMutation("my-action") call the action from React components
3. Expose to Agent – The agent's tool registry automatically registers actions as LLM‑callable tools
4. Persist State – Actions read/write to the Drizzle‑backed SQL DB; large intermediate data uses the workspace‑files tool
5. Sync UI – Both sides listen to the same DB via useDbSync(), achieving instant bi‑directional updates
6. Extend via Skills – Add capabilities by dropping a skill folder into .agents/skills/; the agent instantly gains the new toolset

Summary

• Actions serve as the single source of truth, consumed by both React hooks and agent tools via defineAction
• Agent Runtime coordinates memory, skills, and A2A communication through the .agents/skills/ directory
• SQL-Backed Data Layer unifies persistence using Drizzle, with workspaceFiles.write() handling large data storage in packages/core/src/workspace-files/tool.ts
• Frontend Layer uses useActionQuery and useActionMutation from @agent-native/core/client to interact with the shared action surface
• Modular Packages separate concerns into @agent-native/core, @agent-native/dispatch, and specialized services
• Skills System enables zero‑code agent extensions through declarative skill definitions
• Templates provide production‑ready examples in the templates/ directory

Frequently Asked Questions

What makes Actions the "single source of truth" in Agent‑Native?

Actions are defined once using defineAction and exposed both as API endpoints and agent tools. This ensures that business logic executes identically whether triggered by a user clicking a button in the React UI or an LLM agent calling a tool, preventing drift between frontend and AI behavior.

How does Agent‑Native handle data persistence for large files?

The system uses a SQL‑backed data layer for all state, with the workspace-files tool in packages/core/src/workspace-files/tool.ts specifically designed to store large intermediate results (like generated markdown documents) as scoped resources within the database.

Can I add agent capabilities without modifying core code?

Yes. The Skills System allows you to extend agents by adding skill folders to .agents/skills/ or using the CLI command npx @agent-native/core@latest skills add <skill-name>. Skills are versioned and composable, requiring no changes to existing action definitions or UI code.

How do the UI and agent stay synchronized in real‑time?

Both the React frontend and the agent runtime listen to the same Drizzle‑backed database via useDbSync(). When an action modifies the database, both surfaces receive updates simultaneously, eliminating the need for manual state management between AI and UI layers.

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