Agent-Native: a TypeScript framework where the agent and the UI share one action layer

What Agent-Native solves, and who it is actually for

The README frames the problem with a comparison: coding agents work with more than a text box, because their environment supplies context, tools, files, tests and previews. Knowledge work, it argues, needs the same kind of environment. A UI shows what an agent can do and gives people familiar ways to inspect, edit, approve and share its work.

So the target reader is not someone wiring up a chat completion. It is a product engineer building an application where an agent does part of the work and a person reviews or adjusts the rest. The repository ships example agents for exactly that shape: Clips for recording and understanding meetings, screens and voice notes; Design for generating and refining interactive designs; Slides for on-brand presentations; Analytics for asking questions of data and building dashboards; Calendar for scheduling; and Mail. Those are working applications, not toy demos, and they double as reference implementations.

The framework is TypeScript and React oriented. If your team writes neither, the shared-action pitch loses most of its value, because the payoff is that the same definition feeds a React hook and an agent tool.

One action definition, four surfaces: how the pieces fit together

Agent-Native is built on three shared layers. Shared actions: the agent calls each capability as a tool, and the UI calls it from code, both paths going through the same validation, permissions and implementation. Shared data: work done by the agent appears in the UI, and work done in the UI is available to the agent. Shared application state: the agent receives relevant UI state such as the current page, selected record or active view.

The README is explicit about the boundary: the agent does not click through the UI. It works through the same action layer as the UI. That single sentence is the design decision the rest of the framework follows from. An action declared in `actions/hello.ts` becomes an agent tool, a React query through `useActionQuery`, and an HTTP endpoint, and the README also lists MCP, A2A and a CLI as exposure paths. Authentication and permissions apply to both callers because there is only one implementation.

Persistence is PostgreSQL in production and PGlite for local development, on any Nitro-compatible host. The README's own summary of what you bring is blunt: your LLM, SQL database, tools and infrastructure. Agent-Native does not supply a model. That keeps it out of the model-provider business, and it also means the interesting failure modes live in your action schemas and your database, not in the framework.

Installing Agent-Native and defining your first shared action

The quick start is a single scaffold command. It creates a project named `my-agent`, uses the standalone layout and starts from the chat template.

npx @agent-native/core@latest create my-agent --standalone --template chat

The README points to the getting started guide at agent-native.com/docs/getting-started for a full introduction, so expect to read that page rather than rely on the scaffold alone. The repository is a pnpm workspace, and the root package.json exposes `pnpm install` behind a `setup` script and a `dev` script that runs `scripts/dev-lazy.ts` if you are working inside the monorepo rather than from the scaffold.

Your first real capability is an action file. The README's example creates `actions/hello.ts` with a description, a zod schema, an HTTP method and a run function.

import { defineAction } from "@agent-native/core/action";
import { z } from "zod";

export default defineAction({
  description: "Return a friendly greeting.",
  schema: z.object({
    name: z.string().default("world").describe("Name to greet"),
  }),
  http: { method: "GET" },
  run: async ({ name }) => {
    return { message: `Hello, ${name}!` };
  },
});

After that file exists, the agent receives `hello` as a tool, and React reaches the same function from code:

useActionQuery("hello", { name: "Alex" })

The thing to check first is that both paths return the same shape. If your action's zod schema rejects a value, the README's claim is that the agent path and the UI path fail identically, because they run the same validation.

Where Agent-Native is the wrong tool

The framework assumes there is a UI worth sharing state with. If your workload is a batch job, a webhook handler or a pure tool-calling loop that returns text to a terminal, the action layer is overhead: you are paying for React integration, permissions plumbing and a database you may not need. A plain model SDK with function definitions is smaller and has fewer moving parts.

The documented backend is a real constraint too. PostgreSQL in production and PGlite locally is a reasonable default, but the README does not describe a supported path for teams standardized on MySQL, SQLite in production or a document store. The same section says to bring your own SQL database, which reads as flexibility, but the included authentication, permissions and shared-data behaviour are described against that PostgreSQL backend.

Release cadence deserves a hard look. The recent releases are nightlies, with three published on 2026-09-14 and 2026-09-15 alone, all under the v0.1.150-nightly series. A version line still at 0.1.x publishing multiple nightlies per day is a project that moves fast and does not promise stability between them. The README does not document a rollback procedure or a migration path between nightly builds, so treat upgrades as something you test rather than something you assume.

How this differs from wiring an agent into an existing app

The obvious alternative is to keep your application framework and add an agent SDK beside it. In that arrangement the agent gets its own tool definitions, written for the model, while the UI keeps calling your internal service functions. The two drift. A permission check added to the service layer does not automatically apply to the tool, and a validation rule added to the tool does not reach the button.

Agent-Native inverts that. The action is the single source, and the tool definition, the HTTP route, the React hook, the MCP surface and the CLI entry are all projections of it. The cost is that you write your capabilities in the framework's shape, using `defineAction` with a zod schema, and you accept its conventions for authentication, permissions and storage. The benefit is that there is no second place for a rule to live.

A second alternative is an agent product that already has its own interface, where you configure tools and prompts rather than build screens. That gets you to a demo faster and gives you far less control over how results are inspected and approved, which is precisely the part Agent-Native is built around. If your users only ever read the agent's final answer, the second option is cheaper.

Licence, maintenance and what an upgrade costs you

The repository's root package.json declares `"license": "ISC"`, and the repository is marked private. The top-level file listing does not include a LICENSE file, so the authoritative text is not in the repository root as listed. ISC is a permissive licence in the same family as MIT, but the declaration in a package.json is not the same artifact as a licence file, and this is a point to confirm with the maintainers before you depend on it. Nothing here is legal advice.

Maintenance signals are mixed in a specific way. The last push was on 2026-09-15, and the repository is not archived, so the codebase is being touched. The release history shows nightlies, which tells you the project is iterating quickly and not cutting stable tags. There is a `.changeset/` directory at the top level, which is the standard Changesets workflow for recording version bumps, so some release discipline exists in the repository layout even though the published versions are nightly.

Upgrade cost is the practical question. With three nightlies in roughly a day, pinning a version is the only way to have a stable target. The README does not document a rollback path, and the repository does not describe a compatibility policy between nightly builds. Budget for reading the changesets and re-running your own tests, particularly the database-backed ones, since the root test script has separate fast and database test lanes and the fast lane explicitly excludes `*.db.test.ts`, `*.integration.test.ts` and `*.live.test.ts` files.

Editorial conclusion

Adopt Agent-Native if you are building an app where people inspect, approve and edit what an agent produces, and you want one action definition to serve the tool call, the HTTP route and the React hook. Do not adopt it if you only need a headless agent loop with no interface, or if you cannot run PostgreSQL in production, since the documented backend is PostgreSQL with PGlite for local development. Before committing, verify the licence, because the root package.json declares ISC while the repository has no LICENSE file listed at the top level, and check the nightly release cadence against your tolerance for upgrading.

Frequently asked questions

Official sources

1. BuilderIO/agent-native on GitHub
2. Issues
3. Project website
4. README
5. Releases