Build on Agent-Native

---
name: Build on Agent-Native
description: "Build an application on Builder.io's open-source Agent-Native framework (@agent-native/core), where the agent acts inside the app as a peer to the UI, sharing one set of actions and one database with the interface. Covers actions as the single source of truth, SQL-backed shared state, real-time sync, context-awareness, agent-to-agent calls, automations, the skills convention, and the CLI and template workflow. Use when someone says \"build an agent-native app\", \"use the agent-native framework\", \"defineAction\", \"@agent-native/core\", \"clone an agent-native template\", \"make the agent a peer to my UI\", or \"an app where the agent and the UI call the same actions\". Do NOT use for authoring generic SKILL.md files (use skill-creator), a standalone MCP server unrelated to this framework, or plain Next.js/React scaffolding with no agent runtime."

---

# Build on Agent-Native

Agent-Native (open-source, MIT, by Builder.io - `@agent-native/core`) is a framework for apps where the agent acts **inside** the product, not in a chat box beside it. The agent and the UI are equal citizens of one system: the same action that a button calls, the agent calls as a tool, over the same database and shared state. Use this skill to build on it correctly instead of bolting a chatbot onto a normal app.

## When to reach for it

Choose Agent-Native when the agent needs to *do real work in the product* - read and mutate app data, edit the same document a human is editing, coordinate with other agents - and you want one implementation serving UI, agent, HTTP, MCP, A2A, and CLI. If you only need a chat assistant next to an otherwise-normal app, you do not need this framework; say so.

## Core primitives

**Actions are the single source of truth.** Define each operation once with `defineAction` (a Zod schema plus a `run` function). That one definition is callable from the agent as a tool, from the UI via `useActionQuery` / `useActionMutation`, and from HTTP, MCP, A2A, and the CLI (`pnpm action <name>`). Do not add `/api/*` pass-through routes whose only job is to call an action - call the action directly.

**Keep the action surface small and orthogonal.** Every agent-exposed action is a tool in the model's context window, and more tools degrade tool-selection quality - past roughly 15-20 agent-visible tools, expect noticeably worse selection, so consolidate before you get there. Prefer one patch-style `update-<thing>` over many per-field actions (an app exposing 40 per-field setters where 5 patch actions would do is the canonical smell). Hide UI-only or programmatic actions from the model with `agentTool: false` (still callable from the UI/HTTP, just not a tool the agent sees). Note that `agentTool: false` (hidden from the model entirely) is *not* `toolCallable: false` (blocks only the sandboxed extension iframe bridge) - use the latter for high-blast-radius operations, not for trimming the tool list.

**SQL-backed shared state.** Bring your own Drizzle-supported SQL database and a Nitro-compatible host. One database, one state - changes from the agent or the UI show up instantly on the other via real-time sync. This is what makes human-and-agent multiplayer editing work.

**Context-awareness.** The agent knows what the user is looking at. Surface UI state to it deliberately so "summarize *this*" and Cmd+I-style "do this to the selection" work.

**Agent-to-agent (A2A) and external agents.** Agents tag and call other agents over A2A; the framework also speaks MCP (as server and via MCP-apps). Reach for these for cross-app coordination rather than hardcoding integrations.