@agent-native/core 0.144.0 → 0.144.2

package/docs/content/getting-started-actions.mdx

@@ -1,84 +1,44 @@
 ---
 title: "Add an Action"
-description: "Define your first action and render its result as a UI component directly inside the chat transcript."
+description: "Define your first action and render its result as a chart directly inside the chat."
 ---
 
 # Add an Action
 
-This is part two of the Getting Started series. In [Getting Started](/docs/getting-started) you created a Chat app and connected an AI engine. Here you'll define your first action and render its result inline in chat.
+This is part two of the Getting Started series. In [Getting Started](/docs/getting-started)
+you created a Chat app. Here you'll define a typed text analyzer and render its
+result in the chat.
 
 ## Add an action {#add-an-action}
 
-An action is a typed operation that both your agent and your UI can call. It's
-how the agent does things in your app. Actions live in the `actions/` directory
-and can be triggered from chat, from React components, from the CLI, or on a
-schedule. You define them once and call them from anywhere.
+An action is a typed operation that both the agent and your UI can call. Actions
+live in the `actions/` directory and are the shared operation surface for chat,
+React components, the CLI, and other callers.
 
-### Try the starter action
-
-The Chat template includes a `hello` action at `actions/hello.ts`:
-
-```ts filename="actions/hello.ts"
-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}!` };
-  },
-});
-```
-
-Run it from the terminal (inside your `my-app/` directory):
-
-```bash
-pnpm action hello --name Alice
-```
-
-Or open your app at `http://localhost:8080` and ask the agent in the chat there:
-
-> Use the hello action with the name Alice.
-
-### Add your own action
-
-Replace the starter action with the first real operation in your domain. This example
-counts words, sentences, and paragraphs in any text you pass it. It computes
-everything locally, so there's nothing to configure and no external service to connect.
-
-Create a new file called `analyze-text.ts` in your `actions/` directory:
+Create `actions/analyze-text.ts`:
 
 ```ts filename="actions/analyze-text.ts"
 import { defineAction } from "@agent-native/core/action";
+import { ACTION_CHAT_UI_DATA_CHART_RENDERER } from "@agent-native/core/action-ui";
+import {
+  createDataChartWidgetResult,
+  dataChartWidgetResultSchema,
+} from "@agent-native/core/data-widgets";
 import { z } from "zod";
 
-const textStatsSchema = z.object({
-  title: z.string(),
-  points: z.array(z.object({ label: z.string(), value: z.number() })),
-});
-
 export default defineAction({
   description: "Count words, sentences, and paragraphs in a block of text.",
   schema: z.object({
-    text: z
-      .string()
-      .default(
-        "The quick brown fox jumps over the lazy dog. Pack my box with five dozen liquor jugs.",
-      ),
+    text: z.string().default("The quick brown fox jumps over the lazy dog."),
   }),
-  outputSchema: textStatsSchema,
+  outputSchema: dataChartWidgetResultSchema,
   chatUI: {
-    renderer: "text.stats-chart",
+    renderer: ACTION_CHAT_UI_DATA_CHART_RENDERER,
     title: "Text stats",
   },
   readOnly: true,
-  run: async ({ text }) => ({
-    title: "Text statistics",
-    points: [
+  run: async ({ text }) => {
+    const points = [
       { label: "Characters", value: text.length },
       { label: "Words", value: text.split(/\s+/).filter(Boolean).length },
       {
@@ -89,147 +49,36 @@ export default defineAction({
         label: "Paragraphs",
         value: text.split(/\n\n+/).filter(Boolean).length,
       },
-    ],
-  }),
+    ];
+
+    return createDataChartWidgetResult({
+      title: "Text statistics",
+      chartSeries: {
+        type: "bar",
+        xKey: "label",
+        series: [{ key: "value", label: "Count" }],
+        data: points,
+      },
+    });
+  },
 });
 ```
 
-Try it from the terminal:
+Run it from the terminal:
 
 ```bash
 pnpm action analyze-text --text "Hello world. How are you today?"
 ```
 
-Or open your app at `http://localhost:8080` and ask the agent in the chat there:
+Or ask the agent in chat:
 
 > Run the analyze-text action on "Hello world. How are you today?"
 
-#### Define once, call from anywhere
-
-This action is now reachable from chat, React hooks, CLI, HTTP, MCP, A2A,
-scheduled jobs, and webhooks.
-
-TIP: Any time you want the agent to call a specific action without ambiguity, phrasing it as "Run the `<action-name>` action" is most reliable. Natural-language prompts work well once the agent has enough context about your app's domain. For a brand-new app with no data or context yet, explicit is safer.
-
-## Render the result inline {#render-inline}
-
-When the agent runs `analyze-text`, it returns structured data: a title and an
-array of counts. By default the agent will describe that data in prose: "The
-text has 9 words, 2 sentences..." and so on. That works, but you can
-also render the result as a real UI component (a bar chart, a table, a card)
-directly inside the chat transcript, right where the agent responded.
-
-This is what `chatUI.renderer` in the action does. It's a label that says "when
-this action's result appears in chat, hand it to this React component instead of
-summarizing it in text." The component receives the validated action output as
-props and renders whatever you want.
-
-In the next step, you'll create `app/chat-renderers.tsx`, but first, add one import line
-to `app/root.tsx` so it runs on startup:
-
-```ts filename="app/root.tsx"
-import "./chat-renderers";
-```
-
-Add it alongside your other imports at the top of the file. That's the only
-change to `root.tsx`. The import just ensures the file runs and registers the
-renderer. Now create the renderer file:
-
-```tsx filename="app/chat-renderers.tsx"
-import {
-  registerActionChatRenderer,
-  type ToolRendererProps,
-} from "@agent-native/core/client/chat";
-
-type TextStatsResult = {
-  title: string;
-  points: Array<{ label: string; value: number }>;
-};
-
-const MAX_BAR_PX = 80;
-
-function TextStatsChart({ context }: ToolRendererProps) {
-  const result = context.resultJson as TextStatsResult;
-  const max = Math.max(...result.points.map((point) => point.value), 1);
-  return (
-    <section className="rounded-lg border bg-card p-4">
-      <h3 className="text-sm font-medium">{result.title}</h3>
-      <div className="mt-4 flex items-end gap-2">
-        {result.points.map((point) => (
-          <div
-            key={point.label}
-            className="flex flex-1 flex-col items-center gap-2"
-          >
-            <div
-              className="w-full rounded-t bg-blue-500"
-              style={{
-                height: `${Math.max(Math.round((point.value / max) * MAX_BAR_PX), 2)}px`,
-              }}
-            />
-            <span className="text-xs text-muted-foreground">{point.label}</span>
-          </div>
-        ))}
-      </div>
-    </section>
-  );
-}
-
-registerActionChatRenderer({
-  id: "text.stats-chart",
-  renderer: "text.stats-chart",
-  Component: TextStatsChart,
-});
-```
-
-Once the renderer is registered, the agent's response looks like this. Instead
-of a paragraph of text, your React component renders directly inside the chat
-transcript:
-
-<WireframeBlock id="doc-block-inline-result-wireframe">
-  <Screen
-    surface="desktop"
-    html={
-      "<div style='min-height:340px;box-sizing:border-box;padding:24px;display:flex;justify-content:center;align-items:center;background:var(--wf-bg)'><div style='width:min(640px,100%);display:flex;flex-direction:column;gap:14px'><div class='wf-card' data-rough style='align-self:flex-end;max-width:70%;padding:12px 14px'><strong>User</strong><p style='margin:6px 0 0'>Run the analyze-text action on \"Hello world. How are you today?\"</p></div><div class='wf-card' data-rough style='align-self:flex-start;width:min(480px,100%);padding:14px'><strong>Agent</strong><p class='wf-muted' style='margin:6px 0 12px'>Rendered with text.stats-chart.</p><section class='wf-card' data-rough style='padding:14px'><h3 style='margin:0 0 12px;font-size:14px'>Text statistics</h3><div data-rough='line:bottom' style='height:104px;display:flex;align-items:end;gap:8px;border-bottom:1.4px solid var(--wf-line);padding-bottom:4px'><div style='flex:1;display:flex;flex-direction:column;align-items:center;gap:6px'><div data-rough style='height:80px;width:100%;background:color-mix(in srgb, var(--wf-accent) 36%, transparent);border:1.4px solid var(--wf-accent);border-radius:8px 8px 3px 3px'></div><span class='wf-muted'>Characters</span></div><div style='flex:1;display:flex;flex-direction:column;align-items:center;gap:6px'><div data-rough style='height:18px;width:100%;background:color-mix(in srgb, var(--wf-accent) 30%, transparent);border:1.4px solid var(--wf-accent);border-radius:8px 8px 3px 3px'></div><span class='wf-muted'>Words</span></div><div style='flex:1;display:flex;flex-direction:column;align-items:center;gap:6px'><div data-rough style='height:2px;width:100%;background:color-mix(in srgb, var(--wf-accent) 24%, transparent);border:1.4px solid var(--wf-accent);border-radius:8px 8px 3px 3px'></div><span class='wf-muted'>Sentences</span></div><div style='flex:1;display:flex;flex-direction:column;align-items:center;gap:6px'><div data-rough style='height:2px;width:100%;background:color-mix(in srgb, var(--wf-accent) 24%, transparent);border:1.4px solid var(--wf-accent);border-radius:8px 8px 3px 3px'></div><span class='wf-muted'>Paragraphs</span></div></div></section></div></div></div>"
-    }
-  />
-</WireframeBlock>
-
-Use this step when the result belongs where the agent is speaking:
-
-- setup summaries
-- short reports
-- approvals
-- tables or charts small enough to inspect inline
-- links into durable app views
-
-For reusable generic outputs, the framework also ships built-in
-`data-chart` and `data-table` renderers, plus `data-insights` for combined
-summary/chart/table cards. See [Native Chat UI](/docs/native-chat-ui). For
-temporary controls the agent creates at runtime, see
-[Generative UI](/docs/generative-ui).
-
-## What's next {#next}
-
-<Cards>
-
-### [Persist Data in SQL](/docs/getting-started-database)
-
-Save action results to a database so the agent can reference them across
-conversations. Next in the series.
-
-### [Actions](/docs/actions)
-
-Schemas, auth, approvals, hooks, and transport — the full reference for what
-actions can do.
-
-### [Native Chat UI](/docs/native-chat-ui)
-
-Built-in renderers for tables, charts, and typed cards — beyond the custom
-renderer you just built.
-
-### [Key Concepts](/docs/key-concepts)
+The built-in `data-chart` renderer turns the structured result into a chart in
+the transcript. There is no renderer file or `app/root.tsx` import to add. For
+custom native components, see [Native Chat UI](/docs/native-chat-ui).
 
-The architecture underneath this tutorial: SQL, actions, live sync, and context
-awareness.
+## Continue
 
-</Cards>
+Continue with [Persist Data in SQL](/docs/getting-started-database) to save
+analysis results for later.

package/docs/content/getting-started-database.mdx

@@ -5,25 +5,20 @@ description: "Save action results to a SQL database so the agent can reference t
 
 # Persist Data in SQL
 
-This is part three of the Getting Started series. In [Add an Action](/docs/getting-started-actions) you defined the `analyze-text` action and rendered its result inline in chat. Here you'll persist those results to a SQL database.
+This is part three of the Getting Started series. In [Add an Action](/docs/getting-started-actions)
+you defined `analyze-text`. Here you'll add a table and two actions so the
+results persist.
 
-## Persist data in SQL {#persist-data}
+## Add a table {#persist-data}
 
-Right now, every time the agent runs `analyze-text` the result appears in chat
-and then disappears. There's nothing to look back at, nothing the agent can
-reference later, and no way to build a page around the data. Persisting to SQL
-fixes that: the agent writes results to a table, and both the agent and your UI
-can read them back at any time.
+The Chat template uses a local SQLite file by default, so no database server is
+needed for this tutorial. Add these three server files:
 
-Agent-Native apps have a SQL database available by default: SQLite locally,
-and your configured provider (Postgres, Turso/libSQL, Cloudflare D1) in
-production.
+1. `server/plugins/db.ts` creates the table with an additive migration.
+2. `server/db/schema.ts` describes the table for typed queries.
+3. `server/db/index.ts` creates the app's typed database client.
 
-### Wire up the database plugin
-
-The Chat template doesn't include a database plugin by default. Create
-`server/plugins/db.ts` to initialize it. This is what runs migrations and
-makes the database available to your actions:
+Create `server/plugins/db.ts`:
 
 ```ts filename="server/plugins/db.ts"
 import { runMigrations } from "@agent-native/core/db";
@@ -32,12 +27,15 @@ export default runMigrations(
   [
     {
       version: 1,
+      name: "create-text-analyses",
       sql: `CREATE TABLE IF NOT EXISTS text_analyses (
         id TEXT PRIMARY KEY,
         input TEXT NOT NULL,
         char_count INTEGER NOT NULL,
         word_count INTEGER NOT NULL,
         sentence_count INTEGER NOT NULL,
+        paragraph_count INTEGER NOT NULL,
+        owner_email TEXT NOT NULL,
         created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
       )`,
     },
@@ -46,14 +44,7 @@ export default runMigrations(
 );
 ```
 
-Each entry in the array is an additive migration. When you add new columns or
-tables later, append a new version object. Never edit existing ones.
-
-### Define the schema
-
-Create `server/db/schema.ts`. The `server/db/` directory may not exist yet,
-so create it if needed. This file describes your tables using typed helpers so
-your actions get full TypeScript autocomplete:
+Create `server/db/schema.ts`:
 
 ```ts filename="server/db/schema.ts"
 import { integer, now, table, text } from "@agent-native/core/db/schema";
@@ -64,190 +55,115 @@ export const textAnalyses = table("text_analyses", {
   charCount: integer("char_count").notNull(),
   wordCount: integer("word_count").notNull(),
   sentenceCount: integer("sentence_count").notNull(),
+  paragraphCount: integer("paragraph_count").notNull(),
+  ownerEmail: text("owner_email").notNull(),
   createdAt: text("created_at").notNull().default(now()),
 });
 ```
 
-Use the framework schema helpers (`table`, `text`, `integer`, `now`) rather than
-`sqliteTable`, `pgTable`, or dialect-specific imports. They pick the configured
-SQL backend automatically, so the same schema runs locally on SQLite and in
-production on any supported provider.
+Create `server/db/index.ts`:
 
-After adding both files, restart the dev server so the migration runs:
+```ts filename="server/db/index.ts"
+import { createGetDb } from "@agent-native/core/db";
+import * as schema from "./schema.js";
 
-```bash
-pnpm dev
-```
-
-Look for these two lines in the terminal output. They confirm the table was created:
-
-```
-[db] Applying 1 migration(s) on SQLite/libsql…
-[db] Applied migration v1 (1 statement)
+export const getDb = createGetDb(schema);
+export { schema };
 ```
 
-The `NitroViteError` lines, `BETTER_AUTH_SECRET` warning, and
-`SECRETS_ENCRYPTION_KEY` warning that also appear are normal for local dev and
-can be ignored.
+Restart `pnpm dev` once so the migration runs. Keep future migrations additive,
+and give each one a new `version` and `name`.
 
-### Add actions for the table
+## Add save and list actions
 
-Now create the action files that read and write the table. These go in your
-`actions/` directory, the same place as `hello.ts` and `analyze-text.ts`. You
-create them yourself, one file per operation. The agent and your UI will call
-them the same way they call any other action.
-
-**`actions/save-text-analysis.ts`** writes a result row to the database.
-Call this after running `analyze-text` to make the result durable:
+Keep `analyze-text` read-only and make saving explicit with a separate action.
+Create `actions/save-text-analysis.ts`:
 
 ```ts filename="actions/save-text-analysis.ts"
 import { defineAction } from "@agent-native/core/action";
-import { getDbExec } from "@agent-native/core/db";
 import { z } from "zod";
 
+import { getDb, schema } from "../server/db/index.js";
+
 export default defineAction({
   description: "Save a text analysis result to the database.",
   schema: z.object({
-    input: z.string(),
+    input: z.string().min(1),
     charCount: z.number(),
     wordCount: z.number(),
     sentenceCount: z.number(),
+    paragraphCount: z.number(),
   }),
-  run: async ({ input, charCount, wordCount, sentenceCount }) => {
+  run: async (
+    { input, charCount, wordCount, sentenceCount, paragraphCount },
+    ctx,
+  ) => {
+    const ownerEmail = ctx?.userEmail;
+    if (!ownerEmail) throw new Error("Sign in before saving analyses.");
+
     const id = crypto.randomUUID();
-    await getDbExec().execute({
-      sql: `INSERT INTO text_analyses (id, input, char_count, word_count, sentence_count)
-            VALUES (?, ?, ?, ?, ?)`,
-      args: [id, input, charCount, wordCount, sentenceCount],
+    await getDb().insert(schema.textAnalyses).values({
+      id,
+      input,
+      charCount,
+      wordCount,
+      sentenceCount,
+      paragraphCount,
+      ownerEmail,
     });
+
     return { id };
   },
 });
 ```
 
-**`actions/list-text-analyses.ts`** reads all saved results. The agent can
-call this to summarize past analyses, and your UI can use it to populate a page:
+Create `actions/list-text-analyses.ts`:
 
 ```ts filename="actions/list-text-analyses.ts"
 import { defineAction } from "@agent-native/core/action";
-import { getDbExec } from "@agent-native/core/db";
+import { desc, eq } from "drizzle-orm";
 import { z } from "zod";
 
-export default defineAction({
-  description: "List all saved text analyses, newest first.",
-  schema: z.object({}),
-  run: async () => {
-    const result = await getDbExec().execute(
-      `SELECT id, input, char_count, word_count, sentence_count, created_at
-       FROM text_analyses
-       ORDER BY created_at DESC`,
-    );
-    return result.rows;
-  },
-});
-```
-
-**`actions/delete-text-analysis.ts`** removes a row by id:
-
-```ts filename="actions/delete-text-analysis.ts"
-import { defineAction } from "@agent-native/core/action";
-import { getDbExec } from "@agent-native/core/db";
-import { z } from "zod";
+import { getDb, schema } from "../server/db/index.js";
 
 export default defineAction({
-  description: "Delete a saved text analysis by id.",
-  schema: z.object({ id: z.string() }),
-  run: async ({ id }) => {
-    await getDbExec().execute({
-      sql: `DELETE FROM text_analyses WHERE id = ?`,
-      args: [id],
-    });
-    return { deleted: id };
+  description: "List the signed-in user's saved text analyses, newest first.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (_, ctx) => {
+    const ownerEmail = ctx?.userEmail;
+    if (!ownerEmail) throw new Error("Sign in before listing analyses.");
+
+    return getDb()
+      .select({
+        id: schema.textAnalyses.id,
+        input: schema.textAnalyses.input,
+        charCount: schema.textAnalyses.charCount,
+        wordCount: schema.textAnalyses.wordCount,
+        sentenceCount: schema.textAnalyses.sentenceCount,
+        paragraphCount: schema.textAnalyses.paragraphCount,
+        createdAt: schema.textAnalyses.createdAt,
+      })
+      .from(schema.textAnalyses)
+      .where(eq(schema.textAnalyses.ownerEmail, ownerEmail))
+      .orderBy(desc(schema.textAnalyses.createdAt));
   },
 });
 ```
 
-Once these files are saved the dev server picks them up automatically. No
-restart needed. Try listing analyses from the terminal:
-
-```bash
-pnpm action list-text-analyses
-```
-
-You should see an empty array. The table exists and the action works; there's
-just nothing saved yet:
-
-```
-[]
-```
-
-Data is saved to `data/app.db`, a SQLite file in your project directory that
-gets created automatically on first run. In production you'd point
-`DATABASE_URL` at a hosted database instead, but locally this file is all you
-need.
-
-To save something, first run `analyze-text` to get the counts:
-
-```bash
-pnpm action analyze-text --text "Hello world"
-```
-
-You'll see output like:
-
-```
-{
-  title: 'Text statistics',
-  points: [
-    { label: 'Characters', value: 11 },
-    { label: 'Words', value: 2 },
-    { label: 'Sentences', value: 1 },
-    { label: 'Paragraphs', value: 1 }
-  ]
-}
-```
-
-Then pass those values to `save-text-analysis`:
-
-```bash
-pnpm action save-text-analysis \
-  --input "Hello world" \
-  --charCount 11 \
-  --wordCount 2 \
-  --sentenceCount 1
-```
-
-Now run `list-text-analyses` again and you'll see the saved row:
-
-```bash
-pnpm action list-text-analyses
-```
-
-Or ask the agent in the chat at `http://localhost:8080` to do both steps at once:
-
-> Run analyze-text on "Hello world", then save the result.
-
-## What's next {#next}
-
-<Cards>
-
-### [Add a Page](/docs/getting-started-pages)
-
-Build a React route that displays your saved analyses and wire it into the
-sidebar. Next in the series.
-
-### [Database](/docs/database)
+The actions use the typed Drizzle client for app reads and writes. Raw SQL is
+only needed here for the additive migration.
 
-Migrations, schema helpers, and production database setup — the full reference
-for SQL in Agent Native.
+## Try it
 
-### [Actions](/docs/actions)
+In chat, ask the agent to do the whole flow:
 
-Schemas, auth, approvals, hooks, and transport — the full reference for what
-actions can do.
+> Run analyze-text on "Hello world", save the result with save-text-analysis, then list my saved text analyses.
 
-### [Key Concepts](/docs/key-concepts)
+The saved row is now available to the agent and to the page you'll build next.
 
-The architecture underneath this tutorial: SQL, actions, live sync, and context
-awareness.
+## Continue
 
-</Cards>
+Continue with [Add a Page](/docs/getting-started-pages) to display the saved
+rows in a route.