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

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, 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 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, 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, 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 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, each action automatically becomes available to the React UI, LLM agent, CLI, and external MCP clients.

// 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 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 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 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 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.
• 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.

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, 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, actions can be invoked via the CLI (packages/core/src/cli/action.ts), HTTP endpoints (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.

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