# Agent-Native (Builder.io) Agent-Native is a framework for building applications that are an app *and* an agent, from Builder.io. [[MIT License]], [[TypeScript]], [[React]]. Its pitch: *"Don't pick between apps or agents. Agent-Native apps are both."* This is the framework. For the conceptual layer of the same name, see [[Agent-Native Product Decomposition]], which is [[Andrej Karpathy]]'s sensors/actuators/logic framing. Related ideas, different artifacts. ## The one idea: Actions Everything rests on a single primitive. You define a unit of work once: ```ts export default defineAction({ description: "Say hello from the local agent.", schema: z.object({ name: z.string().default("world") }), http: { method: "GET" }, readOnly: true, run: async ({ name }) => ({ message: `Hello, ${name}!` }), }); ``` That one declaration becomes **seven surfaces**: 1. **Agent tool** — the model sees it as JSON Schema and can call it conversationally 2. **React hooks** — `useActionMutation()` / `useActionQuery()`, fully typed 3. **Imperative client** — `callAction()` when hooks don't fit 4. **HTTP endpoint** — auto-mounted at `/_agent-native/actions/<name>` 5. **[[Model Context Protocol (MCP)|MCP]] tool** — exposed to Claude, ChatGPT and other MCP hosts 6. **A2A tool** — callable by other Agent-Native apps 7. **CLI command** — `pnpm action <name>`, for scripting One implementation, one schema, one place where the behaviour lives. The alternative, which is what everyone currently does, is writing the same operation four times: once as a route handler, once as a tool definition, once as a UI mutation, once as a script. ## Permissions, which is where it gets serious Five independent flags on each action, and they're the part that makes this look designed rather than demoed: - `agentTool: false` — hidden from the model, still callable from UI, HTTP, CLI - `toolCallable: false` — blocks extension iframe calls, for high-blast-radius operations - `publicAgent: { expose: true }` — safe reads without authentication - `needsApproval: true` — **pauses the agent loop pending human approval** - `authorize: guard` — gate-check on every caller The guard runs before input validation and applies uniformly across agent, HTTP, frontend, MCP, A2A and CLI. **There is no bypass route.** That sentence is the whole security argument, and it's only possible because there's one definition rather than six. Every mutating action is audited automatically: who, when, from which surface, which agent thread. The audit log is itself queryable through built-in actions. Run context tells the implementation who called it and how (`ctx.caller` is `"tool" | "http" | "frontend" | "cli" | "mcp" | "a2a"`), so an action can behave differently for an agent than for a human without being a different action. ## The rest of the stack - **Agent runtime**: chat, tools, skills, memory, jobs, observability and handoffs ship together - **Backend agnostic**: any [[Drizzle]]-supported SQL database, any Nitro-compatible host - **Toolkits**: reusable blocks for collaboration, sharing, settings, teams, observability ```bash npx @agent-native/core@latest create my-app ``` There's a gallery of working apps meant to be forked and evolved by an agent rather than read as demos: a Loom clone, a visual plan mode for coding agents, a Figma-like design tool, an analytics tool positioned against Amplitude and FullStory, a minimal ChatGPT-style shell, and **an Obsidian/Notion-style content app**. ## Design guidance worth stealing The docs warn against one-action-per-UI-affordance sprawl: prefer a single CRUD-style `update` with optional fields over N per-field actions, mark UI-only operations `agentTool: false` to free model context, and delete actions the UI stopped using rather than leaving them exposed. There's an advisory `pnpm actions:audit` that flags dead actions and redundant clusters. That is the same problem [[DrSkill]] scans for, one layer up: **too many near-identical capabilities is a routing failure, not just clutter.** Whether the router is a model choosing a tool or a model choosing a skill, overlapping descriptions are what break it. ## Why I keep this note **The seven-surfaces idea generalises past this framework.** Define the capability once with a schema and a guard, then project it into every consumer. That's the answer to a question I keep hitting: my vault capabilities exist as skills for an agent, and as CLI commands, and as things I do by hand, with the logic restated each time. One definition with a declared shape is strictly better, and the fact that MCP and A2A fall out for free is the point. **`needsApproval` as a first-class flag is the right primitive.** Not a wrapper you remember to add, not a convention, a property of the action itself that pauses the loop. That's the same lesson as the [[qm (Y Combinator)]] security postures and the [[Bento]] pattern of putting the constraint in the artifact: safety mechanisms belong in the definition, where they can't be forgotten. **Forkable apps that an agent evolves is a real distribution model.** Not a template you customise by hand, a working app you point an agent at. The gallery's Obsidian/Notion entry is the one I'd actually look at, though with no illusions: my vault's value is the accumulated notes and the plugin ecosystem, not the editor. The caveat: this is young, it's from a company with a product to sell, and adopting it means adopting Drizzle, Nitro, React and their action model together. The *idea* transfers to anything. The framework is a bigger commitment than the idea. ## References - [BuilderIO/agent-native](https://github.com/BuilderIO/agent-native) — source - [agent-native.com](https://agent-native.com) — docs - [Actions](https://agent-native.com/docs/actions) — the core primitive - [Agent surfaces](https://agent-native.com/docs/agent-surfaces) - [App gallery](https://agent-native.com/apps) - [Getting started](https://agent-native.com/docs/getting-started) - [Discord](https://discord.gg/qm82StQ2NC) ## Related - [[Agent-Native Product Decomposition]] - [[AI Agents]] - [[AI Agent Skills]] - [[Model Context Protocol (MCP)]] - [[DrSkill]] - [[qm (Y Combinator)]] - [[Bento]] - [[React]] - [[TypeScript]] - [[Drizzle]] - [[Obsidian]] - [[Notion]] - [[Open Source]] - [[MIT License]]