Skip to content

BuilderIO/agent-native / packages/core/src/templates/headless/.agents/skills/actions

actions

Verified

How to create and run agent actions. Actions are the single source of truth for app operations — the agent calls them as tools and frontend code calls them through client hooks. Use when creating a new action, adding an API integration, or wiring up frontend data fetching.

Agent Actions

Rule

Actions in actions/ are the single source of truth for app operations. The agent calls them as tools, the frontend calls them through useActionQuery / useActionMutation, and the framework owns the HTTP transport behind those hooks — no duplicate /api/ routes.

Before creating any custom route for app data, check actions/ and the action table in AGENTS.md. An action already exists? Call it directly. Missing? Create or update a defineAction. Stop trigger: about to add a file under server/routes/api/ (or middleware to guard one)? Check it against the exception list in Custom /api/ Routes below first — even if you already started the route.

Keep Actions Deterministic

An action may call a provider API, validate data, and persist records without being an AI feature — keep it deterministic, focused, and independently useful to the agent. Don't put LLM calls or a second model runtime in app actions.

The sanctioned model-backed exception is @agent-native/core/decisions for capability-aware classification and scoring, and it returns a result without performing or authorizing the selected action.

When a workflow is research, analysis, generation, recommendation, or synthesis — or spans several provider calls and writes — route it to the AgentSidebar via sendToAgentChat({ openSidebar: true }) and let the agent orchestrate focused actions instead of hiding an AI-shaped workflow behind one opaque generate-*/create-* action just because its implementation happens to be deterministic.

How to Create an Action

One action per file, default-exported. The filename is the action name (kebab-case): actions/list-meals.ts is the list-meals action. Don't put several defineActions as named exports in one file — the registry keys actions by filename and only the default export is registered, so extra named exports never become callable and won't match .generated/action-types.d.ts.

// actions/list-meals.ts
import { z } from "zod";
import { defineAction } from "@agent-native/core/action";
import { getDb } from "../server/db/index.js";
import { meals } from "../server/db/schema.js";

export default defineAction({
  description: "List all meals",
  schema: z.object({}),
  http: { method: "GET" },
  run: async () => {
    const db = getDb();
    const rows = await db.select().from(meals);
    return rows; // Return objects/arrays, NOT JSON.stringify()
  },
});

schema (Zod or Standard Schema-compatible) gives runtime validation, TS inference for run() args, and an auto-generated JSON Schema for the tool. Write it so an agent can call the tool correctly on the first try: .describe() every param and state enum values and the default in that text (z.enum(["open","closed"]).default("open").describe('Filter status: "open" or "closed"; defaults to "open"')); mark a field .optional() only when the action truly tolerates its absence — a silent default the caller cannot see is a required field in disguise; name the primary id the same way across a family (create-/get-/update-/delete-<thing> all take id, not a mix of id and <thing>Id), and if one action must differ, accept both with .or(); give nested objects a real schema, never a prose description; keep the one-line description complete enough to call the tool without a second lookup, because compact catalogs and tool-search show only that line. Use z.coerce.number() for numeric HTTP params, but write an explicit boolean parser instead of z.coerce.boolean(), which treats "false" as truthy.

Some models (GPT-6 Luna in strict mode) send every optional field they aren't using, filled with null, [], false, or an enum's only value, so a call must mean the same with that padding as without it. Make an optional switch act only when true (fixedCanvas: true, not responsive: false), and never give [] a meaning of its own such as "none".

Use Drizzle's PostgreSQL query builder, not raw SQL/getDbExec() or direct driver imports, unless Drizzle can't express the query. Never hardcode API keys/tokens/secrets - read via readAppSecret / resolveCredential / OAuth helpers; process.env is deploy-level config only.

Decision order: existing action → extend/create a defineAction → custom route as last resort (Custom /api/ Routes below). Actions are already callable by agents, CLIs, hooks, HTTP, and MCP/A2A — don't wrap them in an umbrella REST API.

Keep the Action Surface Small and Orthogonal

Every agent-exposed action is a tool in the model's context window; more tools degrades tool-selection quality. Add the fewest, most orthogonal actions that cover the capability.

  • One orthogonal update per resource, not one per field — update-<thing> taking an optional-fields patch, not update-<thing>-name + update-<thing>-order + …
  • Reach for a generic escape hatch before minting a new read action — the provider-api-catalog/docs/request trio for provider data (references/provider-apis.md), db-query for ad hoc app-data reads in dev.
  • agentTool: false hides a UI-only/programmatic action from the model while keeping it frontend/HTTP-callable — not toolCallable: false, which only blocks the sandboxed extension bridge and leaves the action visible everywhere else; reserve that one for high-blast-radius operations.
  • Delete or hide stale actions once you confirm neither the UI nor an agent workflow uses them.

Key Actions — One Index, Every Surface

Document the app's primary actions in the AGENTS.md action table. For first-turn loading, add those action names to the plugin's initialToolNames (INITIAL_TOOL_NAMES in some templates), or mark the full starter set deferLoading: false on the actions. When one action opts into per-action eager loading, unmarked actions are deferred; the remaining actions stay discoverable through tool-search. When users name an action's job in words its name and description lack ("auto-archive rule", "canned reply"), add those words as searchHints: tool-search ranks them just below the name and never shows them to the model.

When MCP is enabled, its Key tools line is generated from mcp.keyToolNames ?? initialToolNames and filtered to the actions served on that surface. A configured mcp.keyToolNames overrides the advertised MCP/WebMCP key list; it does not change the in-app agent's first-turn list. Keep the advertised subset consistent with the primary actions in the AGENTS.md table and the external catalog; the table may also document other in-app actions. Do not hand-write another action list in mcp.instructions, a skill, or an external skill; describe when to use actions there.

The http Option

Controls HTTP exposure:

ValueBehaviorUse for
(omitted)POST /_agent-native/actions/:nameWrite operations (default)
{ method: "GET" }GET /_agent-native/actions/:nameRead-only queries
{ method: "PUT"/"DELETE" }matching verbUpdate / delete
{ method: "GET", path: "x" }custom route pathNon-default path
falsenever exposed as HTTPnavigate, view-screen, internal

Mutating actions (anything but GET) auto-refresh the UI on success — don't call refresh-screen after a normal action. Overrides (readOnly, parallelSafe) and exact trigger rules: references/action-fields.md.

Saves That Can Race

An action that writes a value a person or another agent may also be changing checks what it read:

  • Server: saveIfCurrent from @agent-native/core/save-conflict/server takes read, write and expectedRevision. It checks and writes in one statement, confirms exactly one row changed, ignores a repeat of a save it already applied, and throws one typed conflict carrying the current value. Use saveRevisionOf(value) as the revision, so no migration is needed and any writer moves it. Set requireRevision for a write that replaces a whole value: a caller that read nothing gets the conflict, with the current value, and can redo its edit.
  • Reads return the same revision, and the schema takes it as expectedRevision with EXPECTED_REVISION_DESCRIPTION.
  • Browser: saveWithMerge from @agent-native/core/save-conflict merges field by field on a conflict and saves again, so most apps need no merge code. useSaveConflictPrompt from @agent-native/toolkit/app/save-conflict is its resolveOverlap: a person sees it only when both writers changed the same field, and can get the other version back.
  • Agents never see the prompt. They get the conflict and redo the edit on details.current.

Outcomes are counted (save_outcome_counts, and save_conflict_prompt in the browser), so prompts that could have been automatic show up.

Names That Must Stay Unique

When a record's name must be unique in its parent (a file in a design, say), back the rule with a unique index and pick names with nextFreeName from @agent-native/core/free-name: name.html, then name-2.html, name-3.html (a slug whose alphabet has no - passes { separator: "_" }). Don't write another copy of that loop.

  • Refusing: throw nameTaken(record, name, suggestion) from @agent-native/core/free-name/server. It is a 409 name_taken whose details.suggestion is free; pass { noWrite: true } from an action that declares it as a no-write error. Don't put internal ids in the message.
  • Creating from the UI: let the caller ask for the next free name instead of a refusal (Design's create-file takes ifNameTaken: "next-free"), pick it on the server under the same lock as the insert, and return the saved name. Two tabs that both pick x-copy.html from their own list then both save.
  • When the picker can't see every name the index covers (other members' private records, say), let the insert claim it: on isUniqueViolation from @agent-native/core/db, mark that name taken, pick again and retry a few times, then refuse. CRM's create-crm-list does this for list slugs.
  • Agents get the refusal and retry with details.suggestion, or edit the existing record if that was the intent.

Return Values

Return structured data (objects, arrays), never JSON.stringify() — the framework serializes the response and only tries to parse a returned string as JSON, which isn't the same contract.

run: async (args) => await fetchEvents(args.from, args.to); // good
run: async (args) => JSON.stringify(await fetchEvents(...)); // bad

A create/update result is read by more than the caller. These keys are well-known and survive result truncation:

  • id — the created or updated record. Pair it with a pure, synchronous link builder on the action (link: (result) => ({ url: buildDeepLink({ app, view, params: { id: result.id } }), label })) so MCP hosts and the desktop app surface an "Open …" deep link that lands in the editing view focused on the record; returning url/urlPath in the result works too.
  • nextRequiredAction — the name of the next tool to call when the operation is one step of a flow the agent should keep driving (nextRequiredAction: "update-slide"). Never phrase it as waiting for the user: an MCP/WebMCP/A2A caller cannot receive an in-app answer. The agent loop keeps this field in continuation prompts even when the rest of a large result is dropped, and MCP callers see it as Next: ….
  • message/summary — the one-line status external callers read; everything else stays in the structured result.
  • designSystem — when a record can link a brand or design system, expose it as designSystem: AgentDesignSystemContext | null via loadAgentDesignSystemContext(id, getDesignSystemAction) from core's shared design-system-agent-context. Reads get the bounded summary (scope: "summary", with a next line naming the full read); only the create action and get-design-system itself pass { full: true }. status: "unavailable" is not null: keep the id and the message. Print it in text results with formatAgentDesignSystemContext; do not name the field anything else.

For actions that attach a chatUI renderer, use chatUI.projectResult to return only the small structured fields the renderer needs. chatUI.when is evaluated against the full successful result first; the projection is used live and saved for interrupted-run recovery.

An action that hands control back to the user (question form, intake dialog) sets endsTurn: true; that hides it from MCP/WebMCP/A2A unless mcpTool: true is explicit — references/action-fields.md. For external-agent integrations, use the external-agents documentation slug listed by agent-native-docs.

An action the app's agent can call that the app's MCP catalog doesn't already serve needs a decision, or outside agents can reach it only through ask_app: mcpTool: true serves it to them (add a test that calls it over MCP), and mcpTool: false keeps it in-app, with a comment on that line saying why.

Every new action declares outputSchema: it types the action's return and is enforced strictly by default (guard:action-output-schema). Declare its failure codes with defineActionErrors and fail through them. Reach for _agentImages (attach images the agent can see), authorize (gate who may call it), or needsApproval (require human sign-off per call) only when the action needs that guarantee — examples in references/action-fields.md.

To test an action, start with checkActionProperties(action, { context }) from @agent-native/core/action-properties. It generates inputs from the zod schema, and fails on any throw that is not an action contract error, on a return its outputSchema rejects, and on an invalid input that reaches run. It needs fast-check as a devDependency, and it throws UnsupportedSchemaError for a schema shape it cannot generate unless you pass an override.

Write receipts

A write action that can check its own effect returns a plain-object result with a reserved _receipt, so the final answer is reconciled with what the write did, not with the model's reading of a JSON string that may be truncated:

import type { WriteReceipt } from "@agent-native/core/action";

const _receipt: WriteReceipt = {
  changed: true,
  verified: false,
  summary: "Saved; panel 3 returned no rows.",
  checks: [{ id: "panel-3", ok: false, detail: "0 rows" }],
};
return { id, _receipt };

verified is true (the effect was observed), false (checked and did not hold), or "unverified" (could not be checked); checks and warnings are optional. The agent loop reads the receipt before the result is stringified and truncated (summary 200 chars, 8 checks, 5 warnings):

  • verified: false or changed: false forces one honest-reconciliation retry per turn: the model must say what the receipt shows and may not call the change visible or working. If the retry is spent, the answer is prefixed with the receipt block.
  • verified: "unverified" only prefixes that note; no retry.
  • A receipt that is present but malformed counts as unverified, never clean. changed: false also records the call as completedSideEffect: false, unless a write nested in the action also entered its handler: a receipt, like retrySafe, speaks only for the action's own write.
  • Set subject (the stable target, such as a dashboard id) so a later changed: true, verified: true receipt for the same subject can supersede an earlier flagged one in the same turn. When the earlier receipt had failing or unverified checks, the later receipts (from this action or another that writes the same subject) must carry an ok: true check with the same id for each; a receipt without checks never clears one that had them. A flagged receipt with no failing checks is superseded only by the same action. Receipts without a subject are never superseded.

A receipt is not an error channel. A write that did not achieve the requested state throws (fail()); return changed: false only for a benign no-op, such as the record already being in the requested state.

Failed Writes

The framework classifies a failed action from the writes it saw the call make: every database write (any statement that is not a read such as SELECT, SET or LOCK, and not the framework's own schema setup) and every fetch that is not GET, HEAD or OPTIONS. A rejection raised before any of those is "nothing saved", however it is thrown (fail(), a plain Error, a library error).

  • Declare writes it cannot see. Before a disk write, child process, node:http/https request or vendor SDK call, call noteExternalWrite("<channel>"), e.g. noteExternalWrite("local-disk"). Without it, a failed call that already wrote looks retry-safe. guard:no-unobserved-writes fails new code that skips the call. A temp-only or retry-idempotent write can say why with // observed-write-ok: <reason> instead.
  • withoutWriteObservation(fn) is only for framework bookkeeping (an audit row, a change marker, analytics) or a write a retry provably cannot repeat, such as one keyed by a deterministic id or dedup key. Never wrap the write the call exists to make. await the work inside fn: a Drizzle query builder only runs when awaited, after fn has returned, so withoutWriteObservation(() => db.insert(t).values(v)) exempts nothing.
  • retrySafe says this action's own write is safe to run again, so a failure after that write is not "unknown". It covers only this action's write. Don't set it on an action that appends, sends or charges unless the input carries an idempotency key.
  • NoWriteError is an override, not a requirement: most rejections need no label, but it wins over an observed write when the only write before the rejection is one a retry harmlessly repeats (such as uploads nobody has referenced yet), and the framework accepts it only for the call that raised it and only when no nested write action entered that call's handler.
  • A call that times out or loses its result stays "unknown", because it may still be running.

Frontend Hooks

Import from focused @agent-native/core/client/* entry points; the broad @agent-native/core/client barrel is deprecated. Use action hooks, not hand-written fetch("/_agent-native/actions/...").

import { useActionQuery, useActionMutation, callAction } from "@agent-native/core/client/hooks";

const { data: meals } = useActionQuery("list-meals", { date: "2025-01-01" }); // GET, types auto-inferred
const { mutate } = useActionMutation("log-meal");                             // POST/PUT/DELETE
mutate({ name: "Salad", calories: 350 });
const people = await callAction("search-people", { query }, { method: "GET" }); // imperative (debounce, prefetch)

Don't add manual generics like useActionQuery<Meal[]>(...) — types come from .generated/action-types.d.ts. Mutations auto-invalidate all ["action"] query keys, so GET queries refetch. A revisit paints the persisted result for the signed-in user and org before that refetch; see references/action-fields.md for persistInBrowser: false.

A failed useActionMutation write shows one shared toast (WriteFailureToaster, mounted by AppProviders) when nothing else reports it. mutate toasts unless an onError (hook-level or per call) handles the failure; mutateAsync toasts only when its rejection ends up unhandled. errorNotification picks the mode: "auto" (default), "shared" (toast even beside an onError that only rolls back or logs), or "caller" (never: background saves, deliberate swallows, call sites that render the error themselves). errorLabel is an already-translated title. A fail() with a 4xx status shows its message as the toast text, a 5xx shows only the title because the server masks its text, and a 401 stays silent. For a write that is not a useActionMutation (a raw fetch upload, a swallowed catch), call reportWriteFailure(error, { label }) from @agent-native/core/client/write-failure.

When a query result varies by viewer or another client context that is not part of the action arguments, pass that stable context through queryKeyScope. It partitions only the local query cache; it is not sent to the action and never replaces server-side authorization.

How to Run (Agent)

pnpm action log-meal --name "Salad" --calories 350

CLI flags become action input fields (--key value or --key=value); the runner does not read or write files for --input or --output. The default template dispatches through core's runScript() in actions/run.ts. Action names are lowercase-with-hyphens (pnpm action my-action → actions/my-action.ts).

For a needsApproval action, the CLI checks parsed/defaulted input with caller cli. An interactive terminal shows the action and arguments and asks y/N (only y or yes runs). Without both stdin and stdout TTYs, ask the person to approve the specific call, then rerun the exact original pnpm action arguments with --approved appended. Never add --approved before the person approves. This reserved flag is removed before action input parsing and is harmless on ungated actions. See references/action-fields.md for approval details.

Custom /api/ Routes

Complete exception list — justified only when the caller isn't your own UI/agent, or the payload isn't JSON: file uploads (actions take JSON, not multipart), streaming (SSE/chunked needing direct H3 control), webhooks, OAuth callbacks (fixed redirect URL patterns), public unauthenticated endpoints (SEO/OG images, share links), binary/non-JSON responses.

Everything else — CRUD, settings, search, list/detail reads, auth state, anything the UI fetches as JSON — is an action. Needing middleware to scope a route to the current user is itself a signal it should be an action. Existing template /api/* CRUD routes are being migrated; do not add new ones.

Do / Don't

  • Do keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in AGENTS.md once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
  • Do use fail(message, { errorCode, statusCode }) for user-friendly errors and import primitives from @agent-native/core(/action) instead of redefining them; use the core upload-image action or uploadFile() for durable images/files — never base64 into SQL, markdown, or action results.
  • Do signal failure by throwing, using fail() for expected caller-readable failures. Never return { error: ... } as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
  • Do use fail() rather than a bare Error for caller-readable failures. It carries the action's message, errorCode, and details to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
  • Do give fail() the status that matches the cause: it defaults to 400, and useActionQuery retries only 429, 502, 503, and 504. Mutations do not retry; use transient statuses only for retryable failures.
  • Do validate inputs before the first write. A rejection raised before any write the framework can see is "nothing saved", so the agent can fix its request and retry. Don't reorder code just to add labels. See Failed Writes.
  • Do render actionErrorMessage(error) ?? yourCopy in UI, never bare error.message. The message keeps an Action <name> failed: prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and undefined when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
  • Do pass a real errorCode when the agent should branch on the failure rather than re-read it. Codes other than the default action_failed are appended to the tool result as (errorCode: not_found), on both the in-app agent and MCP. details follow as an Error details: {...} JSON line, and as structuredContent.error over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
  • Don't re-export actions as REST — /_agent-native/actions/:name is already the REST surface; duplicating it under /api/* hides the operation from agents.
  • Don't reach for provider integrations, authorize, needsApproval, or _agentImages without checking references/ first — each has sharp edges covered there, not here.

Troubleshooting

  • Action not found / type mismatch — filename must match the command (pnpm action foo-bar → actions/foo-bar.ts), and the action must be the file's default export. Multiple defineAction named exports in one file register only the default; split them into one file each.
  • Args not parsing — use --key value / --key=value; boolean flags are --flag (sets "true").
  • Frontend 405 — http.method doesn't match the hook (useActionQuery for GET, useActionMutation for POST/PUT/DELETE).
  • Frontend gets undefined — action must return structured data, not JSON.stringify().

References

  • references/provider-apis.md — wiring a credentialed provider (HubSpot, Gong, Slack, …) for querying, reporting, or cross-source research.
  • references/action-fields.md — outputSchema, authorize, needsApproval, _agentImages, and exact auto-refresh rules.
  • references/examples.md — a second worked example and legacy bare-export patterns.

Related Skills

  • storing-data — Actions read/write data in SQL
  • delegate-to-agent — The agent invokes actions via pnpm action <name>
  • real-time-sync — Database writes from actions trigger change events to update the UI
  • adding-a-feature — Actions are area 2 of the four-area checklist
  • client-methods — Client code uses named helpers/hooks instead of raw REST calls
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall