# Core Components of Agent‑Native: A Complete Architecture Guide

> Explore the four core components of Agent Native architecture: Actions, Agent Runtime, SQL persistence, and a React frontend. Unify AI agents with full-stack apps seamlessly.

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

---

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

```typescript
// 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`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/workspace-files/tool.ts), stores large intermediate data as resources scoped to users or organizations.

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

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

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

```

*Implementation details in [`packages/skills/src/install.ts`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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.