@agent-native/core 0.151.0 → 0.151.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/corpus/README.md +1 -1
- package/corpus/templates/slides/.agents/skills/slide-editing/SKILL.md +13 -0
- package/corpus/templates/slides/changelog/2026-08-10-asking-the-agent-for-several-slide-animations-at-once-now-ke.md +6 -0
- package/dist/collab/awareness.d.ts +2 -2
- package/dist/notifications/routes.d.ts +3 -3
- package/dist/observability/routes.d.ts +3 -3
- package/docs/content/key-concepts.mdx +141 -83
- package/package.json +1 -1
package/corpus/README.md
CHANGED
|
@@ -102,6 +102,19 @@ simulate reveals. When content and reveals change together, send both fields in
|
|
|
102
102
|
one `patch-deck` operation. To remove reveals, send `animations: []` with the
|
|
103
103
|
existing content and verify the persisted slide afterward.
|
|
104
104
|
|
|
105
|
+
Array order is reveal order, and each entry needs a non-empty `id`, a 0-based
|
|
106
|
+
`elementIndex`, and a `type` of `appear`, `fade`, `slide-up`, or `zoom`; the
|
|
107
|
+
schema rejects the operation otherwise. Nothing checks that ids are unique, but
|
|
108
|
+
the editor keys its reveal list by id, so a duplicate makes "remove" and
|
|
109
|
+
"change type" hit every entry sharing it.
|
|
110
|
+
|
|
111
|
+
`elementPath` has to come from the exact final HTML because it is positional:
|
|
112
|
+
every segment is a child index, so inserting or removing a sibling anywhere
|
|
113
|
+
along the path retargets it. The runtime resolves the path first and falls back
|
|
114
|
+
to `elementIndex` only when it fails to resolve, which is why a stale path
|
|
115
|
+
silently reveals the wrong element instead of erroring. `get-deck` with
|
|
116
|
+
`compact=true` reports each step's order, id, target, and type for verification.
|
|
117
|
+
|
|
105
118
|
If retrieval produces a new immutable context pack, keep its `contextPackId`
|
|
106
119
|
and reuse labels with the deck provenance. Existing slide HTML is not proof of
|
|
107
120
|
which source version influenced it.
|
|
@@ -62,11 +62,11 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
|
|
|
62
62
|
error: string;
|
|
63
63
|
states?: undefined;
|
|
64
64
|
} | {
|
|
65
|
-
error?: undefined;
|
|
66
65
|
states: {
|
|
67
66
|
clientId: number;
|
|
68
67
|
state: string;
|
|
69
68
|
}[];
|
|
69
|
+
error?: undefined;
|
|
70
70
|
}>>;
|
|
71
71
|
/**
|
|
72
72
|
* GET /_agent-native/collab/:docId/users
|
|
@@ -77,9 +77,9 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
|
|
|
77
77
|
error: string;
|
|
78
78
|
users?: undefined;
|
|
79
79
|
} | {
|
|
80
|
-
error?: undefined;
|
|
81
80
|
users: {
|
|
82
81
|
clientId: number;
|
|
83
82
|
lastSeen: number;
|
|
84
83
|
}[];
|
|
84
|
+
error?: undefined;
|
|
85
85
|
}>>;
|
|
@@ -13,12 +13,12 @@
|
|
|
13
13
|
export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
|
|
14
14
|
count: number;
|
|
15
15
|
updated?: undefined;
|
|
16
|
-
ok?: undefined;
|
|
17
16
|
error?: undefined;
|
|
17
|
+
ok?: undefined;
|
|
18
18
|
} | {
|
|
19
19
|
updated: number;
|
|
20
|
-
ok?: undefined;
|
|
21
20
|
error?: undefined;
|
|
21
|
+
ok?: undefined;
|
|
22
22
|
count?: undefined;
|
|
23
23
|
} | {
|
|
24
24
|
updated?: undefined;
|
|
@@ -27,7 +27,7 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
|
|
|
27
27
|
count?: undefined;
|
|
28
28
|
} | {
|
|
29
29
|
updated?: undefined;
|
|
30
|
-
ok: boolean;
|
|
31
30
|
error?: undefined;
|
|
31
|
+
ok: boolean;
|
|
32
32
|
count?: undefined;
|
|
33
33
|
}>>;
|
|
@@ -42,22 +42,22 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
|
|
|
42
42
|
avgEvalScore: number;
|
|
43
43
|
} | {
|
|
44
44
|
error?: undefined;
|
|
45
|
+
ok?: undefined;
|
|
45
46
|
summary: import("./types.js").TraceSummary;
|
|
46
47
|
spans: import("./types.js").TraceSpan[];
|
|
47
48
|
id?: undefined;
|
|
48
|
-
ok?: undefined;
|
|
49
49
|
} | {
|
|
50
50
|
error?: undefined;
|
|
51
|
+
ok?: undefined;
|
|
51
52
|
summary?: undefined;
|
|
52
53
|
spans?: undefined;
|
|
53
54
|
id: string;
|
|
54
|
-
ok?: undefined;
|
|
55
55
|
} | {
|
|
56
|
+
ok?: undefined;
|
|
56
57
|
summary?: undefined;
|
|
57
58
|
spans?: undefined;
|
|
58
59
|
id?: undefined;
|
|
59
60
|
error: any;
|
|
60
|
-
ok?: undefined;
|
|
61
61
|
} | {
|
|
62
62
|
error?: undefined;
|
|
63
63
|
summary?: undefined;
|
|
@@ -1,21 +1,21 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Key Concepts"
|
|
3
|
-
description: "How agent-native apps work across three layers: the Core framework, optional Toolkit building blocks, and optional Templates, plus the shared actions, SQL database, app-agent loop, and portability
|
|
3
|
+
description: "How agent-native apps work across three layers: the Core framework, optional Toolkit building blocks, and optional Templates, plus the shared actions, SQL database, app-agent loop, and portability rules."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Key Concepts
|
|
7
7
|
|
|
8
|
-
How agent-native apps work under the hood
|
|
8
|
+
How agent-native apps work under the hood: the principles and the architecture. This page is the contract: the fixed rules an app has to follow to count as agent-native. For the vision and the case for building this way, see [What Is Agent-Native?](/docs/what-is-agent-native).
|
|
9
9
|
|
|
10
10
|
## The three layers {#three-layers}
|
|
11
11
|
|
|
12
|
-
Agent Native is a framework
|
|
12
|
+
Agent Native is a framework with three layers:
|
|
13
13
|
|
|
14
|
-
| Layer
|
|
15
|
-
|
|
|
16
|
-
| **Core
|
|
17
|
-
| **Toolkit
|
|
18
|
-
| **Templates
|
|
14
|
+
| Layer | What it is |
|
|
15
|
+
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
16
|
+
| **Core: the framework** | The foundational runtime contract: actions, SQL and Drizzle helpers, auth, application state, agent execution, access checks, routing, and live sync. Every app can use Core directly. |
|
|
17
|
+
| **Toolkit: optional reusable pieces** | Shared app-building UI and product systems such as primitives, editors, sharing, collaboration, settings, and agent UX. Apps can use, compose, or fork the pieces they need. |
|
|
18
|
+
| **Templates: optional apps built on Core** | Complete, domain-specific apps with routes, schema, actions, instructions, and visual identity. First-party and custom templates commonly use Toolkit, and can be forked and used as starting points. |
|
|
19
19
|
|
|
20
20
|
Core is the foundation. Toolkit and Templates are optional: a template can use Toolkit, but Toolkit is not required to build an app on Core.
|
|
21
21
|
|
|
@@ -23,9 +23,11 @@ Core is the foundation. Toolkit and Templates are optional: a template can use T
|
|
|
23
23
|
|
|
24
24
|
At runtime, every agent-native app is three things working together:
|
|
25
25
|
|
|
26
|
-
- **Agent
|
|
27
|
-
- **Application
|
|
28
|
-
- **Computer
|
|
26
|
+
- **Agent:** The autonomous AI. It reads data, writes data, runs actions, and uses whatever tools are configured. When its frame is intentionally granted workspace access and write tooling, it can also modify the app's own source. Customizable with skills and instructions.
|
|
27
|
+
- **Application:** The product surface around the agent. It may start as chat, add native inline results, grow into a small control plane, or become a full React UI with dashboards, flows, and visualizations.
|
|
28
|
+
- **Computer:** The database, browser, and configured tool runtimes the agent acts through. Agents work through the app's own action and data surface; that same surface can optionally be exposed over MCP, but external MCP servers stay an add-on, not the foundation.
|
|
29
|
+
|
|
30
|
+
The diagram below shows the agent and the application side by side, both with two-way arrows into one shared computer layer underneath. Neither one owns the data. Instead, they read and write the same SQL store, so a change either side makes is visible to the other immediately, with no sync layer to build in between.
|
|
29
31
|
|
|
30
32
|
<Diagram id="doc-block-t1f7pj" title="Agent, application, and computer" summary="Three layers working together over one shared SQL store. The agent and the application both read and write the same data.">
|
|
31
33
|
|
|
@@ -88,12 +90,13 @@ At runtime, every agent-native app is three things working together:
|
|
|
88
90
|
|
|
89
91
|
</Diagram>
|
|
90
92
|
|
|
91
|
-
|
|
93
|
+
That same agent-application-computer loop is what runs locally and in production. Automation-first apps run it straight from the folder with `pnpm agent`; UI apps mount the embedded agent panel and add `pnpm dev`. In the cloud, Builder.io hosts the identical loop as a managed frame: the environment that runs the agent next to your app. It handles collaboration, visual editing, and infrastructure for you.
|
|
92
94
|
|
|
93
95
|
## Agent building blocks {#agent-building-blocks}
|
|
94
96
|
|
|
95
97
|
Every agent-native app has the same agent building blocks, regardless of whether
|
|
96
|
-
the product surface is chat-first, automation-first, or a full UI
|
|
98
|
+
the product surface is chat-first, automation-first, or a full UI. Each one lives
|
|
99
|
+
in its own file:
|
|
97
100
|
|
|
98
101
|
<FileTree
|
|
99
102
|
id="doc-block-1ae57y4"
|
|
@@ -114,11 +117,13 @@ the product surface is chat-first, automation-first, or a full UI:
|
|
|
114
117
|
]}
|
|
115
118
|
/>
|
|
116
119
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
|
120
|
-
|
|
|
121
|
-
| **
|
|
120
|
+
A turn is one exchange with the agent: it reads its context, decides what to do, and responds. Loaded every turn means the file re-enters that context each time, not just once at session start.
|
|
121
|
+
|
|
122
|
+
| Building block | File | Use it for | Loaded when |
|
|
123
|
+
| ---------------- | -------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
|
|
124
|
+
| **Instructions** | `AGENTS.md` | Stable guidance the agent should carry into every task: what the app is, invariants, tone, indexes | Every turn |
|
|
125
|
+
| **Skills** | `.agents/skills/<name>/SKILL.md` | Reusable behavior: how to follow a workflow, apply a policy, inspect evidence, or verify an output | On demand when the skill description matches the task |
|
|
126
|
+
| **Actions** | `actions/<name>.ts` | Real operations: read or write data, call APIs, send messages, run approvals, produce typed results | Listed as tools every turn; executed only when called |
|
|
122
127
|
|
|
123
128
|
Skills and actions work together. A skill teaches the agent how to do a class of
|
|
124
129
|
work; an action is the code path it can call while doing that work. For example,
|
|
@@ -128,41 +133,59 @@ and write the actual data.
|
|
|
128
133
|
|
|
129
134
|
Five rules govern the architecture:
|
|
130
135
|
|
|
131
|
-
1. **Data lives in SQL
|
|
132
|
-
2. **All AI goes through the agent
|
|
133
|
-
3. **Actions for agent operations
|
|
134
|
-
4. **Live sync keeps the UI in sync
|
|
135
|
-
5. **Application state in SQL
|
|
136
|
+
1. **Data lives in SQL:** all app state lives in the database via Drizzle ORM.
|
|
137
|
+
2. **All AI goes through the agent:** no inline LLM calls; every AI interaction flows through the agent chat bridge.
|
|
138
|
+
3. **Actions for agent operations:** complex work runs as a typed action, not inline code.
|
|
139
|
+
4. **Live sync keeps the UI in sync:** database changes stream over SSE, with polling as the universal fallback.
|
|
140
|
+
5. **Application state in SQL:** ephemeral UI state lives in the database, readable by both agent and UI.
|
|
136
141
|
|
|
137
142
|
## The four-area checklist {#four-area-checklist}
|
|
138
143
|
|
|
139
144
|
Every user-facing feature should update all applicable areas. Skipping an applicable area breaks the agent-native contract; forcing a screen onto an automation that no human needs to browse is also a smell.
|
|
140
145
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
| **3. Skills** | Update AGENTS.md and/or create a skill documenting the pattern |
|
|
146
|
-
| **4. App-State** | Navigation state, view-screen data, and navigate commands |
|
|
146
|
+
- **1. UI:** Page, component, or dialog the user interacts with.
|
|
147
|
+
- **2. Action:** Agent-callable action in `actions/` for the same operation.
|
|
148
|
+
- **3. Skills:** Update `AGENTS.md` and/or create a skill documenting the pattern.
|
|
149
|
+
- **4. App-State:** Navigation state, view-screen data, and navigate commands.
|
|
147
150
|
|
|
148
151
|
A feature with only UI is invisible to the agent. A full UI feature with only actions is invisible to the user. A feature without app-state means the agent is blind to what the user is doing. An automation-first operation can legitimately start with action + instructions and add chat, UI, or app-state later when humans need to browse, approve, configure, or share it.
|
|
149
152
|
|
|
153
|
+
## What Agent Native includes {#what-you-get-for-free}
|
|
154
|
+
|
|
155
|
+
Adopting the framework is valuable mostly because of what you stop having to build. The moment your app follows the five rules above, you inherit:
|
|
156
|
+
|
|
157
|
+
| Feature | What it gives you |
|
|
158
|
+
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
159
|
+
| One action = every surface | Every action defined with `defineAction()` is simultaneously an agent tool, a typesafe frontend hook (`useActionQuery` / `useActionMutation`), a framework-owned HTTP transport, a CLI command, an MCP tool for external clients, and an A2A tool for other agent-native apps. Optional `link` and `mcpApp` metadata add deep links and MCP Apps UI without a second implementation. |
|
|
160
|
+
| Full agent resources per user | Skills, shared `LEARNINGS.md`, personal `memory/MEMORY.md`, `AGENTS.md`, custom sub-agents, scheduled jobs, and connected MCP servers. All SQL-backed, no dev-box required. See [Agent Resources](/docs/agent-resources). |
|
|
161
|
+
| Drop-in React components | `<AgentPanel />` and `<AgentSidebar />` render chat + resources anywhere in your app. See [Drop-in Agent](/docs/drop-in-agent). |
|
|
162
|
+
| BYO agent chat runtimes | The same chat UI can sit on top of OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI, or your own normalized HTTP stream. See [Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes). |
|
|
163
|
+
| Live sync between agent and UI | Same-process writes stream immediately over `/_agent-native/events`; a lightweight poll keeps serverless, cron, and cross-process writes convergent. Mutating actions invalidate action-backed queries automatically, so agent-created records appear without a manual refresh. See [Live Sync](#polling-sync) below. |
|
|
164
|
+
| Auth, orgs, RBAC | Better Auth with orgs/members/roles is wired in for every template. See [Authentication](/docs/authentication). For more than one user, start with [Organizations, Teams & Permissions](/docs/organizations-teams-permissions). |
|
|
165
|
+
| Context awareness | The agent always knows what the user is looking at through the `navigation` app-state key. See [Context Awareness](/docs/context-awareness). |
|
|
166
|
+
| MCP client + server, both directions | The app ingests MCP servers (local, remote, hub-shared) _and_ exposes its own actions as an MCP server. See [MCP Clients](/docs/mcp-clients) and [MCP Protocol](/docs/mcp-protocol). |
|
|
167
|
+
| Inter-app delegation | Agents in different apps talk over [A2A](/docs/a2a-protocol). Same-origin deploys skip JWT; cross-origin uses a shared `A2A_SECRET`. |
|
|
168
|
+
| Sub-agent teams | Spawn a sub-agent with its own thread and tools, surfaced as a chip inline in chat. See [Agent Teams](/docs/agent-teams). |
|
|
169
|
+
| Portability | Any Drizzle-supported SQL database, any Nitro-compatible host (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun). |
|
|
170
|
+
|
|
150
171
|
## Data in SQL {#data-in-sql}
|
|
151
172
|
|
|
152
173
|
All application state lives in a SQL database via Drizzle ORM. Schemas are provider-agnostic; the supported databases, `DATABASE_URL` config, and portability rules live in [Database](/docs/database).
|
|
153
174
|
|
|
154
175
|
Core SQL stores are auto-created and available in every template:
|
|
155
176
|
|
|
156
|
-
- `application_state
|
|
157
|
-
- `settings
|
|
158
|
-
- `oauth_tokens
|
|
159
|
-
- `sessions
|
|
177
|
+
- `application_state`: ephemeral UI state (navigation, drafts, selections)
|
|
178
|
+
- `settings`: persistent key-value config
|
|
179
|
+
- `oauth_tokens`: OAuth credentials
|
|
180
|
+
- `sessions`: auth sessions
|
|
181
|
+
|
|
182
|
+
Each row below expands to show its fields:
|
|
160
183
|
|
|
161
184
|
<DataModel
|
|
162
185
|
id="doc-block-4w0fu8"
|
|
163
186
|
title="Core SQL stores"
|
|
164
187
|
summary={
|
|
165
|
-
"Auto-created in every template
|
|
188
|
+
"Auto-created in every template. The agent and UI both read and write these."
|
|
166
189
|
}
|
|
167
190
|
entities={[
|
|
168
191
|
{
|
|
@@ -234,6 +257,8 @@ Core SQL stores are auto-created and available in every template:
|
|
|
234
257
|
]}
|
|
235
258
|
/>
|
|
236
259
|
|
|
260
|
+
To add your own domain data, define a table with the same schema helpers used by the core stores above:
|
|
261
|
+
|
|
237
262
|
```ts
|
|
238
263
|
// Drizzle schema for domain data
|
|
239
264
|
import { table, text, integer } from "@agent-native/core/db/schema";
|
|
@@ -247,12 +272,18 @@ export const forms = table("forms", {
|
|
|
247
272
|
});
|
|
248
273
|
```
|
|
249
274
|
|
|
275
|
+
Both you and the agent can inspect that data from the terminal, without a separate SQL client:
|
|
276
|
+
|
|
250
277
|
```bash
|
|
251
278
|
# Core actions for quick database inspection
|
|
252
279
|
pnpm action db-schema # show all tables
|
|
253
280
|
pnpm action db-query --sql "SELECT * FROM forms"
|
|
254
281
|
```
|
|
255
282
|
|
|
283
|
+
`db-schema` prints every table's columns and types. `db-query` runs read-only SQL directly, which is useful for checking an action's writes without opening a database client.
|
|
284
|
+
|
|
285
|
+
<Callout tone="decision">
|
|
286
|
+
|
|
256
287
|
The production agent chat plugin defaults raw SQL tools to read-only
|
|
257
288
|
(`frameworkTools: { database: "read" }`), so agents inspect app-owned data with
|
|
258
289
|
`db-schema` / `db-query` and perform writes through typed app actions. Set
|
|
@@ -268,12 +299,14 @@ chat, and email. See
|
|
|
268
299
|
list, the `"minimal"` preset, and why disabling a group leaves its HTTP routes
|
|
269
300
|
mounted.
|
|
270
301
|
|
|
302
|
+
</Callout>
|
|
303
|
+
|
|
271
304
|
## Agent chat bridge {#agent-chat-bridge}
|
|
272
305
|
|
|
273
|
-
The UI never calls an LLM directly. When a user clicks "Generate chart" or "Write summary", the UI sends a message to the agent via `postMessage`. The agent does the work
|
|
306
|
+
The UI never calls an LLM directly. When a user clicks "Generate chart" or "Write summary", the UI sends a message to the agent via `postMessage`. The agent does the work. It has full conversation history, skills, instructions, and the ability to iterate.
|
|
274
307
|
|
|
275
308
|
```ts
|
|
276
|
-
//
|
|
309
|
+
// Delegate AI work to the agent from a React component
|
|
277
310
|
import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
|
|
278
311
|
sendToAgentChat({
|
|
279
312
|
message: "Generate a chart showing signups by source",
|
|
@@ -282,16 +315,19 @@ sendToAgentChat({
|
|
|
282
315
|
});
|
|
283
316
|
```
|
|
284
317
|
|
|
285
|
-
|
|
318
|
+
In short:
|
|
319
|
+
|
|
320
|
+
- **AI is non-deterministic**: You need conversation flow to give feedback and iterate, not one-shot buttons.
|
|
321
|
+
- **Context matters**: The agent has the app's instructions, skills, and history. An inline call has none of that.
|
|
322
|
+
- **The agent can do more**: It can run actions, browse the web, and chain multiple steps together.
|
|
286
323
|
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
- **External execution.** Because everything goes through the agent and actions, any app can be driven from Slack, Telegram, scheduled jobs, scripts, or another agent via [A2A](/docs/a2a-protocol).
|
|
324
|
+
**[External execution](/docs/a2a-protocol)**
|
|
325
|
+
|
|
326
|
+
Because everything goes through the agent and actions, any app can be driven from Slack, Telegram, scheduled jobs, scripts, or another agent via A2A.
|
|
291
327
|
|
|
292
328
|
## Actions system {#actions-system}
|
|
293
329
|
|
|
294
|
-
When the agent needs to do something complex
|
|
330
|
+
When the agent needs to do something complex, like calling an API, processing data, or querying the database, it runs an **action**. Actions are TypeScript files in `actions/` that export a default `defineAction()`:
|
|
295
331
|
|
|
296
332
|
```ts filename="actions/fetch-data.ts"
|
|
297
333
|
import { defineAction } from "@agent-native/core/action";
|
|
@@ -309,19 +345,30 @@ export default defineAction({
|
|
|
309
345
|
});
|
|
310
346
|
```
|
|
311
347
|
|
|
312
|
-
|
|
348
|
+
This action fetches JSON from a source API and returns it. `defineAction()` wraps the function with a zod schema for its input (`source`), so the framework can validate that input, generate a JSON Schema the agent can call, and infer types for the frontend hook, all from this one definition.
|
|
349
|
+
|
|
350
|
+
One `defineAction()` call reaches five different consumers automatically. The diagram shows the fan-out from a single action; the list below explains what each consumer gets:
|
|
351
|
+
|
|
352
|
+
```mermaid
|
|
353
|
+
graph LR
|
|
354
|
+
A[defineAction] --> B[Agent tool]
|
|
355
|
+
A --> C[Frontend hook]
|
|
356
|
+
A --> D[Framework transport]
|
|
357
|
+
A --> E[CLI command]
|
|
358
|
+
A --> F[MCP or A2A tool]
|
|
359
|
+
```
|
|
313
360
|
|
|
314
|
-
- **Agent tool
|
|
315
|
-
- **Frontend hook
|
|
316
|
-
- **Framework transport
|
|
317
|
-
- **CLI
|
|
318
|
-
- **MCP tool / A2A tool
|
|
361
|
+
- **Agent tool:** the agent sees it with the zod-derived JSON Schema and can call it.
|
|
362
|
+
- **Frontend hook:** `useActionMutation("fetch-data")` with full TypeScript inference.
|
|
363
|
+
- **Framework transport:** auto-mounted behind the client hooks.
|
|
364
|
+
- **CLI:** `pnpm action fetch-data --source=signups` for scripting and agent dev loops.
|
|
365
|
+
- **MCP tool / A2A tool:** when MCP server or A2A is enabled, the same action shows up there too.
|
|
319
366
|
|
|
320
|
-
|
|
367
|
+
Every consumer calls the same underlying function, so there is only one implementation to write and maintain. See [Actions](/docs/actions) for the full reference.
|
|
321
368
|
|
|
322
369
|
## Live sync {#polling-sync}
|
|
323
370
|
|
|
324
|
-
|
|
371
|
+
When the agent changes data, the UI needs to reflect that without a manual refresh. `useDbSync()` is what makes that automatic. Same-process writes stream over `/_agent-native/events`; `/_agent-native/poll` remains the cross-process and serverless fallback. When the agent writes to the database (application state, settings, or domain data), a version counter increments and the client invalidates the relevant React Query caches.
|
|
325
372
|
|
|
326
373
|
```ts
|
|
327
374
|
// Client: subscribe to agent/UI data changes once near the app shell
|
|
@@ -329,6 +376,8 @@ import { useDbSync } from "@agent-native/core/client/hooks";
|
|
|
329
376
|
useDbSync({ queryClient });
|
|
330
377
|
```
|
|
331
378
|
|
|
379
|
+
Call this once, near the root of the app. It subscribes the whole app to change events, so any component using `useActionQuery` or a source-versioned `useQuery` refetches automatically when the data it reads changes.
|
|
380
|
+
|
|
332
381
|
The flow is:
|
|
333
382
|
|
|
334
383
|
1. Agent runs an action that writes to the database
|
|
@@ -337,7 +386,9 @@ The flow is:
|
|
|
337
386
|
4. `useActionQuery` hooks and source-versioned `useQuery` hooks refetch
|
|
338
387
|
5. Components render the new data without a page reload
|
|
339
388
|
|
|
340
|
-
|
|
389
|
+
The diagram traces that same sequence end to end:
|
|
390
|
+
|
|
391
|
+
<Diagram id="doc-block-87e1c3" title="Live sync flow" summary={"An agent write becomes a UI render with no manual refresh. SSE first, polling as the universal fallback."}>
|
|
341
392
|
|
|
342
393
|
```html
|
|
343
394
|
<div class="diagram-sync">
|
|
@@ -384,16 +435,16 @@ The flow is:
|
|
|
384
435
|
|
|
385
436
|
</Diagram>
|
|
386
437
|
|
|
387
|
-
This works in all deployment environments
|
|
438
|
+
This works in all deployment environments, including serverless and edge, because it uses the database instead of in-memory state or file system watchers.
|
|
388
439
|
|
|
389
440
|
## Frames {#frames}
|
|
390
441
|
|
|
391
|
-
A _frame_ is the environment that hosts the agent next to your app
|
|
442
|
+
A _frame_ is the environment that hosts the agent next to your app. Locally that's the embedded panel; in the cloud it's Builder.io's managed surface. See [Frames](/docs/frames).
|
|
392
443
|
|
|
393
444
|
Agent-native apps include an embedded agent panel that provides the AI agent alongside the app UI. This is what makes the architecture work: the agent needs a computer (database, browser, code execution), and the app needs the agent for AI work.
|
|
394
445
|
|
|
395
|
-
- **Embedded Agent Panel
|
|
396
|
-
- **Cloud
|
|
446
|
+
- **Embedded Agent Panel:** Chat and optional CLI terminal built into every app. Supports Claude Code, Codex, Gemini, OpenCode, and Builder.io. Runs locally, free and open source.
|
|
447
|
+
- **Cloud:** Deploy to any cloud with real-time collaboration, visual editing, roles, and permissions. Best for teams.
|
|
397
448
|
|
|
398
449
|
## Context awareness {#context-awareness}
|
|
399
450
|
|
|
@@ -405,7 +456,11 @@ For example, when you open an email thread the UI upserts a row like:
|
|
|
405
456
|
{ "key": "navigation", "value": { "view": "thread", "threadId": "th_abc123" } }
|
|
406
457
|
```
|
|
407
458
|
|
|
408
|
-
|
|
459
|
+
<Callout tone="info">
|
|
460
|
+
|
|
461
|
+
The UI writes this on route change; the agent reads it (via `view-screen`) before taking any action, so it always knows which thread, chart, or slide you're focused on.
|
|
462
|
+
|
|
463
|
+
</Callout>
|
|
409
464
|
|
|
410
465
|
See [Context Awareness](/docs/context-awareness) for the full pattern: navigation state, view-screen, navigate commands, and jitter prevention.
|
|
411
466
|
|
|
@@ -413,7 +468,7 @@ See [Context Awareness](/docs/context-awareness) for the full pattern: navigatio
|
|
|
413
468
|
|
|
414
469
|
Implement a domain operation once as an action; the framework exposes it to every consumer. The same `defineAction()` becomes an agent tool, a typesafe UI hook, an HTTP endpoint, a CLI command, an MCP tool, and an A2A tool, with optional `link`, `mcpApp`, native-widget metadata, or Generative UI wrappers added only when a surface needs richer interaction. Skills and instructions cover behavior.
|
|
415
470
|
|
|
416
|
-
For the full protocol/surface matrix (MCP server and OAuth, MCP Apps, A2A, deep links, native chat widgets, Generative UI, AgentChatRuntime connectors, Agent Web, and the adapter horizon for ACP and A2UI), and for choosing a product shape
|
|
471
|
+
For the full protocol/surface matrix (MCP server and OAuth, MCP Apps, A2A, deep links, native chat widgets, Generative UI, AgentChatRuntime connectors, Agent Web, and the adapter horizon for ACP and A2UI), and for choosing a product shape (chat, inline UI, full app pages, embedded sidecar, automation, or external-agent access), see [Agent Surfaces](/docs/agent-surfaces).
|
|
417
472
|
|
|
418
473
|
## App code and customization {#agent-modifies-code}
|
|
419
474
|
|
|
@@ -430,43 +485,46 @@ without source changes, use [Extensions](/docs/extensions).
|
|
|
430
485
|
Two architectural rules keep apps portable across databases and hosts:
|
|
431
486
|
|
|
432
487
|
- **Database-agnostic.** Write schemas with `@agent-native/core/db/schema` and reads/writes with Drizzle's portable query DSL so the same code runs on any supported provider. Use raw SQL only for additive migrations or one-off maintenance, kept parameterized and dialect-agnostic. See [Database](/docs/database).
|
|
433
|
-
- **Hosting-agnostic.** The server runs on Nitro and compiles to any deployment target. Never use Node-specific APIs (`fs`, `child_process`, `path`) in server routes or plugins, and never assume a persistent server process
|
|
488
|
+
- **Hosting-agnostic.** The server runs on Nitro and compiles to any deployment target. Never use Node-specific APIs (`fs`, `child_process`, `path`) in server routes or plugins, and never assume a persistent server process. Serverless and edge are stateless, so keep all state in SQL. See [Deployment](/docs/deployment).
|
|
434
489
|
|
|
435
490
|
## Agent Resources {#workspace}
|
|
436
491
|
|
|
437
|
-
Every user gets a personal set of **agent resources
|
|
492
|
+
Every user gets a personal set of **agent resources**: instructions, skills, memory, custom sub-agents, scheduled jobs, and connected MCP servers, all stored in SQL rather than files. That makes Claude-Code-level customization viable inside multi-tenant SaaS without spinning up a container per user. See [Agent Resources](/docs/agent-resources).
|
|
438
493
|
|
|
439
494
|
## Related building blocks {#building-blocks}
|
|
440
495
|
|
|
441
496
|
These sit on top of the same contract and have their own deep dives:
|
|
442
497
|
|
|
443
|
-
- **[Dispatch](/docs/dispatch)
|
|
444
|
-
- **[Extensions](/docs/extensions)
|
|
445
|
-
- **[A2A Protocol](/docs/a2a-protocol)
|
|
498
|
+
- **[Dispatch](/docs/dispatch):** the workspace control plane, with a shared inbox, secrets vault, scheduled jobs, and an orchestrator that delegates to specialist apps over A2A.
|
|
499
|
+
- **[Extensions](/docs/extensions):** sandboxed Alpine.js mini-apps the agent creates at runtime, with no source changes or migrations.
|
|
500
|
+
- **[A2A Protocol](/docs/a2a-protocol):** how apps in the same workspace discover and call each other over JSON-RPC.
|
|
446
501
|
|
|
447
|
-
## What
|
|
502
|
+
## What's next {#deep-dives}
|
|
448
503
|
|
|
449
|
-
|
|
504
|
+
<Cards>
|
|
450
505
|
|
|
451
|
-
|
|
452
|
-
- **A full set of agent resources per user.** Skills, shared `LEARNINGS.md`, personal `memory/MEMORY.md`, `AGENTS.md`, custom sub-agents, scheduled jobs, connected MCP servers — all SQL-backed, no dev-box required. See [Agent Resources](/docs/agent-resources).
|
|
453
|
-
- **Drop-in React components.** `<AgentPanel />` and `<AgentSidebar />` render chat + resources anywhere in your app. See [Drop-in Agent](/docs/drop-in-agent).
|
|
454
|
-
- **BYO agent chat runtimes.** The same chat UI can sit on top of OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI, or your own normalized HTTP stream. See [Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes).
|
|
455
|
-
- **Live sync between agent and UI.** Same-process writes stream immediately over `/_agent-native/events`; a lightweight poll keeps serverless, cron, and cross-process writes convergent. Mutating actions invalidate action-backed queries automatically, so agent-created records appear without a manual refresh. See [Live Sync](#polling-sync) below.
|
|
456
|
-
- **Auth, orgs, RBAC.** Better Auth with orgs/members/roles is wired in for every template. See [Authentication](/docs/authentication). Building for more than one user? Start with [Organizations, Teams & Permissions](/docs/organizations-teams-permissions).
|
|
457
|
-
- **Context awareness.** The agent always knows what the user is looking at through the `navigation` app-state key. See [Context Awareness](/docs/context-awareness).
|
|
458
|
-
- **MCP client + server, both directions.** The app ingests MCP servers (local, remote, hub-shared) _and_ exposes its own actions as an MCP server. See [MCP Clients](/docs/mcp-clients) and [MCP Protocol](/docs/mcp-protocol).
|
|
459
|
-
- **Inter-app delegation.** Agents in different apps talk over [A2A](/docs/a2a-protocol). Same-origin deploys skip JWT; cross-origin uses a shared `A2A_SECRET`.
|
|
460
|
-
- **Sub-agent teams.** Spawn a sub-agent with its own thread and tools, surfaced as a chip inline in chat. See [Agent Teams](/docs/agent-teams).
|
|
461
|
-
- **Portability.** Any Drizzle-supported SQL database, any Nitro-compatible host (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun).
|
|
506
|
+
### [What Is Agent-Native?](/docs/what-is-agent-native)
|
|
462
507
|
|
|
463
|
-
|
|
508
|
+
The vision and philosophy behind these rules.
|
|
464
509
|
|
|
465
|
-
|
|
510
|
+
### [Context Awareness](/docs/context-awareness)
|
|
511
|
+
|
|
512
|
+
Navigation state, view-screen, and navigate commands in depth.
|
|
513
|
+
|
|
514
|
+
### [Skills Guide](/docs/skills-guide)
|
|
515
|
+
|
|
516
|
+
Framework skills, domain skills, and creating custom skills.
|
|
517
|
+
|
|
518
|
+
### [Native Chat UI](/docs/native-chat-ui)
|
|
519
|
+
|
|
520
|
+
Action-declared tables, charts, and BYO runtime posture.
|
|
521
|
+
|
|
522
|
+
### [Agent Surfaces](/docs/agent-surfaces)
|
|
523
|
+
|
|
524
|
+
Chat, native inline UI, full app pages, embedded sidecar, automation, and external-agent paths.
|
|
525
|
+
|
|
526
|
+
### [A2A Protocol](/docs/a2a-protocol)
|
|
527
|
+
|
|
528
|
+
Agent-to-agent communication.
|
|
466
529
|
|
|
467
|
-
|
|
468
|
-
- [**Context Awareness**](/docs/context-awareness) — navigation state, view-screen, and navigate commands in depth
|
|
469
|
-
- [**Skills Guide**](/docs/skills-guide) — framework skills, domain skills, and creating custom skills
|
|
470
|
-
- [**Native Chat UI**](/docs/native-chat-ui) — action-declared tables, charts, and BYO runtime posture
|
|
471
|
-
- [**Agent Surfaces**](/docs/agent-surfaces) — chat, native inline UI, full app pages, embedded sidecar, automation, and external-agent paths
|
|
472
|
-
- [**A2A Protocol**](/docs/a2a-protocol) — agent-to-agent communication
|
|
530
|
+
</Cards>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@agent-native/core",
|
|
3
|
-
"version": "0.151.
|
|
3
|
+
"version": "0.151.2",
|
|
4
4
|
"description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
|
|
5
5
|
"homepage": "https://github.com/BuilderIO/agent-native#readme",
|
|
6
6
|
"bugs": {
|