# What Is the Underlying Technology of Agent-Native? A Full-Stack TypeScript Framework Explained

> Discover the underlying technology of Agent-Native a full-stack TypeScript framework. Explore Node.js Hono Drizzle ORM libSQL and React for self-hosted agent loops with type-safe actions.

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

---

**Agent-Native is a full-stack TypeScript framework built on Node.js 22+, using Hono for the HTTP runtime, Drizzle ORM with libSQL for data, and React 18 with Vite for the UI, enabling self-hosting agent loops with type-safe actions.**

Agent-Native, developed by BuilderIO, is an open-source framework that couples a React frontend with a self-hosting agent runtime. The underlying technology of Agent-Native combines modern TypeScript tooling—including Hono, Drizzle ORM, and Standard-Schema validation—to create a unified surface for UI, LLM agents, and CLI interactions. Every action defined in the system is automatically exposed via HTTP, MCP, A2A bridges, and React hooks, with multi-tenant scoping enforced at the query-builder level.

## Core Technology Stack of Agent-Native

The framework follows a four-area architecture (actions, state, UI, and skills) built on a strictly typed foundation.

### Runtime Layer: Node.js 22+ and Hono

The **Agent-Native runtime** requires Node.js version 22 or later with ESM support. At its core, the framework uses **Hono**, a lightweight HTTP router, to serve Nitro-style API endpoints and handle static assets. In [`packages/core/src/mcp/server.spec.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/mcp/server.spec.ts), the server imports `@hono/node-server` to create the HTTP instance that mounts all `_agent-native/*` routes. This Hono instance manages the agent-tool loops, MCP/A2A bridges, and real-time polling endpoints.

### Data Layer: Drizzle ORM and libSQL

For database operations, Agent-Native relies on **Drizzle ORM** paired with **libSQL** (or any Drizzle-supported database). The [`packages/core/src/action.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/action.ts) file demonstrates how the framework uses `drizzle-orm` for typed SQL queries and schema-driven migrations. All queries are scoped per-user or per-organization through helper functions defined in [`packages/core/src/sharing/access.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/sharing/access.ts), which enforce access filters at the query-builder level rather than through raw SQL strings.

### Schema Validation: Standard-Schema

Action inputs and outputs are validated using **Standard-Schema**, a universal adapter that supports Zod, Valibot, and ArkType. When you call `defineAction` in [`packages/core/src/action.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/action.ts), the framework compiles your schema to JSON-Schema for LLM tool definitions via `schemaToJsonSchema`. The system then wraps the `run` function with `wrapWithValidation` and `wrapWithOutputValidation` to ensure type safety at both compile-time and runtime.

### Frontend: React 18 and Vite

The UI layer uses **React 18** bundled with **Vite** for fast development and production builds. Components leverage **shadcn/ui** primitives for styling, while data synchronization happens through a polling mechanism at `/_agent-native/poll`. The [`packages/core/src/react/useActionMutation.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/react/useActionMutation.ts) file exports React hooks that bridge the frontend to the action runtime with optimistic UI updates.

## How Agent-Native Actions Work Under the Hood

Actions are the universal interface in Agent-Native. Defined via the `defineAction` function in [`packages/core/src/action.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/action.ts), each action automatically becomes available to the React UI, LLM agent, CLI, and external MCP clients.

```typescript
// src/actions/send-email.ts
import { defineAction } from "@agent-native/core";
import { z } from "zod";

export default defineAction({
  description: "Send an email",
  schema: z.object({
    emailId: z.string().describe("Recipient identifier"),
    body: z.string().describe("Email body"),
  }),
  // Runs from UI, agent tool calls, HTTP POST, CLI, or MCP
  run: async ({ emailId, body }) => {
    await db.insert(replies).values({ emailId, body });
    return { ok: true };
  },
});

```

Because `agentTool` defaults to `true`, the action appears automatically in the LLM agent's tool list. The schema is converted to JSON-Schema for Claude tool definitions, and the `run` function is wrapped with input and output validators before execution.

## Real-Time Sync and the Agent Loop

The server initialization in [`packages/core/src/server/create-server.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/create-server.ts) creates a Hono instance that mounts Nitro routes under `/_agent-native/*`. Each incoming request triggers the **agent loop**, which:

1. Decodes the action call from HTTP, UI, or tool invocations
2. Executes the action with an `ActionRunContext` containing `send` (SSE), `userEmail`, `orgId`, `signal`, and attachments
3. Emits change events (unless `readOnly`) to trigger automatic UI refetches via `useDbSync()`

The `ActionRunContext` interface defined in [`packages/core/src/action.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/action.ts) provides the runtime context for all action executions, enabling real-time synchronization between the agent and the frontend.

## Multi-Tenant Data Safety

All database queries flow through Drizzle helpers (`db.select`, `db.insert`, etc.) with automatic access filtering. The [`packages/core/src/sharing/access.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/sharing/access.ts) file exports `ownableColumns()` and `resolveAccess` functions that inject user and organization scoping into every query. This ensures actions can only read or write rows belonging to the current `userEmail`/`orgId` context, enforced at the ORM level rather than application logic.

## Extensibility via the Skill System

Agent-Native supports **Skills**, which are Markdown-driven declarations stored in `.agents/skills/`. When a skill is added, the agent can:

- **Read** the skill description at runtime via `readSkill`
- **Modify** source files to enable self-modifying code capabilities
- **Launch** background jobs through the integrated `jobs` system

This architecture allows the LLM to add features, fix bugs, or generate new UI components without human intervention or separate repository management.

## Summary

- **Agent-Native** combines **Node.js 22+**, **Hono**, **Drizzle ORM**, and **React 18** into a unified TypeScript framework.
- Actions defined with `defineAction` in [`packages/core/src/action.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/action.ts) are automatically exposed via HTTP, CLI, React hooks, and MCP protocols.
- **Standard-Schema** validation (Zod/Valibot/ArkType) ensures type safety across UI, agent, and API boundaries.
- Multi-tenant data scoping is enforced at the query-builder level in [`packages/core/src/sharing/access.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/sharing/access.ts).
- The **Skill** system (`.agents/skills/`) enables declarative, self-modifying agent capabilities.

## Frequently Asked Questions

### What database does Agent-Native use?

Agent-Native uses **Drizzle ORM** with **libSQL** as the default database, though it supports any Drizzle-compatible database. The framework handles schema migrations and typed queries through `drizzle-orm`, with automatic multi-tenant scoping enforced via access filters in [`packages/core/src/sharing/access.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/sharing/access.ts).

### How does Agent-Native handle validation?

The framework implements **Standard-Schema**, a universal validation adapter that works with Zod, Valibot, and ArkType. When you define an action in [`packages/core/src/action.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/action.ts), the schema is compiled to JSON-Schema for LLM tool definitions and wrapped with `wrapWithValidation` to ensure runtime type safety for all inputs and outputs.

### Can Agent-Native run without React?

Yes, the core framework is independent of React. While the repository includes React hooks in [`packages/core/src/react/useActionMutation.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/react/useActionMutation.ts), actions can be invoked via the CLI ([`packages/core/src/cli/action.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/cli/action.ts)), HTTP endpoints ([`packages/core/src/server/action-routes.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/action-routes.ts)), or MCP/A2A clients without any UI layer.

### What is the Skill system in Agent-Native?

**Skills** are Markdown files stored in `.agents/skills/` that enable the agent to read documentation, modify source code, and launch background jobs. This system allows the agent to self-modify the codebase, add features, or generate new UI components without requiring separate repositories or manual intervention.