---
title: "FAQ"
description: "Common questions about agent-native — what it is, who it's for, what you can build, and how it works."
---

# FAQ

Common questions about agent-native, organized from "I'm just looking" to "I'm wiring up auth right now."

## The basics {#general}

### What is agent-native? {#what-is-agent-native}

Agent-native is a framework for building apps where the AI agent and the product surface around it are equal partners. The usual path starts with chat, adds typed actions, renders structured results inline, and grows into durable pages around the same SQL state. The invariant is that agents and humans share the same actions, database, and state. See [What Is Agent-Native?](/docs/what-is-agent-native) for the full explanation.

### Who is this for? {#who-is-this-for}

Agent-native is for people who want a real app and an AI agent to work from the same data and actions. The common paths are:

- **Use a hosted app** if you want Mail, Calendar, Forms, Plan, or another finished template with no setup — start at the [template gallery](/templates).
- **Start with Chat** if you want the default from-scratch path: users can talk to the agent immediately, then you extend with actions, native results, and screens — start with [Getting Started](/docs/getting-started) or [Chat](/docs/template-chat).
- **Start automation-first** if you are building scheduled jobs, queues, scripts, integration workers, or external-agent workflows with no browser UI yet — start with [Automation-First Apps](/docs/pure-agent-apps).
- **Start from a template and customize it** if you want your own SaaS product with auth, database, UI, and agent actions already wired — see [Templates](/docs/cloneable-saas).
- **Build from scratch** if you want the framework primitives for a new agent-driven product — start with [Getting Started](/docs/getting-started).
- **Connect another agent or code tool** if you want Claude, ChatGPT, Codex, Cursor, or GitHub Copilot / VS Code to use an agent-native app — see [External Agents](/docs/external-agents) and [Skills Guide](/docs/skills-guide).

### How is this different from adding AI to an existing app? {#how-is-this-different}

Most apps bolt AI on as an afterthought that can't actually _do_ things in the app. In an agent-native app the agent is a first-class citizen that shares the same actions, database, and state as the UI, so it can do anything the buttons can — and modify the app's own code. See [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder).

<Diagram id="doc-block-1s6b04" title="Bolted-on AI vs. agent-native" summary="A bolted-on chat sidebar lives in its own world. An agent-native agent shares the same actions, database, and state as the UI.">

```html
<div class="diagram-vs">
  <div class="diagram-col">
    <span class="diagram-pill warn">Bolted-on AI</span>
    <div class="diagram-node">Chat sidebar</div>
    <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
    <div class="diagram-box" data-rough>
      separate AI world<br /><small class="diagram-muted"
        >can't touch the app</small
      >
    </div>
    <div class="diagram-box diagram-muted">App UI &amp; data</div>
  </div>
  <div class="diagram-divider" aria-hidden="true"></div>
  <div class="diagram-col">
    <span class="diagram-pill ok">Agent-native</span>
    <div class="diagram-row2">
      <div class="diagram-node">UI</div>
      <div class="diagram-node">Agent</div>
    </div>
    <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
    <div class="diagram-box" data-rough>shared actions, DB &amp; state</div>
  </div>
</div>
```

```css
.diagram-vs {
  display: flex;
  align-items: stretch;
  gap: 18px;
  flex-wrap: wrap;
}
.diagram-vs .diagram-col {
  display: flex;
  flex-direction: column;
  gap: 8px;
  align-items: center;
  flex: 1;
  min-width: 200px;
}
.diagram-vs .diagram-row2 {
  display: flex;
  gap: 8px;
}
.diagram-vs .diagram-arrow {
  font-size: 20px;
  line-height: 1;
}
.diagram-vs .diagram-divider {
  width: 1px;
  align-self: stretch;
  background: currentColor;
  opacity: 0.15;
}
```

</Diagram>

### Is it open source? {#is-this-open-source}

Yes. The framework and all templates are open source. You can run everything locally, self-host, or use Builder.io's cloud for managed hosting, collaboration, and team features.

### How much does it cost? {#how-much}

The framework itself is free. The two costs you'll see in practice:

- **AI usage.** You bring your own API key (Anthropic, OpenAI, etc.) and pay the model provider directly. There's no markup from us.
- **Hosting.** Whatever your host charges. Most templates run fine on free tiers (Netlify, Vercel, Cloudflare) for small workloads.

If you'd rather not manage any of this, the hosted version on `agent-native.com` (operated by Builder.io) bundles inference and hosting into a per-seat plan.

### Can I host this myself? {#can-i-self-host}

Yes. Pick any host that runs Node — Netlify, Vercel, Cloudflare, AWS, Deno Deploy, your own server — and any SQL database (Postgres, SQLite, Turso, D1). The framework is built to be portable. See [Deployment](/docs/deployment).

### What AI models does it support? {#what-models}

Anthropic Claude, OpenAI (GPT-5 family), Google Gemini, and any provider that speaks the OpenAI API shape. For OpenAI-compatible gateways like LiteLLM, choose OpenAI in Settings and add the gateway URL under Advanced. You configure the model in settings; switching is a config change, not a code rewrite. The framework's heaviest tested path is Claude, so that's the default recommendation.

### Do I need to know AI/ML? {#do-i-need-to-know-ai}

No. You don't train models, fine-tune, or deal with embeddings. You build a regular web app — and on the hosted version, you barely build anything at all. The framework handles the agent integration: routing messages, running actions, syncing state.

### Can I migrate an existing app to agent-native? {#can-i-use-existing-code}

You can, but agent-native works best when built from the ground up. The architecture — shared database, polling sync, actions, application state — needs to be integrated throughout. Starting from an app and customizing it is the recommended path. Think of it like the shift from desktop-first to mobile-first: you _can_ retrofit, but building native is better.

## Templates and what you can build {#templates}

### What templates are available? {#what-templates-are-available}

The framework ships with production-ready templates including [Chat](/docs/template-chat), [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Plan](/docs/template-plan) (visual plans and PR recaps), [Analytics](/docs/template-analytics), [Dispatch](/docs/template-dispatch), and more. Each is a complete app with UI, agent actions, database schema, and AI instructions ready to go. See [Templates](/docs/cloneable-saas) for the full catalog.

### Can I customize templates? {#can-i-customize-templates}

That's the whole point. Start from a template and customize it by asking the agent. "Add a priority field to forms." "Connect to our Salesforce instance." "Change the color scheme to match our brand." The agent modifies the code, and your app evolves over time.

### Can I build something the templates don't cover? {#build-from-scratch}

Yes. If you want a basic agentic app, run `npx @agent-native/core@latest create my-chat-app --template chat`; you get durable chat threads, actions, auth, SQL-backed runtime state, native inline result rendering, and room to add your own screens. If you are building a no-browser automation, run `npx @agent-native/core@latest create my-agent --headless`. See [Getting Started](/docs/getting-started), [Automation-First Apps](/docs/pure-agent-apps), and [Chat](/docs/template-chat).

### Can I try it without starting from a template? {#try-with-a-skill}

Yes — install a skill into a coding agent you already use with one command and no scaffold required. See the [Skills Guide](/docs/skills-guide#app-backed-skills) for the walkthrough.

## Agent capabilities {#agent-capabilities}

### Can the agent really modify the app's own code? {#can-the-agent-modify-code}

Yes, and it's a feature. The agent can safely edit components, routes, styles, and actions. You ask "add a cohort analysis chart" and the agent builds it. You ask "connect to our Stripe account" and the agent writes the integration. Everything is normal Git-tracked code, so bad changes are easy to revert.

### Can users talk to the agent from outside the app? {#external-channels}

Yes. The same agent runs in your web UI, in Slack, in Telegram, over email, and from other agents (via [A2A](/docs/a2a-protocol)). It's the same agent with the same memory and the same actions, just reached through different channels. See [Messaging the agent](/docs/messaging).

### Can agents talk to each other? {#can-agents-talk-to-each-other}

Yes, via the [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol). Every agent-native app automatically gets an A2A endpoint. From the mail app, you can tag the analytics agent to query data. An agent discovers what other agents are available, calls them over the protocol, and shows results in the UI. No configuration needed — the agent card is auto-generated from your template's actions.

### What can the agent see in the app? {#what-can-the-agent-see}

The agent always knows what the user is currently viewing. The UI writes navigation state to the database on every route change — which view is open, which item is selected. The agent reads this before taking action. If an email is open, the agent knows which email. If a slide is selected, the agent knows which slide. See [Context Awareness](/docs/context-awareness).

## Development questions {#development}

### Which AI coding tools work with agent-native? {#which-ai-tools-work}

Any AI coding tool that reads project instructions. The framework uses AGENTS.md as the universal standard:

- **Claude Code** — reads CLAUDE.md (symlinked from AGENTS.md by the CLI setup)
- **Cursor** — reads AGENTS.md directly, or `.cursorrules` (Cursor's legacy location) if present in your project
- **Windsurf** — reads AGENTS.md directly, or `.windsurfrules` (Windsurf's legacy location) if present in your project
- **Codex, Gemini, and others** — work via the embedded agent panel
- **Builder.io** — cloud-hosted agent with visual editing and collaboration

### Can I use my own database? {#can-i-use-my-own-database}

Yes. Set `DATABASE_URL` and the framework auto-detects it. Supported databases include SQLite, Postgres (Neon, Supabase, plain), Turso (libSQL), and Cloudflare D1. All SQL is dialect-agnostic via Drizzle ORM — the same code works everywhere.

### Where can I deploy? {#where-can-i-deploy}

Anywhere. The server runs on Nitro, which compiles to any deployment target: Node.js, Cloudflare Workers/Pages, Netlify, Vercel, Deno Deploy, AWS Lambda, and Bun. You can also use Builder.io's hosting for managed deployments. See the [Deployment guide](/docs/deployment).

## Architecture {#architecture}

### Why SSE plus polling instead of WebSockets? {#why-polling-not-websockets}

SSE gives same-process writes an immediate path to the browser, and a lightweight version-counter poll remains the fallback because it works in every deployment environment — including serverless and edge, where persistent sockets may not be available. See [Key Concepts — Live sync](/docs/key-concepts#polling-sync).

<Diagram id="doc-block-1et8179" title="SSE first, polling fallback" summary={"Same-process writes stream instantly; a version-counter poll keeps serverless, edge, and cross-process writes convergent."}>

```html
<div class="diagram-transport">
  <div class="diagram-box" data-rough>DB write</div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
  <div class="diagram-col">
    <div class="diagram-node">
      SSE<br /><small class="diagram-muted"
        >/_agent-native/events &middot; instant</small
      >
    </div>
    <div class="diagram-node">
      Poll<br /><small class="diagram-muted"
        >/_agent-native/poll &middot; universal fallback</small
      >
    </div>
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
  <div class="diagram-box" data-rough>Browser refetch</div>
</div>
```

```css
.diagram-transport {
  display: flex;
  align-items: center;
  gap: 12px;
  flex-wrap: wrap;
}
.diagram-transport .diagram-col {
  display: flex;
  flex-direction: column;
  gap: 8px;
}
.diagram-transport .diagram-arrow {
  font-size: 22px;
  line-height: 1;
}
```

</Diagram>

### Why can't the UI call an LLM directly? {#why-no-inline-llm-calls}

AI is non-deterministic, so you need conversation flow to give feedback and iterate — not one-shot buttons — and the agent already has your codebase, instructions, skills, and history that an inline call lacks. Routing everything through the agent is also what lets the app be driven from Slack, Telegram, or another agent. See [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge).

### How do I upgrade an older Agent Native app? {#upgrade-older-app}

Run the supported upgrade path from the app or workspace root:

```bash
npx @agent-native/core@latest upgrade
```

That bumps `@agent-native/*` dependencies to `latest`, installs, refreshes
scaffold skills (`skills update scaffold --project`), and runs typecheck when
available. Use `upgrade check` first if you want a doctor-only report of
framework overrides/patches and pending bumps.

Do **not** fix a broken upgrade with `pnpm.overrides`, `patchedDependencies`,
or edits under `node_modules/@agent-native/*` (especially core/dispatch). If
upgrade or typecheck fails, fix app-level code or ask — then re-run upgrade.

### Why is this a framework and not a library? {#why-framework-not-library}

The shared database, live sync, actions system, and application state only work because they're wired together from the ground up — the UI reacts to agent changes instantly, agents communicate, and the agent understands what the user is looking at. A library gives you pieces; this is an architecture. See [Key Concepts](/docs/key-concepts).

## What's next

- [**Getting Started**](/docs/getting-started) — build your first action and render it inline in chat
- [**What Is Agent-Native?**](/docs/what-is-agent-native) — the full explanation behind the answers above
- [**Templates**](/docs/cloneable-saas) — start from a complete SaaS product instead of starting from scratch
- [**Key Concepts**](/docs/key-concepts) — the architecture: SQL, actions, polling sync, and portability
- [**Deployment**](/docs/deployment) — host on your own domain or any Nitro-compatible provider